DiscordStatus
Guias / Guides

Criando uma assinatura

Para criar uma assinatura, utilize o endpoint de criação de assinaturas.

POST /v3/subscriptions
Confira a referência completa deste endpoint

Antes da criação, certifique-se de que:

  • o cliente já está cadastrado;
  • a forma de pagamento desejada é compatível com a recorrência;
  • a data do primeiro vencimento foi definida corretamente.
{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "BOLETO",
  "nextDueDate": "2023-10-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "description": "Assinatura Plano Pró"
}

Principais parâmetros

Embora todos os parâmetros estejam documentados na referência da API, alguns campos possuem impacto direto no comportamento da assinatura:

  • customer — identifica o cliente que receberá as cobranças.
  • billingType — define a forma de pagamento utilizada na recorrência.
  • nextDueDate — determina a data da primeira cobrança da assinatura.
  • value — valor de cada recorrência.
  • cycle — periodicidade utilizada para geração das cobranças.
  • description — descrição apresentada nas cobranças geradas.

As periodicidades disponíveis são:

  • WEEKLY — semanal;
  • BIWEEKLY — quinzenal;
  • MONTHLY — mensal;
  • QUARTERLY — trimestral;
  • SEMIANNUALLY — semestral;
  • YEARLY — anual.
📘

Importante

O campo nextDueDate representa apenas a data da primeira cobrança. As próximas cobranças serão geradas automaticamente conforme a periodicidade definida em cycle.

Como funciona a criação

A assinatura funciona como um agendador de cobranças.

Após sua criação, o Asaas passa a gerar automaticamente novas cobranças conforme a periodicidade configurada.

Fluxo simplificado:

Criar assinatura
        ↓
Assinatura criada
        ↓
Asaas gera
novas cobranças
automaticamente
        ↓
Cliente realiza
o pagamento
        ↓
Webhook informa
o resultado

Ao criar a assinatura, a API retorna um identificador semelhante a:

sub_VXJBYgP2u0eO

Esse identificador deve ser armazenado pela aplicação, pois será utilizado em consultas, alterações, cancelamentos e recuperação das cobranças da recorrência.

Como acompanhar os pagamentos

A assinatura não muda automaticamente para "paga".

Quem recebe pagamentos são as cobranças geradas por ela.

Para acompanhar esse processo, recomenda-se utilizar o webhook de cobranças.

Quando uma nova cobrança é criada, será enviado o evento:

PAYMENT_CREATED

O objeto da cobrança conterá o campo subscription, permitindo identificar a qual assinatura ela pertence.

Após o pagamento da cobrança, novos eventos financeiros serão enviados normalmente, como:

  • PAYMENT_RECEIVED para pagamentos liquidados;
  • demais eventos financeiros conforme a forma de pagamento utilizada.

Também é possível consultar todas as cobranças geradas pela assinatura utilizando:

GET /v3/subscriptions/{id}/payments
Confira a referência completa deste endpoint

Alterando uma assinatura

É possível atualizar as informações de assinaturas com forma de pagamento BOLETO ou PIX.

POST /v3/subscriptions/{id}
Veja a referência completa deste endpoint

Por padrão, alterações como:

  • valor;
  • descrição;
  • forma de pagamento;
  • outras configurações da assinatura;

afetam apenas as cobranças que ainda serão geradas futuramente.

As cobranças já existentes permanecem inalteradas.

Caso seja necessário atualizar também as cobranças pendentes já criadas, utilize:

updatePendingPayments: true

Nesse cenário, todas as cobranças pendentes da assinatura serão atualizadas conforme os novos dados enviados.

📘

Importante

Apenas cobranças pendentes podem ser atualizadas através desse parâmetro. Cobranças já pagas, vencidas ou canceladas não são alteradas.

Recuperando as cobranças da assinatura

Diferentemente das cobranças parceladas, uma assinatura não retorna imediatamente o identificador da primeira cobrança.

Isso ocorre porque a assinatura representa apenas a recorrência, enquanto as cobranças são geradas automaticamente pelo Asaas.

Para recuperar as cobranças criadas, utilize:

GET /v3/subscriptions/{id}/payments
Veja a referência completa deste endpoint

A resposta retornará todas as cobranças pertencentes à assinatura, juntamente com seus respectivos status.

Boas práticas

📘

Recomendado

  • Armazene o identificador (id) da assinatura logo após sua criação.
  • Utilize Webhooks para acompanhar o ciclo financeiro das cobranças.
  • Não considere a criação da assinatura como confirmação de pagamento.
  • Utilize o parâmetro updatePendingPayments apenas quando desejar atualizar cobranças pendentes.
  • Consulte periodicamente as cobranças da assinatura caso sua integração realize conciliação financeira.

Impactos operacionais

Como novas cobranças são criadas automaticamente ao longo do tempo, integrações que realizam:

  • sincronização financeira;
  • emissão automática de notas fiscais;
  • envio de notificações;
  • conciliação;
  • processamento de Webhooks;

devem considerar que novas cobranças poderão surgir sem novas chamadas para criação da assinatura.

Por esse motivo, recomenda-se acompanhar os eventos financeiros através dos Webhooks, em vez de depender apenas de consultas periódicas.

Próximos passos

Após implementar a criação de assinaturas, recomendamos consultar:

  • Criando assinatura com cartão de crédito.
  • Recuperar uma assinatura.
  • Listar cobranças de uma assinatura.
  • Atualizar assinatura existente.
  • Remover assinatura.
  • Webhook para cobranças.
  • FAQ de Assinaturas.