Como gerar novas cobranças de uma assinatura

No ambiente Sandbox, é possível testar a geração de novas cobranças de uma assinatura utilizando o recurso de geração de carnê.

Esse mecanismo permite antecipar a criação das cobranças futuras vinculadas à assinatura, facilitando a homologação de integrações que dependem da existência dessas cobranças para validação de fluxos financeiros, notificações, webhooks e processos de cobrança.

Quando utilizar

Este recurso é recomendado quando sua integração precisa:

• validar cobranças futuras de uma assinatura;
• testar webhooks relacionados às cobranças geradas;
• homologar fluxos de recorrência;
• validar regras de negócio dependentes das cobranças da assinatura;
• testar relatórios e conciliações financeiras envolvendo cobranças recorrentes.

Como funciona

Uma assinatura cria suas cobranças de forma gradual ao longo do tempo, conforme a recorrência configurada.

Ao gerar o carnê da assinatura, o Asaas antecipa a criação dessas cobranças até uma data limite definida na solicitação.

Fluxo simplificado:

Assinatura criada
        ↓
Gerar carnê
        ↓
Informar data final
        ↓
Criar cobranças futuras
        ↓
Validar integração

Data final do carnê

A geração do carnê depende da data final informada na solicitação.

Essa data determina até qual período as cobranças serão criadas.

Exemplo:

• carnê gerado até dezembro → cria cobranças até dezembro;
• carnê gerado até junho do próximo ano → cria cobranças até junho do próximo ano.

Quanto maior o período informado, maior será a quantidade de cobranças geradas.

Comportamento esperado

Ao gerar o carnê:

• as cobranças futuras da assinatura são criadas automaticamente;
• as cobranças passam a ficar disponíveis para consulta pela API;
• os fluxos relacionados à assinatura podem ser homologados antecipadamente;
• a assinatura original permanece ativa e continua seguindo sua recorrência normalmente.

A geração do carnê não representa um pagamento e não altera o status das cobranças criadas.

Exemplo de homologação

Uma homologação típica pode seguir o fluxo abaixo:

Criar assinatura
        ↓
Gerar carnê
até dezembro
        ↓
Criar cobranças futuras
        ↓
Consultar cobranças
        ↓
Validar webhooks
        ↓
Validar integração

Esse processo permite testar toda a jornada de recorrência sem necessidade de aguardar a geração natural das próximas cobranças.

Boas práticas

📘

Recomendado

• Utilize o recurso apenas para homologação dos fluxos necessários.
• Valide se a quantidade de cobranças geradas corresponde ao período informado.
• Teste os webhooks relacionados às cobranças criadas.
• Consulte as cobranças geradas após a execução da operação.
• Realize os testes em Sandbox antes da utilização em produção.

Impactos operacionais

A geração do carnê pode aumentar significativamente a quantidade de cobranças disponíveis na conta.

Por esse motivo, integrações que realizam:

• consultas de cobranças;
• sincronizações periódicas;
• relatórios financeiros;
• conciliações;
• processamento de webhooks;

devem considerar que múltiplas cobranças poderão ser criadas simultaneamente após a execução da operação.

Esse comportamento é especialmente útil para validar cenários de alto volume durante a homologação.

Possíveis dificuldades

Caso as cobranças esperadas não sejam geradas, verifique:

• se a assinatura está ativa;
• se a data final informada é posterior às cobranças já existentes;
• se a autenticação está sendo realizada corretamente;
• se a assinatura utilizada pertence ao ambiente Sandbox.

Referência da API

Veja a chamada para gerar o carnê da assinatura:

Gerar carnê de assinatura