Documento e linha digitável
Em emissões confirmadas, use os campos retornados para apresentar o boleto. No simulador, URL, linha e código de barras são nulos.
INTEGRAÇÃO BOLETO POR API
Integração de boleto para emitir e acompanhar cada cobrança.
Conecte seu ERP, e-commerce ou SaaS à API de boleto do Calebe Pay. Emita a partir da fatura, informe vencimento e dados do pagador, entregue a linha digitável e acompanhe a confirmação bancária pelo seu sistema.
- API de boleto
- emissão em JSON
- Até 365 dias
- para definir o vencimento
- Multa e juros
- conforme condições da conta
- Webhook
- para acompanhar mudanças de status
PASSO A PASSO
Como integrar a emissão de boleto
O boleto compartilha autenticação, consultas e eventos com o Pix, com campos próprios para endereço, vencimento e instruções.
- 01
Habilite boleto para a conta
Confirme a disponibilidade do método e gere uma chave com boleto:write e transactions:read. Comece em teste antes da emissão real.
- 02
Envie a cobrança pela API
Faça POST /v1/boleto com valor em centavos, referência, descrição, dados completos do pagador e boleto.due_date. Preserve o corpo e o Idempotency-Key.
- 03
Entregue o documento retornado
Quando disponíveis, apresente boleto_url, boleto_digitable_line e boleto_barcode. Linha digitável e código de barras são textos; preserve os zeros.
- 04
Aguarde a confirmação bancária
Acompanhe transaction.updated e consultas pelo ID. Somente paid em produção confirma o pagamento; pending e processing ainda não autorizam a baixa financeira.
EXEMPLO REAL DA API
Exemplo de emissão de boleto por API
O exemplo usa dados fictícios. Prepare o pedido uma vez e comece com uma chave de teste, que não emite um título pagável.
- due_date usa AAAA-MM-DD, de hoje até 365 dias à frente no horário de São Paulo.
- Multa, juros e baixa após vencimento dependem das condições habilitadas para a conta.
- Ao repetir uma tentativa, preserve inclusive o vencimento original. Recalcular a data altera o corpo e gera conflito.
curl --fail-with-body https://api.calebepay.com.br/v1/boleto \
-H "X-API-Key: $CALEBE_API_KEY" \
-H "Idempotency-Key: fatura-2026-10-boleto" \
-H "Content-Type: application/json" \
-d '{
"amount": 49900,
"reference": "fatura-2026-10",
"description": "Mensalidade de outubro",
"customer": {
"name": "Cliente de demonstração",
"document": "00000000000",
"email": "cliente@example.com",
"phone": "11999998888",
"address": {
"zip_code": "01310100", "street": "Avenida Paulista", "number": "1000",
"district": "Bela Vista", "city": "São Paulo", "state": "SP"
}
},
"boleto": {
"due_date": "2026-10-13",
"penalty_rate": 2,
"interest_rate": 1,
"instruction": "Não receber após 5 dias do vencimento",
"cancel_after_due": true,
"days_before_cancel": 5
}
}'
# Emissão confirmada: boleto_digitable_line, boleto_barcode, boleto_url.
# Em teste simulado, esses três campos são nulos.RECURSOS
Recursos da API de boleto
A emissão mantém a referência da fatura para que financeiro e sistema acompanhem a mesma cobrança.
Vencimento por cobrança
Defina a data adequada à fatura, respeitando o limite de emissão e o horário de São Paulo.
Multa, juros e instruções
Informe os percentuais e a instrução do boleto, dentro das regras do contrato e da configuração da conta.
Baixa após o vencimento
Solicite a opção de baixa com cancel_after_due e days_before_cancel. O estado final depende do retorno bancário.
Webhook e consulta de status
Receba eventos assinados e consulte cobranças por ID, referência e método sem gerar outro boleto.
Teste antes da produção
Valide o contrato em simulação. O sandbox remoto de boleto é uma opção separada, quando configurado para a conta.
O que é integração de boleto por API
Integração de boleto permite que o seu sistema solicite a emissão e acompanhe o pagamento sem cadastrar cada cobrança manualmente. A fatura fornece valor, pagador e prazo; a API devolve o registro da transação e os dados do boleto quando a emissão é confirmada.
Na integração com o Calebe Pay, seu backend trabalha com JSON e eventos de pagamento. Não precisa gerar arquivo de remessa CNAB nem interpretar arquivo de retorno para utilizar esta API.
Boleto para ERP, mensalidades e vendas a prazo
Um ERP pode gerar a cobrança ao concluir uma venda ou uma fatura. Um SaaS pode emitir um novo boleto para cada mensalidade. Escolas, prestadores de serviço e distribuidores podem usar a referência comercial para relacionar o pagamento ao documento correto.
Seu sistema pode criar cada boleto avulso ou delegar o calendário ao recurso de assinaturas do Calebe Pay. A assinatura gera uma cobrança por ciclo; o endpoint de boleto avulso continua destinado a uma emissão individual. O envio dos links e lembretes ao cliente fica com sua operação.
Automatize mensalidades com assinaturas →Ofereça boleto e Pix no mesmo link de pagamento →
Vencimento, baixa e confirmação não são a mesma coisa
Vencimento é a data definida para pagamento. Baixa é o encerramento informado pelo banco, conforme as regras do boleto. Confirmação é a mudança para paid quando o pagamento é reconhecido. Passar do vencimento, sozinho, não significa que um boleto está pago ou baixado.
Mantenha a fatura em acompanhamento enquanto a transação estiver pending ou processing. Em caso de resultado unknown ou falha de rede, consulte a tentativa existente antes de emitir outra. A consulta e o refresh usam o ID original e não criam um novo título.
Quando oferecer boleto, Pix ou os dois
O boleto atende operações em que o cliente precisa de uma data de vencimento e de um documento para o processo financeiro. O Pix atende quem prefere pagar pelo QR Code ou copia e cola. A escolha depende do fluxo e da preferência do pagador.
No Calebe Pay, os dois métodos compartilham a API de transações. Se quiser apresentar a escolha numa página pronta, crie um link de pagamento com os métodos habilitados para a conta.
Veja como integrar Pix ao mesmo sistema →Conheça a API de pagamentos →
PERGUNTAS FREQUENTES
Dúvidas sobre integração de boleto
Não achou a resposta? Fale com um especialista pelo WhatsApp.
Como emitir boleto por API com o Calebe Pay?
Habilite boleto para a conta e faça POST /v1/boleto com uma chave autorizada. Envie valor em centavos, referência, descrição, dados do pagador e vencimento. Guarde o ID retornado e apresente os dados do boleto quando disponíveis.
Quais dados do cliente são necessários para emitir boleto?
Nome, CPF ou CNPJ, e-mail, telefone e endereço com CEP, rua, número, bairro, cidade e UF. Valor, referência, descrição e data de vencimento também são obrigatórios na requisição.
Posso configurar multa e juros pela API?
Sim. penalty_rate e interest_rate recebem percentuais de 0 a 100, com até duas casas decimais. A aplicação depende das condições contratadas para a conta. A instrução do boleto aceita até 200 bytes.
A integração permite testar boletos sem dinheiro real?
Sim. Com chave de teste, a cobrança é simulada e não tem boleto pagável: URL, linha digitável e código de barras são nulos. O sandbox remoto de boleto é outro ambiente, disponível quando configurado, e também não representa dinheiro real.
O boleto vencido é cancelado automaticamente?
A emissão aceita a opção de baixa após vencimento, sujeita às condições da conta. O banco determina o estado final: o vencimento não muda sozinho o status para expired. Não há endpoint público de cancelamento posterior nesta versão.
Preciso processar arquivos CNAB para integrar?
Não para usar a API do Calebe Pay. Você solicita a emissão por HTTPS e JSON e acompanha o resultado com webhooks e consultas de transações.
CADASTRO 100% ONLINE · CERCA DE 6 MINUTOS