Criar Boleto Individual

Emite um boleto bancário e retorna o PDF na mesma resposta. Este é o endpoint mais utilizado da API Boleto Cloud, ideal para emissão sob demanda onde você precisa do boleto imediatamente após a criação.

O que este endpoint faz

1. Valida os dados do boleto enviados
2. Gera o boleto no Boleto Cloud
3. Envia para registro no banco (automático ou via CNAB)
4. Retorna o PDF do boleto pronto para uso

┌──────────────┐      ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│    Enviar    │─────▶│   Validar    │─────▶│    Gerar     │─────▶│  Registrar   │
│  POST /boletos│     │    Dados     │      │   Boleto     │      │   no Banco   │
└──────────────┘      └──────────────┘      └──────────────┘      └──────────────┘
                                                                          │
                      ┌──────────────┐      ┌──────────────┐              │
                      │   Usar PDF   │◀─────│   Retornar   │◀─────────────┘
                      │   e Token    │      │  PDF + Token │
                      └──────────────┘      └──────────────┘

---

Quando Usar

Cenários Recomendados

Cenário	Recomendação
Emissão de boletos avulsos	Sim
Checkout de e-commerce	Sim
Geração sob demanda em sistemas	Sim
Emissão de carnês (3 boletos por página)	Não — use Criar Carnê
Emissão de boletos em lote (1 por página)	Não — use Criar em Lote

Onde se encaixa no ciclo de vida

O POST /boletos é o ponto de entrada para criar boletos individuais. Após a criação, o boleto entra no estado “Criado” e é enviado para registro no banco.

┌─────────────────────────────────────────────────────────────────────────────┐
│                            CRIAÇÃO DO BOLETO                                │
│                                                                             │
│                        ┌─────────────────────┐                              │
│                        │  ★ POST /boletos    │                              │
│                        │    (individual)     │                              │
│                        └──────────┬──────────┘                              │
│                                   ▼                                         │
└───────────────────────────────[ CRIADO ]────────────────────────────────────┘
                                    │
                       (envio automático ou via CNAB)
                                    ▼
┌─────────────────────────[ REGISTRO PENDENTE ]───────────────────────────────┐
│                                                                             │
│   Próximos endpoints disponíveis:                                           │
│   • GET /boletos/{token}              → Obter PDF original                  │
│   • GET /boletos/{token}/registro     → Consultar status do registro        │
│   • GET /boletos/{token}/situacao     → Consultar situação completa         │
│   • PUT /boletos/{token}/baixa        → Cancelar antes do registro          │
│                                                                             │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                 ┌────────────────┴────────────────┐
                 ▼                                 ▼
      [ REGISTRADO / ATIVO ]              [ REJEITADO ]

Pré-requisitos

Antes de usar este endpoint, certifique-se de ter:

• Conta Boleto Cloud — Crie sua conta se ainda não tiver
• API Key — Gerada na área de desenvolvedor da plataforma
• Conta Bancária cadastrada — Com token de acesso gerado
• Ambiente correto — Use Sandbox para desenvolvimento, Produção apenas em produção

Ambiente de Desenvolvimento

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

Endpoint

POST https://sandbox.boletocloud.com/api/v1/boletos

Ambiente	URL Base
Sandbox (desenvolvimento)	https://sandbox.boletocloud.com/api/v1/boletos
Produção	https://app.boletocloud.com/api/v1/boletos

---

Requisição

Headers

Header	Valor	Obrigatório
Authorization	Basic {credenciais_base64}	Sim
Content-Type	application/x-www-form-urlencoded; charset=utf-8	Sim

Autenticação Basic

As credenciais são sua API Key seguida de :token, codificadas em Base64. Exemplo: api-key_SUA-API-KEY:token → Base64.

Body (application/x-www-form-urlencoded)

O corpo da requisição contém os campos do boleto no formato chave=valor. Use o token da conta bancária para simplificar a requisição — os dados do beneficiário e a numeração são obtidos automaticamente.

