Guia de Assinaturas

Confira o guia de assinaturas para mais informações.

Endpoint responsável por listar todas as cobranças geradas por uma assinatura específica.

Esse recurso permite acompanhar o histórico financeiro da recorrência, consultar o status das cobranças já criadas e identificar quais mensalidades já foram pagas, permanecem pendentes ou foram canceladas.

Cada assinatura funciona como um gerador de cobranças. Este endpoint retorna justamente essas cobranças criadas ao longo do ciclo de vida da assinatura.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• consultar as cobranças geradas por uma assinatura;
• verificar se determinada mensalidade já foi criada;
• acompanhar o status financeiro das cobranças da recorrência;
• localizar cobranças pagas, pendentes ou vencidas;
• realizar conciliações financeiras;
• recuperar os identificadores das cobranças pertencentes à assinatura.

Caso seja necessário consultar apenas os dados da assinatura, utilize o endpoint Recuperar uma única assinatura.

Parâmetros importantes

Além do identificador da assinatura (id), este endpoint possui o seguinte filtro:

• status — retorna apenas cobranças com o status informado.

Esse filtro pode ser utilizado para reduzir o volume de dados retornados quando sua integração estiver interessada apenas em cobranças específicas, como pendentes ou vencidas.

Como funciona

Após localizar a assinatura pelo identificador informado, o Asaas retorna todas as cobranças já geradas para aquela recorrência.

Fluxo simplificado:

Assinatura
        ↓
Cobranças geradas
        ↓
Consultar cobranças
        ↓
Receber histórico da recorrência

As cobranças retornadas representam apenas as mensalidades já criadas.

Cobranças futuras ainda não geradas não aparecerão na listagem.

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• somente cobranças já geradas são retornadas;
• cobranças futuras ainda não criadas não fazem parte da resposta;
• cada cobrança possui seu próprio ciclo de vida e status;
• alterações realizadas na assinatura afetam apenas cobranças futuras, salvo quando utilizado o parâmetro updatePendingPayments durante a atualização da assinatura;
• cobranças removidas em consequência da remoção da assinatura deixam de ser retornadas.

Exemplos de uso

Consultar todas as cobranças da assinatura:

GET /v3/subscriptions/{id}/payments

Consultar apenas cobranças pendentes:

GET /v3/subscriptions/{id}/payments?status=PENDING

Consultar apenas cobranças recebidas:

GET /v3/subscriptions/{id}/payments?status=RECEIVED

Boas práticas

Erros comuns

400 Bad Request

Pode ocorrer quando algum parâmetro é informado com valor inválido.

401 Unauthorized

Ocorre quando a API Key é inválida ou pertence ao ambiente incorreto.

403 Forbidden

Pode ocorrer quando uma requisição GET é enviada com body preenchido. Os filtros devem ser enviados como query params.

404 Not Found

Ocorre quando a assinatura informada não existe ou não pertence à conta autenticada.

Impactos operacionais

Assinaturas com longo tempo de utilização podem possuir um grande número de cobranças associadas.

Para evitar processamento desnecessário na aplicação:

• consulte apenas quando necessário;
• utilize filtros de status sempre que possível;
• armazene os identificadores das cobranças já processadas;
• prefira utilizar Webhooks para acompanhar alterações de status em tempo real.

Conteúdos relacionados

• Criar assinatura
• Recuperar uma única assinatura
• Atualizar assinatura
• Remover assinatura
• Webhooks de cobrança
• Eventos de assinatura