Cria a assinatura de um cliente final a um plano. Ela nasce em PENDING_ENROLLMENT e só é cobrada depois da adesão do cartão.
Fluxo completo da recorrência por cartão
POST /v1/acquiring/subscription-plans— crie o plano (uma vez).POST /v1/acquiring/subscriptions— crie a assinatura do cliente (esta rota). Guarde oid.POST /v1/acquiring/card-sessionscompurpose=ENROLLMENTesubscriptionId= oidda assinatura. Abra ahostedCardUrlpara o cliente digitar o cartão. A adesão faz uma validação de valor zero (não cobra), salva o cartão e deixa a assinaturaACTIVE(webhooksubscription.activated).- A Autra cobra sozinha: gera a fatura 3 dias antes de cada vencimento e cobra o cartão salvo no dia, sem CVV. Recusa → até 3 tentativas (vencimento +
cardRetryDaysdo plano); esgotadas, a fatura ficaOVERDUEe a assinaturaPAST_DUE. Acompanhe pelos webhooksinvoice.*esubscription.*(domíniosubscriptions) ou porGET .../invoices.
Idempotência: externalRef é a sua chave, única por estabelecimento. Repetir o POST com o mesmo externalRef, plano e cliente devolve a assinatura já criada (200, sem duplicar); com outro plano ou cliente, EXTERNAL_REF_IN_USE.
1º vencimento: firstDueDate (hoje ou depois, horário de Brasília) ou, se omitido, a regra do plano. O dia do 1º vencimento vira o dia-âncora das cobranças seguintes (planos FIXED_DAY usam o billingDay).
O documento do cliente volta mascarado na resposta e nos webhooks.
Erros — corpo {"errors":[{"code":"...","msg":"..."}]}; msg detalha o campo quando é validação:
code | HTTP | Quando acontece | O que fazer |
|---|---|---|---|
INVALID_INPUT | 400 | Campo inválido ou fora do limite; msg diz qual e a regra. | Corrija o campo indicado. |
INVALID_JSON | 400 | Corpo não é um objeto JSON válido. | Corrija o JSON. |
MISSING_DOCUMENT_ID | 400 | Estabelecimento não informado. | Envie o header X-Merchant-Document (ou documentId). |
TENANT_REQUIRED | 400 | A credencial não identifica o tenant. | Gere o token com as credenciais do seu tenant (POST /v1/oauth/token). |
FEATURE_DISABLED | 403 | O módulo de assinaturas não está habilitado para o tenant. | Peça a habilitação à Autra. |
MERCHANT_NOT_FOUND | 404 | O documento não é de um estabelecimento do seu tenant. | Confira o CPF/CNPJ do estabelecimento. |
PLAN_NOT_FOUND | 404 | Plano não existe neste estabelecimento. | Confira o id (planos são por estabelecimento). |
EXTERNAL_REF_IN_USE | 409 | externalRef já usado por outra assinatura (outro plano ou cliente). | Use outro externalRef ou consulte a existente com GET ?externalRef=. |
PAYLOAD_TOO_LARGE | 413 | Corpo acima de 64 KiB. | Reduza o corpo (o metadata aceita até 4 KiB). |
INVALID_DOCUMENT | 422 | Documento do estabelecimento malformado. | CPF com 11 ou CNPJ com 14 dígitos, só números. |
PLAN_ARCHIVED | 422 | O plano está arquivado. | Use um plano ACTIVE. |
INTERNAL_ERROR | 500 | Falha interna. | Tente de novo; persistindo, fale com o suporte com o horário da chamada. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||