Campos Obrigatórios

Campo	Tipo	Exemplo	Descrição
boleto.conta.token	string	"api-key_abc123..."	Token da conta bancária cadastrada
boleto.emissao	date	"2024-01-15"	Data de emissão (formato AAAA-MM-DD)
boleto.vencimento	date	"2024-02-15"	Data de vencimento (formato AAAA-MM-DD)
boleto.documento	string	"PED-12345"	Número do documento/pedido
boleto.titulo	string	"DM"	Tipo do título (ver tipos)
boleto.valor	decimal	"1250.43"	Valor do boleto (até 8 inteiros, até 4 decimais)
boleto.pagador.nome	string	"Alberto Santos Dumont"	Nome completo do pagador
boleto.pagador.cprf	string	"111.111.111-11"	CPF ou CNPJ do pagador
boleto.pagador.endereco.cep	string	"36240-000"	CEP do pagador
boleto.pagador.endereco.uf	string	"MG"	Estado (2 letras)
boleto.pagador.endereco.localidade	string	"Santos Dumont"	Cidade
boleto.pagador.endereco.bairro	string	"Centro"	Bairro
boleto.pagador.endereco.logradouro	string	"Rua Principal"	Logradouro
boleto.pagador.endereco.numero	string	"123"	Número (use "s/n" se não houver)

Campos Opcionais

Campo	Tipo	Exemplo	Descrição
boleto.pagador.endereco.complemento	string	"Apto 101"	Complemento do endereço
boleto.numero	string	"12345678901-P"	NIB específico (se não informado, usa sequencial automático)
boleto.sequencial	integer	12345	Sequencial para gerar NIB (alternativa ao numero)
boleto.instrucao	string	"Não receber após 30 dias"	Instruções ao caixa (até 3 linhas, envie múltiplas vezes)
boleto.info	string	"Pedido #12345"	Informações ao pagador (até 2 linhas de 100 caracteres)
boleto.juros	decimal	"0.0333"	Taxa diária de juros, em percentual ao dia. Para ~1% a.m., envie 0.0333 (taxa mensal ÷ 30)
boleto.multa	decimal	"2.00"	Percentual de multa por atraso (%)
boleto.desconto	decimal	"5.00"	Percentual de desconto até o vencimento (%)
boleto.tokenControleUsuario	string	"pedido-12345-abc"	Token para idempotência (máx. 44 caracteres)

Como obter o Token da Conta

1. Acesse o painel Boleto Cloud
2. Navegue até Conta → Consultar
3. Clique no nome da conta bancária
4. Clique em “Editar dados”
5. Clique em “Gerar Token”

Exemplo de Body

boleto.conta.token=api-key_SEU-TOKEN-DA-CONTA
boleto.emissao=2024-01-15
boleto.vencimento=2024-02-15
boleto.documento=PED-12345
boleto.titulo=DM
boleto.valor=1250.43
boleto.pagador.nome=Alberto Santos Dumont
boleto.pagador.cprf=111.111.111-11
boleto.pagador.endereco.cep=36240-000
boleto.pagador.endereco.uf=MG
boleto.pagador.endereco.localidade=Santos Dumont
boleto.pagador.endereco.bairro=Casa Natal
boleto.pagador.endereco.logradouro=BR-499
boleto.pagador.endereco.numero=s/n
boleto.instrucao=Não receber após o vencimento
boleto.instrucao=Pagamento exclusivo via rede bancária

---

Respostas

201 Created — Sucesso

O boleto foi criado com sucesso. O PDF está no body da resposta.

Headers da Resposta (201)

