Documentação da API

Visão Geral

Olá! Seja bem-vindo à página da documentação de referência da API Boleto Cloud.

Atenção

Este conteúdo é direcionado para desenvolvedores, programadores e pessoas da área de sistemas em geral :-) Aqui descrevemos como a Interface de Programação de Aplicativos (API) funciona.

A API Boleto Cloud permite integrar qualquer sistema — seja site, aplicativo mobile, desktop ou servidor — em qualquer linguagem de programação. Ainda não oferecemos SDKs ou bibliotecas oficiais, mas os exemplos desta documentação são fáceis de adaptar para a linguagem que você preferir.

Como Funciona

A API segue o estilo REST sobre HTTP. Isso significa que você lê e escreve dados através de chamadas HTTP comuns. Para a API, não importa de onde vem a requisição: mobile, desktop ou servidor — todas são tratadas da mesma forma.

O que você pode fazer com a API?

Emissão de Boletos

• Criar boletos individuais com retorno imediato do PDF
• Criar boletos em lote (múltiplos boletos em uma única requisição)
• Gerar carnês com várias parcelas (3 boletos por página)
• Configurar juros, multa e descontos escalonados
• Vincular dados de Nota Fiscal Eletrônica (NF-e) ao boleto

Gestão do Ciclo de Vida

• Consultar status de registro no banco (aceito/rejeitado)
• Alterar data de vencimento de boletos ativos
• Conceder abatimento (redução de valor)
• Cancelar/baixar boletos da cobrança

Segunda Via e Consultas

• Obter PDF original do boleto a qualquer momento
• Gerar segunda via atualizada com juros e multa calculados para nova data
• Disponibilizar link público para o pagador acessar o boleto

Integração Bancária

• Registro automático via API/Webservice bancário (plano personalizado)
• Geração de arquivos CNAB de remessa
• Processamento de arquivos CNAB de retorno
• Integração com Pix (QR Code no boleto)

Comunicação

• Envio automático de boletos por e-mail (plano personalizado)
• Múltiplos destinatários por boleto

Bancos Suportados

A API Boleto Cloud oferece integração com os principais bancos brasileiros, incluindo Banco do Brasil, Bradesco, Itaú, Santander, Caixa, Sicredi, Sicoob e muitos outros. Consulte a lista completa em Bancos Suportados para verificar se o banco que você utiliza já está suportado ou se precisa ser adicionado.

Protocolo

O protocolo utilizado pela API é de fato HTTPS, porém, toda a semântica relacionada a arquitetura REST é pertinente ao HTTP versão 1.1. Base da implementação leva em consideração sua RFC principal: RFC2616, entretanto, alguns aspectos podem utilizar atualizações como a RFC7231.

URL

Todos os serviços disponibilizados através da API em ambiente de produção, por questões de segurança, são realizados através do protocolo HTTPS, onde a URL base de acesso é https://app.boletocloud.com/api.

Como já dissemos, a API segue o estilo REST e sendo desta maneira, para que fique claro, os serviços são compostos e formados da seguinte forma:

Onde:

• Hostname - é o endereço principal dos serviços https://app.boletocloud.com
• Versão - é a versão da API/serviço /api/v1
• Recurso - é o nome do serviço /boletos

Portanto, existem apenas dois endpoints para acessar a API:

Ambiente	URL	Finalidade
Sandbox	https://sandbox.boletocloud.com/api	Desenvolvimento e testes
Produção	https://app.boletocloud.com/api	Operação real com clientes

Atenção

Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Diferenças entre Sandbox e Produção

Os ambientes são completamente independentes — cadastros, tokens e dados de um ambiente não existem no outro.

Funcionalidade	Sandbox	Produção
Geração de boletos via API	Sim	Sim
Exportação manual de arquivo CNAB	Sim	Sim
Registro online (API/Webservice bancário)	Não	Sim*
Integração via VAN	Não	Sim*
Envio automático de remessa	Não	Sim*

*Disponível no plano personalizado

Migração para Produção

Após validar sua integração no Sandbox, você precisará replicar manualmente as configurações (beneficiários, contas bancárias) no ambiente de Produção. Para evitar retrabalho, faça todos os testes no Sandbox primeiro.

Charset

O Charset padrão utilizado para todas as chamadas à API é o UTF-8, em caso de dúvidas consulte a RFC3629.

Content Type

O tráfego de dados na API, utiliza os formatos FORM, JSON e o PDF, dependendo do serviço consumido. Respectivamente a negociação de conteúdo deve levar em consideração o content type:

• application/x-www-form-urlencoded para input
• application/json para retorno de erros
• application/pdf para os boletos gerados

Dados

Para o correto funcionamento do serviço alguns dados são padronizados como:

Tipo	Formato	Exemplo	Descrição
Datas	"aaaa-mm-dd"	"2014-07-01"	Todas as datas devem ser informadas seguindo esse padrão (ISO 8601).
Valores Monetários	"0000.00"	"1.83", "3095.72", "5200459.37"	Todos os valores devem possuir apenas duas casas decimais. No exemplo "5200459.37" que normalmente é representado como R$ 5.200.459,37, não deve conter vírgula e no lugar dela apenas um ponto representa a parte fracionária. Todos os valores são, por padrão, considerados como valores em Real R$.

Sobre os exemplos

Atenção

Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Os exemplos são disponibilizados em 11 linguagens/ferramentas diferentes, organizados em abas para facilitar a navegação. Todos os exemplos seguem o mesmo padrão e utilizam as bibliotecas nativas ou mais populares de cada linguagem.

Versões e Bibliotecas Utilizadas

Linguagem	Versão	Biblioteca/Framework	Observações
Postman	Amplamente utilizada	Interface gráfica	Disponível em alguns exemplos para visualização
cURL	7.x+	Linha de comando	Exemplo canônico, base para todas as linguagens
Java	17+	JAX-RS 2.x + Jersey 2.x	Compatível com Java 11+, adaptável para versões anteriores
Kotlin	1.8+	OkHttp 4.x	Biblioteca HTTP moderna e eficiente
C#	.NET 6+	HttpClient (nativo)	Compatível com .NET Core 3.1+
Node.js	18+	https (módulo nativo)	Sem dependências externas
Go	1.20+	net/http (padrão)	Biblioteca padrão, sem dependências externas
PHP	8.1+	cURL extension	Compatível com PHP 7.4+
Python	3.10+	requests	Biblioteca mais popular para HTTP
Ruby	3.1+	net/http (padrão)	Biblioteca padrão, sem gems externas
Clojure	1.11+	clj-http	Cliente HTTP mais utilizado no ecossistema

Compatibilidade

Os exemplos foram escritos para as versões mais recentes das linguagens, mas são facilmente adaptáveis para versões anteriores. A lógica e os conceitos permanecem os mesmos.

Interface gráfica - Postman

Caso prefira, é possível executar os exemplos direto do browser, para isso, indicamos o Postman. Com essa ferramenta você poderá adaptar os exemplos colocando os valores de parâmetros descritos nos respectivos campos da interface gráfica.

Linha de comando - cURL

Utilizamos o cURL como o principal meio de exemplificação das chamadas à API. É uma ferramenta de linha de comando largamente utilizada e disponível em diversos sistemas operacionais. Os exemplos cURL servem como especificação canônica e base para adaptação em outras linguagens.

Linguagens de Programação

No momento não disponibilizamos nenhuma biblioteca, DLL ou SDK específico, mas fornecemos exemplos completos em 10 linguagens de programação usando as bibliotecas mais populares de cada ecossistema.

Detalhes por Linguagem

Java - Utilizamos a Java API for RESTful Services (JAX-RS) 2.x com a implementação de referência Jersey 2.x. Os exemplos usam text blocks do Java 17, mas são facilmente adaptáveis para versões anteriores usando concatenação de strings.

Kotlin - Utilizamos o OkHttp 4.x, um cliente HTTP moderno e eficiente amplamente utilizado no ecossistema Kotlin/Android.

C# - Utilizamos o HttpClient nativo do .NET, disponível desde o .NET Core. Os exemplos são assíncronos usando async/await.

Node.js - Utilizamos o módulo https nativo, sem dependências externas. Os exemplos são compatíveis com o sistema de callbacks do Node.js.

Go - Utilizamos o pacote net/http da biblioteca padrão. Go oferece excelente suporte HTTP nativo sem necessidade de bibliotecas externas.

PHP - Utilizamos a extensão cURL do PHP, presente na maioria das instalações PHP. Os exemplos são compatíveis com PHP 7.4+.

Python - Utilizamos a biblioteca requests, o cliente HTTP mais popular do Python. Instale com pip install requests.

Ruby - Utilizamos o módulo net/http da biblioteca padrão do Ruby, sem necessidade de gems externas.

Clojure - Utilizamos o clj-http, o cliente HTTP mais utilizado no ecossistema Clojure. Adicione [clj-http "3.12.3"] às suas dependências.

Dados Gerados - Ambiente Sandbox

Dados gerados pela API podem ser visualizados via interface gráfica no ambiente Sandbox, entretanto os dados são apagados de tempos e tempos, portanto não conte com uma vida prolongada dos dados gerados, exceto os dados de acesso referente a conta do usuário.

Ambientes independentes

Os dados do Sandbox não são migrados para Produção. Após concluir os testes, você precisará replicar manualmente as configurações (beneficiários, contas bancárias, tokens) no ambiente de Produção.