Documentação da API

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

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.

Visão geral das conexões com a API

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:

Composição da URL

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

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

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

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

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.

Postman

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.

Próximo
Acesso à API