Header	Descrição	Exemplo
Content-Type	Tipo do conteúdo	application/pdf; charset=UTF-8
X-BoletoCloud-Token	Token único do boleto — guarde para operações futuras	abc123def456...
X-BoletoCloud-NIB-Nosso-Numero	Nosso Número do boleto	00000012345-6
X-BoletoCloud-Token-Controle-Usuario	Token de controle enviado (se informado)	pedido-12345-abc
Location	Path para acessar o boleto	/api/v1/boletos/abc123def456
X-BoletoCloud-Version	Versão da plataforma	2.0.0

Headers Adicionais (Plano Personalizado)

Clientes do plano personalizado recebem headers extras:

Header	Descrição	Exemplo
X-BoletoCloud-Codigo-De-Barras	Código de barras numérico (44 dígitos)	23793.38128 60000.000003 00000.000400 1 84340000012543
X-BoletoCloud-Linha-Digitavel	Linha digitável formatada	23793.38128 60000.000003...
X-BoletoCloud-Pix-Codigo-EMV	Código Pix copia-e-cola	00020126580014br.gov.bcb...
X-BoletoCloud-Status-Registrado-Banco	Se já foi registrado no banco	true ou false

Body da Resposta (201)

O body contém o arquivo PDF do boleto, pronto para ser salvo ou enviado ao pagador.

Guarde o Token

O X-BoletoCloud-Token é essencial para operações futuras como obter PDF, consultar status, alterar vencimento ou cancelar o boleto. Guarde este valor no seu banco de dados.

---

409 Conflict — Boleto Já Existe

Retornado quando já existe um boleto com o mesmo Nosso Número ou tokenControleUsuario. Isso indica que o boleto já foi criado anteriormente — a API está protegendo contra duplicação.

Headers da Resposta (409)

Header	Descrição
Content-Type	application/json; charset=UTF-8
X-BoletoCloud-Token	Token do boleto existente
X-BoletoCloud-NIB-Nosso-Numero	Nosso Número do boleto existente
X-BoletoCloud-Token-Controle-Usuario	Token de controle do boleto existente
Location	Path para o boleto existente
X-BoletoCloud-Version	Versão da plataforma

Body da Resposta (409)

