Assinaturas recorrentes
Lista, exporta, detalha e cancela as assinaturas dos produtos do seller.
Estas quatro rotas dão ao seller a visão de suas assinaturas (o módulo de pagamentos recorrentes). O seller só vê e cancela: pausar, retomar e repetir cobrança são ações da loja. Para o painel com totais, veja Painel e cobranças.
Listar assinaturas
Uma assinatura cobra o cartão salvo do cliente a cada ciclo até ele cancelar. Lista as assinaturas dos produtos do seller com filtros e paginação.
/api/v1/vendor/recurring/subscriptionsSellerAssinaturas dos produtos do seller
Cabeçalhos
AuthorizationstringobrigatórioBearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).Parâmetros de consulta
statusstringactivepausedpast_duesuspendedcancelledqstringproduct_iduuidcustomer_iduuidnext_fromstringYYYY-MM-DD.next_tostringYYYY-MM-DD.overdueboolean1 ou true: só ativas cuja próxima data já passou.sortstringnextnext ordena pela próxima data; sem isso, mais novas primeiro.pageintegerpadrão: 1per_pageintegerpadrão: 25Exemplo de requisição
Resposta
Campos da resposta
itemsobject[]Assinaturas da página.
idstringsub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.kindstringsubscriptionscheduledstatusstringactive, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.customer_namestringcustomer_emailstringproduct_namestringfrequencystringsemanal, quinzenal, mensal...).cycle_daysintegerquantityintegerprice_centsintegerprice_formattedstringR$ 49,90.next_datestringYYYY-MM-DD. Omitido se não houver.last_datestringYYYY-MM-DD. Omitido se não houver.card_last_fourstringcancellation_reasonstringretry_countintegerlast_attempt_atstringsuspended_atstringcreated_atstringactionsobjectQuais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.
cancelbooleanpausebooleanresumebooleanskipbooleanretrybooleanpaginationobjectpage, per_page, total, total_pages.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Token ausente, inválido, expirado ou revogado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller. | {"error":"insufficient permissions"} |
| 403 | O módulo recurring-payments está desligado nesta loja. | {"error":"module_disabled","module":"recurring-payments"} |
| 403 | O usuário não está vinculado a nenhum seller. | {"error":"no vendor account"} |
Exportar assinaturas em CSV
Mesmos filtros da listagem (sem page/per_page), até 5.000 linhas. Devolve um arquivo CSV em UTF-8 com BOM, nome assinaturas-AAAAMMDD.csv. Células que começam com =, +, - ou @ recebem um apóstrofo na frente para evitar execução de fórmula no Excel.
/api/v1/vendor/recurring/subscriptions/export.csvSellerBaixar as assinaturas filtradas em CSV
Cabeçalhos
AuthorizationstringobrigatórioBearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).Parâmetros de consulta
statusstringactivepausedpast_duesuspendedcancelledqstringproduct_iduuidcustomer_iduuidnext_fromstringYYYY-MM-DD.next_tostringYYYY-MM-DD.overdueboolean1 ou true: só ativas cuja próxima data já passou.Exemplo de requisição
Resposta
Colunas do arquivo
Cliente, E-mail, Produto, Status, Frequencia, Valor, Proxima cobranca, Ultima cobranca, Criada emcsvValor já vem formatado (R$ 49,90).Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Token ausente, inválido, expirado ou revogado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller. | {"error":"insufficient permissions"} |
| 403 | O módulo recurring-payments está desligado nesta loja. | {"error":"module_disabled","module":"recurring-payments"} |
| 403 | O usuário não está vinculado a nenhum seller. | {"error":"no vendor account"} |
Ver assinatura
Devolve a assinatura e, junto, as tentativas de cobrança, a linha do tempo e o termo que o cliente aceitou. Só sub:... serve nesta rota.
/api/v1/vendor/recurring/subscriptions/{id}SellerAssinatura com cobranças e linha do tempo
Cabeçalhos
AuthorizationstringobrigatórioBearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).Parâmetros de caminho
idstringobrigatóriosub:<uuid> obtida na listagem. Os dois pontos podem ir como estão.Exemplo de requisição
Resposta
Campos da resposta
idstringsub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.kindstringsubscriptionscheduledstatusstringactive, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.customer_namestringcustomer_emailstringproduct_namestringfrequencystringsemanal, quinzenal, mensal...).cycle_daysintegerquantityintegerprice_centsintegerprice_formattedstringR$ 49,90.next_datestringYYYY-MM-DD. Omitido se não houver.last_datestringYYYY-MM-DD. Omitido se não houver.card_last_fourstringcancellation_reasonstringretry_countintegerlast_attempt_atstringsuspended_atstringcreated_atstringactionsobjectQuais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.
cancelbooleanpausebooleanresumebooleanskipbooleanretrybooleanchargesobject[]Tentativas de cobrança do registro.
idstringrefstringsub:..., sch:..., app:...).kindstringcustomer_namestringproduct_namestringamount_centsintegeramount_formattedstringstatusstringpaid, failed, pending (compras programadas também usam captured).billing_datestringYYYY-MM-DD.attemptintegerorder_numberstringorder_iduuidcreated_atstringcan_retrybooleanfalse para o seller (repetir cobrança é da loja).logobject[]at, event, detail.termsobjectname, version, accepted_at, ip_address. Omitido se não há.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | Referência malformada (por exemplo sub: com UUID inválido). | {"error":"invalid reference"} |
| 404 | Registro inexistente, de outro seller ou de outro tipo (um sch: na rota de assinaturas). | {"error":"not found"} |
| 401 | Token ausente, inválido, expirado ou revogado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller. | {"error":"insufficient permissions"} |
| 403 | O módulo recurring-payments está desligado nesta loja. | {"error":"module_disabled","module":"recurring-payments"} |
| 403 | O usuário não está vinculado a nenhum seller. | {"error":"no vendor account"} |
Cancelar assinatura
Cancela a assinatura (cancelled), grava motivo e data, e devolve o registro atualizado. É a única ação que o seller pode fazer sobre assinaturas. Não há reativação por aqui. A cobrança em andamento não é desfeita.
/api/v1/vendor/recurring/subscriptions/{id}/cancelSellerCancelar uma assinatura do seller
Cabeçalhos
AuthorizationstringobrigatórioBearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).Content-Typestringobrigatórioapplication/json.Parâmetros de caminho
idstringobrigatóriosub:<uuid> obtida na listagem. Os dois pontos podem ir como estão.Corpo da requisição
reasonstringExemplo de requisição
Resposta
Campos da resposta
idstringsub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.kindstringsubscriptionscheduledstatusstringactive, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.customer_namestringcustomer_emailstringproduct_namestringfrequencystringsemanal, quinzenal, mensal...).cycle_daysintegerquantityintegerprice_centsintegerprice_formattedstringR$ 49,90.next_datestringYYYY-MM-DD. Omitido se não houver.last_datestringYYYY-MM-DD. Omitido se não houver.card_last_fourstringcancellation_reasonstringretry_countintegerlast_attempt_atstringsuspended_atstringcreated_atstringactionsobjectQuais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.
cancelbooleanpausebooleanresumebooleanskipbooleanretrybooleanchargesobject[]Tentativas de cobrança do registro.
idstringrefstringsub:..., sch:..., app:...).kindstringcustomer_namestringproduct_namestringamount_centsintegeramount_formattedstringstatusstringpaid, failed, pending (compras programadas também usam captured).billing_datestringYYYY-MM-DD.attemptintegerorder_numberstringorder_iduuidcreated_atstringcan_retrybooleanfalse para o seller (repetir cobrança é da loja).logobject[]at, event, detail.termsobjectname, version, accepted_at, ip_address. Omitido se não há.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | Referência malformada. | {"error":"invalid reference"} |
| 404 | Registro inexistente, de outro seller ou de outro tipo (um sch: na rota de assinaturas). | {"error":"not found"} |
| 409 | Já está cancelada. | {"error":"action not allowed in the current status"} |
| 401 | Token ausente, inválido, expirado ou revogado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller. | {"error":"insufficient permissions"} |
| 403 | O módulo recurring-payments está desligado nesta loja. | {"error":"module_disabled","module":"recurring-payments"} |
| 403 | O usuário não está vinculado a nenhum seller. | {"error":"no vendor account"} |