Como gerar novas cobranças de uma assinatura

No Sandbox, você pode utilizar a geração de carnê para antecipar a criação das cobranças futuras de uma assinatura.

Esse recurso permite homologar consultas, conciliações e outros processos que dependem da existência dessas cobranças, sem aguardar a geração natural de cada ciclo.

📘
Ao concluir este guia, você terá gerado e consultado as cobranças futuras de uma assinatura.

Quando utilizar

Use este recurso para testar:

cobranças futuras de uma assinatura;
fluxos de recorrência;
consultas e sincronizações de cobranças;
relatórios e conciliações;
regras de negócio relacionadas aos próximos ciclos;
eventos aplicáveis às cobranças geradas.

Antes de começar

Você precisa:

Ter uma conta e uma chave de API de Sandbox.
Criar uma assinatura.
Armazenar o ID da assinatura.
Definir até qual data as cobranças devem ser geradas.
Utilizar o endpoint de geração de carnê.

Consulte Gerar carnê de assinatura.

Como funciona

Normalmente, as cobranças de uma assinatura são criadas gradualmente, de acordo com o ciclo configurado.

Ao gerar o carnê, o Asaas antecipa a criação das cobranças até a data final informada.

Criar assinatura
        ↓
Gerar carnê
        ↓
Informar a data final
        ↓
Criar cobranças futuras
        ↓
Consultar e validar os resultados

1. Crie uma assinatura

Crie a assinatura com o ciclo, o valor e a data de vencimento desejados.

Armazene o ID retornado, pois ele será utilizado para gerar o carnê.

2. Gere o carnê

Utilize o endpoint de geração de carnê e informe a data limite para a criação das cobranças.

A data determina até qual período as cobranças serão antecipadas.

Por exemplo:

uma data final em dezembro gera cobranças até esse período;
uma data final em junho do próximo ano gera cobranças até junho;
períodos maiores podem gerar mais cobranças em uma única operação.

⚠️
Escolha a data final de acordo com o cenário que precisa homologar.
A geração de um período extenso pode criar muitas cobranças na conta Sandbox.

3. Valide as cobranças geradas

Após executar a operação:

consulte as cobranças vinculadas à assinatura;
confira a quantidade criada;
valide os vencimentos e valores;
confirme se não houve duplicidade;
processe os eventos aplicáveis;
valide relatórios, sincronizações e conciliações.

Gerar cobranças
        ↓
Consultar pela API
        ↓
Validar quantidade e vencimentos
        ↓
Processar eventos aplicáveis
        ↓
Atualizar a aplicação

Comportamento esperado

Ao gerar o carnê:

as cobranças futuras são criadas até a data informada;
as cobranças ficam disponíveis para consulta;
a assinatura continua seguindo sua recorrência;
nenhum pagamento é realizado;
o status das cobranças não é alterado para pago.

📘
A geração do carnê antecipa a criação das cobranças, mas não antecipa seus pagamentos.

Impacto na integração

A operação pode criar várias cobranças simultaneamente.

Sua aplicação deve estar preparada para:

processar múltiplos registros;
evitar duplicidades durante sincronizações;
paginar consultas quando necessário;
relacionar cada cobrança à assinatura;
lidar com eventos recebidos em sequência;
atualizar relatórios e conciliações.

Caso as cobranças não sejam geradas

Verifique se:

a assinatura pertence ao Sandbox;
o ID da assinatura está correto;
a assinatura está ativa;
a data final é posterior às cobranças existentes;
a URL e a chave de API pertencem ao Sandbox;
os parâmetros obrigatórios foram enviados corretamente.

Checklist de homologação

Antes de considerar o fluxo homologado, confirme se sua aplicação:

identifica as cobranças pela assinatura;
processa várias cobranças sem duplicidade;
valida valores e vencimentos;
trata paginação nas consultas;
processa eventos de forma idempotente;
mantém logs das cobranças importadas;
diferencia cobranças criadas de cobranças pagas.

Próximos passos

Updated 4 days ago

Did this page help you?