{
  "erro": {
    "status": 409,
    "tipo": "conflito",
    "causas": [
      {
        "codigo": "2B257710",
        "mensagem": "Campo (boleto.numero) - Conflito de dados, já existe um boleto com o mesmo conteúdo (12345678901-P) para este campo, localizado em (/api/v1/boletos/abc123def456).",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Como tratar o 409

O erro 409 não é um problema — significa que o boleto já existe. Use os headers retornados para obter o token do boleto existente e prosseguir normalmente. Isso é especialmente útil em cenários de retry.

---

400 Bad Request — Dados Inválidos

Retornado quando há problemas de validação nos dados enviados.

Headers da Resposta (400)

Header	Descrição
Content-Type	application/json; charset=UTF-8
X-BoletoCloud-Version	Versão da plataforma

Body da Resposta (400)

Exemplo: Dados não informados

{
  "erro": {
    "status": 400,
    "tipo": "requisicao",
    "causas": [
      {
        "codigo": "4D4AAFB5",
        "mensagem": "Dados do boleto não informados.",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Exemplo: Múltiplos erros de validação

{
  "erro": {
    "status": 400,
    "tipo": "requisicao",
    "causas": [
      {
        "codigo": "842EF62A",
        "mensagem": "Campo (boleto.emissao) - O valor informado (23/05/2024) não corresponde com o formato válido para este campo (AAAA-MM-DD).",
        "suporte": "https://developers.boleto.cloud/"
      },
      {
        "codigo": "842EF62A",
        "mensagem": "Campo (boleto.valor) - O valor informado (1.274,98) não corresponde com o formato válido para este campo (00000000.0000 = até 8 dígitos parte inteira e até 4 dígitos para fracionada).",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Erros Comuns de Validação

Campo	Formato Incorreto	Formato Correto
boleto.emissao	23/05/2024	2024-05-23
boleto.vencimento	15-02-2024	2024-02-15
boleto.valor	1.274,98	1274.98
boleto.sequencial	12345678901234567890 (>18 dígitos)	12345 (até 18 dígitos)
boleto.conta.carteira	-12	09 (inteiro positivo)

---

Comunicação com o Banco

Após a criação do boleto, a comunicação com o banco depende do tipo de integração configurado na conta:

Tipo de Comunicação	Comportamento
API/Webservice (automático)	O boleto é enviado automaticamente para registro no banco. O header X-BoletoCloud-Status-Registrado-Banco indica se já foi confirmado (plano personalizado).
Arquivo CNAB (manual)	O boleto é incluído no próximo arquivo de remessa para você importar manualmente no banco.

Nota

Para verificar se o boleto foi registrado com sucesso no banco, use o endpoint Obter Status do Registro.

---

Próximos Passos

Após criar o boleto com sucesso, você pode:

Ação	Endpoint	Descrição
Consultar situação	GET /boletos/{token}/situacao	Registro, pagamento, baixa, protesto, Pix e condições de emissão em JSON
Consultar por token de controle	GET /boletos/controle/{tokenControleUsuario}/situacao	Mesma consulta usando o identificador do seu sistema
Verificar registro	GET /boletos/{token}/registro	Confirmar se foi aceito pelo banco
Obter PDF novamente	GET /boletos/{token}	Recuperar o PDF original
Obter PDF atualizado	GET /boletos/{token}/atualizado/vencimento/{data}	PDF com juros/multa calculados
Alterar vencimento	PUT /boletos/{token}/vencimento	Mudar a data de vencimento
Cancelar boleto	PUT /boletos/{token}/baixa	Baixar da cobrança

---

Idempotência (Evitando Duplicação)

Para evitar a criação de boletos duplicados em cenários de retry ou falhas de rede, use o campo boleto.tokenControleUsuario:

boleto.tokenControleUsuario=pedido-12345-abc

Se duas requisições forem enviadas com o mesmo token de controle, apenas a primeira será processada — a segunda retornará 409 Conflict com os dados do boleto existente.

IdempotênciaDocumentação completa sobre como evitar boletos duplicados

---

Exemplos de Código

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/boletos" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -X "POST" \
  -u "api-key_SUA-API-KEY:token" \
  -d boleto.conta.token="api-key_SEU-TOKEN-DA-CONTA" \
  -d boleto.emissao="2024-01-15" \
  -d boleto.vencimento="2024-02-15" \
  -d boleto.documento="PED-12345" \
  -d boleto.titulo="DM" \
  -d boleto.valor="1250.43" \
  -d boleto.pagador.nome="Alberto Santos Dumont" \
  -d boleto.pagador.cprf="111.111.111-11" \
  -d boleto.pagador.endereco.cep="36240-000" \
  -d boleto.pagador.endereco.uf="MG" \
  -d boleto.pagador.endereco.localidade="Santos Dumont" \
  -d boleto.pagador.endereco.bairro="Casa Natal" \
  -d boleto.pagador.endereco.logradouro="BR-499" \
  -d boleto.pagador.endereco.numero="s/n" \
  -d boleto.instrucao="Não receber após o vencimento" \
  -o boleto.pdf

# O token do boleto estará no header X-BoletoCloud-Token da resposta
# Use -v para ver os headers ou capture com -D headers.txt

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;

public class CriarBoleto {
    public static void main(String[] args) throws Exception {
        Form form = new Form()
            .param("boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA")
            .param("boleto.emissao", "2024-01-15")
            .param("boleto.vencimento", "2024-02-15")
            .param("boleto.documento", "PED-12345")
            .param("boleto.titulo", "DM")
            .param("boleto.valor", "1250.43")
            .param("boleto.pagador.nome", "Alberto Santos Dumont")
            .param("boleto.pagador.cprf", "111.111.111-11")
            .param("boleto.pagador.endereco.cep", "36240-000")
            .param("boleto.pagador.endereco.uf", "MG")
            .param("boleto.pagador.endereco.localidade", "Santos Dumont")
            .param("boleto.pagador.endereco.bairro", "Casa Natal")
            .param("boleto.pagador.endereco.logradouro", "BR-499")
            .param("boleto.pagador.endereco.numero", "s/n")
            .param("boleto.instrucao", "Não receber após o vencimento");

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request()
            .post(Entity.form(form));

        switch (response.getStatus()) {
            case 201:
                String token = response.getHeaderString("X-BoletoCloud-Token");
                String nossoNumero = response.getHeaderString("X-BoletoCloud-NIB-Nosso-Numero");
                System.out.println("Boleto criado!");
                System.out.println("Token: " + token);
                System.out.println("Nosso Número: " + nossoNumero);
                Files.copy(response.readEntity(InputStream.class),
                    Paths.get("boleto.pdf"), REPLACE_EXISTING);
                break;
            case 409:
                String tokenExistente = response.getHeaderString("X-BoletoCloud-Token");
                System.out.println("Boleto já existe. Token: " + tokenExistente);
                break;
            default:
                System.out.println("Erro: " + response.readEntity(String.class));
        }
    }
}

Kotlin

import okhttp3.*
import java.io.File

fun main() {
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val body = FormBody.Builder()
        .add("boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA")
        .add("boleto.emissao", "2024-01-15")
        .add("boleto.vencimento", "2024-02-15")
        .add("boleto.documento", "PED-12345")
        .add("boleto.titulo", "DM")
        .add("boleto.valor", "1250.43")
        .add("boleto.pagador.nome", "Alberto Santos Dumont")
        .add("boleto.pagador.cprf", "111.111.111-11")
        .add("boleto.pagador.endereco.cep", "36240-000")
        .add("boleto.pagador.endereco.uf", "MG")
        .add("boleto.pagador.endereco.localidade", "Santos Dumont")
        .add("boleto.pagador.endereco.bairro", "Casa Natal")
        .add("boleto.pagador.endereco.logradouro", "BR-499")
        .add("boleto.pagador.endereco.numero", "s/n")
        .add("boleto.instrucao", "Não receber após o vencimento")
        .build()

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos")
        .header("Authorization", credential)
        .post(body)
        .build()

    client.newCall(request).execute().use { response ->
        when (response.code) {
            201 -> {
                val token = response.header("X-BoletoCloud-Token")
                val nossoNumero = response.header("X-BoletoCloud-NIB-Nosso-Numero")
                println("Boleto criado!")
                println("Token: $token")
                println("Nosso Número: $nossoNumero")
                File("boleto.pdf").writeBytes(response.body!!.bytes())
            }
            409 -> {
                val tokenExistente = response.header("X-BoletoCloud-Token")
                println("Boleto já existe. Token: $tokenExistente")
            }
            else -> println("Erro: ${response.body?.string()}")
        }
    }
}

C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        using var client = new HttpClient();
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);

        var content = new FormUrlEncodedContent(new Dictionary<string, string> {
            {"boleto.conta.token", "api-key_SEU-TOKEN-DA-CONTA"},
            {"boleto.emissao", "2024-01-15"},
            {"boleto.vencimento", "2024-02-15"},
            {"boleto.documento", "PED-12345"},
            {"boleto.titulo", "DM"},
            {"boleto.valor", "1250.43"},
            {"boleto.pagador.nome", "Alberto Santos Dumont"},
            {"boleto.pagador.cprf", "111.111.111-11"},
            {"boleto.pagador.endereco.cep", "36240-000"},
            {"boleto.pagador.endereco.uf", "MG"},
            {"boleto.pagador.endereco.localidade", "Santos Dumont"},
            {"boleto.pagador.endereco.bairro", "Casa Natal"},
            {"boleto.pagador.endereco.logradouro", "BR-499"},
            {"boleto.pagador.endereco.numero", "s/n"},
            {"boleto.instrucao", "Não receber após o vencimento"}
        });

        var response = await client.PostAsync(
            "https://sandbox.boletocloud.com/api/v1/boletos", content);
        var statusCode = (int)response.StatusCode;

        switch (statusCode) {
            case 201:
                var token = response.Headers.GetValues("X-BoletoCloud-Token").First();
                var nossoNumero = response.Headers
                    .GetValues("X-BoletoCloud-NIB-Nosso-Numero").First();
                Console.WriteLine("Boleto criado!");
                Console.WriteLine($"Token: {token}");
                Console.WriteLine($"Nosso Número: {nossoNumero}");
                var pdf = await response.Content.ReadAsByteArrayAsync();
                await File.WriteAllBytesAsync("boleto.pdf", pdf);
                break;
            case 409:
                var tokenExistente = response.Headers
                    .GetValues("X-BoletoCloud-Token").First();
                Console.WriteLine($"Boleto já existe. Token: {tokenExistente}");
                break;
            default:
                var erro = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Erro: {erro}");
                break;
        }
    }
}

Node

const https = require('https');
const fs = require('fs');
const querystring = require('querystring');

const data = querystring.stringify({
  'boleto.conta.token': 'api-key_SEU-TOKEN-DA-CONTA',
  'boleto.emissao': '2024-01-15',
  'boleto.vencimento': '2024-02-15',
  'boleto.documento': 'PED-12345',
  'boleto.titulo': 'DM',
  'boleto.valor': '1250.43',
  'boleto.pagador.nome': 'Alberto Santos Dumont',
  'boleto.pagador.cprf': '111.111.111-11',
  'boleto.pagador.endereco.cep': '36240-000',
  'boleto.pagador.endereco.uf': 'MG',
  'boleto.pagador.endereco.localidade': 'Santos Dumont',
  'boleto.pagador.endereco.bairro': 'Casa Natal',
  'boleto.pagador.endereco.logradouro': 'BR-499',
  'boleto.pagador.endereco.numero': 's/n',
  'boleto.instrucao': 'Não receber após o vencimento'
});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/boletos',
  method: 'POST',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  const token = res.headers['x-boletocloud-token'];
  const nossoNumero = res.headers['x-boletocloud-nib-nosso-numero'];

  switch (res.statusCode) {
    case 201:
      console.log('Boleto criado!');
      console.log('Token:', token);
      console.log('Nosso Número:', nossoNumero);
      const file = fs.createWriteStream('boleto.pdf');
      res.pipe(file);
      break;
    case 409:
      console.log('Boleto já existe. Token:', token);
      break;
    default:
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => console.log('Erro:', body));
  }
});

req.write(data);
req.end();

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
)

func main() {
    data := url.Values{
        "boleto.conta.token":              {"api-key_SEU-TOKEN-DA-CONTA"},
        "boleto.emissao":                  {"2024-01-15"},
        "boleto.vencimento":               {"2024-02-15"},
        "boleto.documento":                {"PED-12345"},
        "boleto.titulo":                   {"DM"},
        "boleto.valor":                    {"1250.43"},
        "boleto.pagador.nome":             {"Alberto Santos Dumont"},
        "boleto.pagador.cprf":             {"111.111.111-11"},
        "boleto.pagador.endereco.cep":     {"36240-000"},
        "boleto.pagador.endereco.uf":      {"MG"},
        "boleto.pagador.endereco.localidade": {"Santos Dumont"},
        "boleto.pagador.endereco.bairro":  {"Casa Natal"},
        "boleto.pagador.endereco.logradouro": {"BR-499"},
        "boleto.pagador.endereco.numero":  {"s/n"},
        "boleto.instrucao":                {"Não receber após o vencimento"},
    }

    req, _ := http.NewRequest("POST",
        "https://sandbox.boletocloud.com/api/v1/boletos",
        strings.NewReader(data.Encode()))
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    token := resp.Header.Get("X-BoletoCloud-Token")
    nossoNumero := resp.Header.Get("X-BoletoCloud-NIB-Nosso-Numero")

    switch resp.StatusCode {
    case 201:
        fmt.Println("Boleto criado!")
        fmt.Println("Token:", token)
        fmt.Println("Nosso Número:", nossoNumero)
        file, _ := os.Create("boleto.pdf")
        defer file.Close()
        io.Copy(file, resp.Body)
    case 409:
        fmt.Println("Boleto já existe. Token:", token)
    default:
        body, _ := io.ReadAll(resp.Body)
        fmt.Println("Erro:", string(body))
    }
}

PHP

<?php
$url = 'https://sandbox.boletocloud.com/api/v1/boletos';
$api_key = 'api-key_SUA-API-KEY';

$data = http_build_query([
    'boleto.conta.token' => 'api-key_SEU-TOKEN-DA-CONTA',
    'boleto.emissao' => '2024-01-15',
    'boleto.vencimento' => '2024-02-15',
    'boleto.documento' => 'PED-12345',
    'boleto.titulo' => 'DM',
    'boleto.valor' => '1250.43',
    'boleto.pagador.nome' => 'Alberto Santos Dumont',
    'boleto.pagador.cprf' => '111.111.111-11',
    'boleto.pagador.endereco.cep' => '36240-000',
    'boleto.pagador.endereco.uf' => 'MG',
    'boleto.pagador.endereco.localidade' => 'Santos Dumont',
    'boleto.pagador.endereco.bairro' => 'Casa Natal',
    'boleto.pagador.endereco.logradouro' => 'BR-499',
    'boleto.pagador.endereco.numero' => 's/n',
    'boleto.instrucao' => 'Não receber após o vencimento'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);

// Extrair headers
preg_match('/X-BoletoCloud-Token:\s*(.+)/i', $headers, $tokenMatch);
preg_match('/X-BoletoCloud-NIB-Nosso-Numero:\s*(.+)/i', $headers, $nibMatch);
$token = trim($tokenMatch[1] ?? '');
$nossoNumero = trim($nibMatch[1] ?? '');

switch ($http_code) {
    case 201:
        echo "Boleto criado!\n";
        echo "Token: $token\n";
        echo "Nosso Número: $nossoNumero\n";
        file_put_contents('boleto.pdf', $body);
        break;
    case 409:
        echo "Boleto já existe. Token: $token\n";
        break;
    default:
        echo "Erro ($http_code): $body\n";
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

data = {
    'boleto.conta.token': 'api-key_SEU-TOKEN-DA-CONTA',
    'boleto.emissao': '2024-01-15',
    'boleto.vencimento': '2024-02-15',
    'boleto.documento': 'PED-12345',
    'boleto.titulo': 'DM',
    'boleto.valor': '1250.43',
    'boleto.pagador.nome': 'Alberto Santos Dumont',
    'boleto.pagador.cprf': '111.111.111-11',
    'boleto.pagador.endereco.cep': '36240-000',
    'boleto.pagador.endereco.uf': 'MG',
    'boleto.pagador.endereco.localidade': 'Santos Dumont',
    'boleto.pagador.endereco.bairro': 'Casa Natal',
    'boleto.pagador.endereco.logradouro': 'BR-499',
    'boleto.pagador.endereco.numero': 's/n',
    'boleto.instrucao': 'Não receber após o vencimento'
}

response = requests.post(
    'https://sandbox.boletocloud.com/api/v1/boletos',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    data=data
)

token = response.headers.get('X-BoletoCloud-Token')
nosso_numero = response.headers.get('X-BoletoCloud-NIB-Nosso-Numero')

if response.status_code == 201:
    print('Boleto criado!')
    print(f'Token: {token}')
    print(f'Nosso Número: {nosso_numero}')
    with open('boleto.pdf', 'wb') as f:
        f.write(response.content)
elif response.status_code == 409:
    print(f'Boleto já existe. Token: {token}')
else:
    print(f'Erro: {response.text}')

Ruby

require 'net/http'
require 'uri'

uri = URI('https://sandbox.boletocloud.com/api/v1/boletos')

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Post.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request.set_form_data(
    'boleto.conta.token' => 'api-key_SEU-TOKEN-DA-CONTA',
    'boleto.emissao' => '2024-01-15',
    'boleto.vencimento' => '2024-02-15',
    'boleto.documento' => 'PED-12345',
    'boleto.titulo' => 'DM',
    'boleto.valor' => '1250.43',
    'boleto.pagador.nome' => 'Alberto Santos Dumont',
    'boleto.pagador.cprf' => '111.111.111-11',
    'boleto.pagador.endereco.cep' => '36240-000',
    'boleto.pagador.endereco.uf' => 'MG',
    'boleto.pagador.endereco.localidade' => 'Santos Dumont',
    'boleto.pagador.endereco.bairro' => 'Casa Natal',
    'boleto.pagador.endereco.logradouro' => 'BR-499',
    'boleto.pagador.endereco.numero' => 's/n',
    'boleto.instrucao' => 'Não receber após o vencimento'
  )

  response = http.request(request)
  token = response['X-BoletoCloud-Token']
  nosso_numero = response['X-BoletoCloud-NIB-Nosso-Numero']

  case response.code
  when '201'
    puts 'Boleto criado!'
    puts "Token: #{token}"
    puts "Nosso Número: #{nosso_numero}"
    File.write('boleto.pdf', response.body)
  when '409'
    puts "Boleto já existe. Token: #{token}"
  else
    puts "Erro: #{response.body}"
  end
end

Clojure

(require '[clj-http.client :as client])

(let [response (client/post
                "https://sandbox.boletocloud.com/api/v1/boletos"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :form-params {:boleto.conta.token "api-key_SEU-TOKEN-DA-CONTA"
                               :boleto.emissao "2024-01-15"
                               :boleto.vencimento "2024-02-15"
                               :boleto.documento "PED-12345"
                               :boleto.titulo "DM"
                               :boleto.valor "1250.43"
                               :boleto.pagador.nome "Alberto Santos Dumont"
                               :boleto.pagador.cprf "111.111.111-11"
                               :boleto.pagador.endereco.cep "36240-000"
                               :boleto.pagador.endereco.uf "MG"
                               :boleto.pagador.endereco.localidade "Santos Dumont"
                               :boleto.pagador.endereco.bairro "Casa Natal"
                               :boleto.pagador.endereco.logradouro "BR-499"
                               :boleto.pagador.endereco.numero "s/n"
                               :boleto.instrucao "Não receber após o vencimento"}
                 :as :byte-array
                 :throw-exceptions false})
      token (get-in response [:headers "X-BoletoCloud-Token"])
      nosso-numero (get-in response [:headers "X-BoletoCloud-NIB-Nosso-Numero"])]
  (case (:status response)
    201 (do
          (println "Boleto criado!")
          (println "Token:" token)
          (println "Nosso Número:" nosso-numero)
          (clojure.java.io/copy (:body response)
            (clojure.java.io/file "boleto.pdf")))
    409 (println "Boleto já existe. Token:" token)
    (println "Erro:" (String. (:body response)))))

---

Acesso Alternativo ao Boleto

Além de usar o endpoint da API, boletos também podem ser acessados pela URL pública:

https://sandbox.boletocloud.com/boleto/2via/{TOKEN}

Esta URL pode ser compartilhada com o pagador para que ele acesse o boleto diretamente no navegador.

---

Veja Também

Campos do BoletoReferência completa de todos os campos disponíveis

IdempotênciaComo evitar boletos duplicados

Consultar SituaçãoVisão completa do boleto em JSON

Status do RegistroVerificar se foi registrado no banco

Criar em LoteEmitir múltiplos boletos de uma vez