Guia de Assinaturas

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

Endpoint responsável por gerar o carnê das cobranças pertencentes a uma assinatura.

O carnê reúne em um único documento as cobranças já geradas pela assinatura, permitindo disponibilizar ao pagador um documento único contendo diversas mensalidades.

O retorno pode ser obtido em formato JSON ou PDF, conforme o cabeçalho Accept enviado na requisição.

Quando utilizar

Utilize este endpoint quando sua aplicação precisar:

• disponibilizar um carnê com as cobranças da assinatura;
• gerar um documento em PDF para impressão ou envio ao cliente;
• emitir um carnê contendo apenas as cobranças geradas até determinado mês e ano;
• oferecer uma alternativa para pagamento de múltiplas mensalidades.

Este endpoint não cria novas cobranças. Ele apenas organiza as cobranças já existentes da assinatura em formato de carnê.

Parâmetros importantes

Além do identificador da assinatura (id), este endpoint possui os seguintes parâmetros opcionais:

• month — define o último mês considerado na geração do carnê.
• year — define o último ano considerado na geração do carnê.
• sort — define o campo utilizado para ordenação.
• order — define a ordem crescente ou decrescente dos registros.

Como funciona

Após localizar a assinatura, o Asaas identifica todas as cobranças elegíveis e gera um carnê contendo essas mensalidades.

Fluxo simplificado:

Assinatura
        ↓
Cobranças já geradas
        ↓
Gerar carnê
        ↓
Documento disponível

O carnê é composto apenas pelas cobranças existentes no momento da geração.

Formatos de resposta

O formato do retorno depende do cabeçalho Accept.

Exemplo para gerar o PDF:

GET /v3/subscriptions/{id}/paymentBook
Accept: application/pdf

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• apenas cobranças já geradas poderão compor o carnê;
• cobranças futuras ainda não criadas não serão incluídas;
• a geração do carnê não altera a assinatura nem cria novas cobranças;
• caso novas mensalidades sejam geradas posteriormente, será necessário gerar um novo carnê para incluí-las;
• a assinatura deve pertencer à conta autenticada pela API Key.

Exemplos de uso

Gerar o carnê completo:

GET /v3/subscriptions/{id}/paymentBook

Gerar o carnê até dezembro de 2026:

GET /v3/subscriptions/{id}/paymentBook?month=12&year=2026

Gerar o carnê em PDF:

GET /v3/subscriptions/{id}/paymentBook
Accept: application/pdf

Boas práticas

Erros comuns

400 Bad Request

Pode ocorrer quando algum parâmetro for 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 parâmetros 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

A geração do carnê considera apenas as cobranças existentes no momento da requisição.

Caso novas mensalidades sejam geradas posteriormente, será necessário emitir um novo carnê para que elas sejam incluídas no documento.

A operação não altera o ciclo da assinatura nem modifica o status das cobranças existentes.

Conteúdos relacionados

• Criar assinatura
• Recuperar uma única assinatura
• Listar cobranças de uma assinatura
• Atualizar assinatura
• Remover assinatura