Gerar Boletos via API REST
Visão Geral
Seção intitulada “Visão Geral”O recurso Boletos é o principal endpoint da API Boleto Cloud. Através dele você pode criar boletos, obter PDFs, consultar status de registro, alterar vencimento e realizar baixa/cancelamento.
Endpoint Base
Seção intitulada “Endpoint Base”https://sandbox.boletocloud.com/api/v1/boletosOperações Disponíveis
Seção intitulada “Operações Disponíveis”A tabela abaixo resume todas as operações disponíveis para o recurso de boletos:
| Operação | Método | Endpoint | Descrição |
|---|---|---|---|
| Criar Boleto/PDF | POST | /boletos | Emite um boleto e retorna o PDF |
| Obter PDF Original | GET | /boletos/{token} | Recupera o PDF com dados originais |
| Obter PDF Atualizado | GET | /boletos/{token}/atualizado/vencimento/{data} | Recupera PDF com encargos calculados |
| Obter Status do Registro | GET | /boletos/{token}/registro | Consulta se o boleto foi registrado no banco |
| Alterar Vencimento | PUT | /boletos/{token}/vencimento | Altera a data de vencimento |
| Alterar Registro | PUT | /boletos/{token}/registro | Habilita ou desabilita o registro no banco |
| Conceder Abatimento | PUT | /boletos/{token}/abatimento | Concede abatimento (redução de valor) |
| Baixar/Cancelar | PUT | /boletos/{token}/baixa | Cancela o boleto na cobrança |
Ciclo de Vida do Boleto
Seção intitulada “Ciclo de Vida do Boleto”O diagrama abaixo mostra os estados do boleto e quais endpoints da API se aplicam em cada etapa:
┌─────────────────────────────────────────────────────────────────────────────────┐│ CRIAÇÃO DO BOLETO ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ POST /boletos │ │ POST /carnes │ │ POST /batch/ │ ││ │ (individual) │ │ (3 por página) │ │ boletos │ ││ │ │ │ │ │ (1 por página) │ ││ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ ││ └────────────────────┼────────────────────┘ ││ ▼ │└────────────────────────────[ CRIADO ]───────────────────────────────────────────┘ │ (envio automático ou via CNAB remessa) ▼┌─────────────────────────[ REGISTRO PENDENTE ]───────────────────────────────────┐│ ││ Endpoints disponíveis: ││ • GET /boletos/{token} → Obter PDF original ││ • GET /boletos/{token}/registro → Consultar status do registro ││ • PUT /boletos/{token}/registro → Habilitar/desabilitar registro ││ • PUT /boletos/{token}/baixa → Cancelar antes do registro ││ │└─────────────────────────────────┬───────────────────────────────────────────────┘ │ ┌────────────────┴────────────────┐ ▼ ▼┌────────[ REGISTRADO / ATIVO ]────────┐ ┌────────[ REJEITADO ]────────┐│ │ │ ││ Endpoints disponíveis: │ │ Ação: Corrigir dados e ││ • GET /boletos/{token} │ │ criar novo boleto ││ • GET /boletos/{token}/registro │ │ ││ • GET /boletos/{token}/atualizado/ │ └─────────────────────────────┘│ vencimento/{data} ││ • PUT /boletos/{token}/vencimento ││ • PUT /boletos/{token}/abatimento ││ • PUT /boletos/{token}/baixa ││ │└──────────────────┬───────────────────┘ │ ┌────────────┼────────────┬─────────────────┐ ▼ ▼ ▼ ▼┌──────────┐ ┌──────────┐ ┌───────────┐ ┌─────────────────┐│ PAGO │ │ VENCIDO │ │ BAIXADO │ │ ALTERADO ││ │ │ │ │ CANCELADO │ │ (vencimento) │└──────────┘ └────┬─────┘ └───────────┘ └────────┬────────┘ │ │ │ (permanece ATIVO com │ │ nova data) │ │ │ ▼ │ ┌─────────────┐ │ │ PAGO ou │◄────────────────────────┘ │ BAIXADO │ └─────────────┘Resumo dos Endpoints por Etapa
Seção intitulada “Resumo dos Endpoints por Etapa”| Etapa | Endpoints Aplicáveis | Descrição |
|---|---|---|
| Criação | POST /boletos, POST /carnes, POST /batch/boletos | Criar boleto individual, carnê (3 por página) ou lote (1 por página) |
| Registro | GET /boletos/{token}/registro, PUT /boletos/{token}/registro | Verificar status ou habilitar/desabilitar registro |
| Consulta PDF | GET /boletos/{token} | PDF com dados originais |
| PDF Atualizado | GET /boletos/{token}/atualizado/vencimento/{data} | PDF com juros/multa recalculados |
| Alteração | PUT /boletos/{token}/vencimento, PUT /boletos/{token}/abatimento | Alterar vencimento ou conceder abatimento |
| Cancelamento | PUT /boletos/{token}/baixa | Baixar/cancelar o boleto |
| CNAB | POST /arquivos/cnab/remessas, POST /arquivos/cnab/retornos | Integração via arquivo bancário |
Detalhes das Operações
Seção intitulada “Detalhes das Operações” Criar Boleto/PDF (POST) Emita boletos sob demanda e receba o PDF na resposta. O fluxo mais utilizado na maioria das integrações.
Criar Carnê (POST) Gere carnês com múltiplas parcelas em um único PDF (3 boletos por página).
Criar em Lote (POST) Emita múltiplos boletos em uma única requisição (1 boleto por página).
Obter PDF Original (GET) Recupere a 2ª via do boleto com os dados originais da emissão.
Obter PDF Atualizado (GET) Recupere o PDF com valores de juros e multa já calculados para uma nova data.
Obter Status do Registro (GET) Consulte se o boleto foi registrado com sucesso no banco ou se houve rejeição.
Alterar Vencimento (PUT) Altere permanentemente a data de vencimento do boleto no banco.
Alterar Registro (PUT) Habilite ou desabilite o registro do boleto no banco após a criação.
Conceder Abatimento (PUT) Reduza o valor do boleto concedendo um abatimento após a emissão.
Baixar/Cancelar (PUT) Cancele o boleto e remova-o da cobrança ativa. Operação irreversível.
Veja Também
Seção intitulada “Veja Também” Campos do Boleto Referência completa de todos os campos disponíveis
Numeração (NIB) Entenda o Número Identificador Bancário
Idempotência Evite boletos duplicados usando token de controle
Arquivos CNAB Geração de remessa e processamento de retorno