Criar Carnê de Pagamento

Criar Carnê (POST)

Gera múltiplos boletos organizados no formato carnê (3 boletos por página), ideal para parcelamentos e mensalidades. Diferente do endpoint /boletos, este é um processo de duas etapas: primeiro você envia os dados e recebe os tokens, depois busca o PDF consolidado.

Plano Personalizado

Este endpoint está disponível apenas para clientes do plano personalizado. O limite é de 300 boletos por requisição. Entre em contato para contratar.

O que este endpoint faz

1. Recebe um array de boletos em formato JSON
2. Valida os dados de cada boleto do lote
3. Gera os boletos no Boleto Cloud
4. Retorna tokens para cada boleto + token do carnê para obter o PDF

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  POST /carnes    │─────▶│  Validar dados   │─────▶│  Gerar boletos   │
│  (JSON batch)    │      │  de cada boleto  │      │  individuais     │
└──────────────────┘      └──────────────────┘      └──────────────────┘
                                                             │
         ┌───────────────────────────────────────────────────┘
         ▼
┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  Retornar JSON   │─────▶│  GET /carnes/    │─────▶│  Baixar PDF      │
│  com tokens      │      │  {token}         │      │  consolidado     │
└──────────────────┘      └──────────────────┘      └──────────────────┘

Fluxo em Duas Etapas

O formato carnê requer duas chamadas: primeiro POST /carnes para criar os boletos e receber os tokens, depois GET /carnes/{token} para obter o PDF com todos os boletos organizados (3 por página).

---

Quando Usar

Carnê vs Boleto Individual vs Lote

Cenário	Endpoint Recomendado	Layout do PDF
Boleto avulso	POST /boletos	1 boleto por página, PDF na resposta
Parcelamentos/mensalidades	POST /carnes	3 boletos por página
Múltiplos boletos separados	POST /batch/boletos	1 boleto por página

Cenários Recomendados para Carnê

Cenário	Recomendação
Parcelamento de vendas	Sim
Mensalidades escolares	Sim
Planos de pagamento	Sim
Financiamentos	Sim
Cobrança recorrente com boletos avulsos	Não — use Boleto Individual

Onde se encaixa no ciclo de vida

O POST /carnes é uma alternativa ao POST /boletos para quando você precisa de múltiplos boletos em formato carnê.

┌─────────────────────────────────────────────────────────────────────────────┐
│                            CRIAÇÃO DOS BOLETOS                              │
│                                                                             │
│   ┌─────────────────────┐     ┌─────────────────────┐                       │
│   │  POST /boletos      │     │  ★ POST /carnes     │                       │
│   │  (individual)       │     │  (múltiplos, 3/pág) │                       │
│   └──────────┬──────────┘     └──────────┬──────────┘                       │
│              │                           │                                  │
│              └───────────┬───────────────┘                                  │
│                          ▼                                                  │
└──────────────────────[ CRIADO ]─────────────────────────────────────────────┘
                            │
               (envio automático ou via CNAB)
                            ▼
┌──────────────────[ REGISTRO PENDENTE ]──────────────────────────────────────┐
│                                                                             │
│   Próximos endpoints para carnê:                                            │
│   • GET /carnes/{token}                → Obter PDF do carnê                 │
│   • GET /boletos/{token-individual}    → Obter boleto específico            │
│   • GET /boletos/{token}/registro      → Status do registro                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

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

Ambiente de Desenvolvimento

Use o endpoint Sandbox (https://sandbox.boletocloud.com) durante o desenvolvimento para evitar problemas como bloqueio de chamadas e inconsistência de dados.

---

Endpoint

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

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

---

Requisição

Headers

Header	Valor	Obrigatório
Authorization	Basic {credenciais_base64}	Sim
Content-Type	application/json; charset=utf-8	Sim
Accept	*/*	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/json)

O corpo da requisição contém um objeto batch com um array de boletos:

{
  "batch": {
    "boletos": [
      { /* boleto 1 */ },
      { /* boleto 2 */ },
      { /* boleto 3 */ }
    ]
  }
}

Campos de Cada Boleto

Campos Obrigatórios

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

Campos Opcionais

Campo	Tipo	Exemplo	Descrição
pagador.endereco.complemento	string	"Apto 101"	Complemento do endereço
numero	string	"12345678901-P"	NIB específico (se não informado, usa sequencial)
sequencial	integer	1	Sequencial para gerar NIB
instrucao	array	["Parcela 1 de 3"]	Instruções ao caixa (até 3 linhas)
info	array	["Referente contrato #123"]	Informações ao pagador
juros	decimal	1.00	Taxa de juros ao mês (%)
multa	decimal	2.00	Percentual de multa por atraso (%)
desconto	decimal	5.00	Percentual de desconto até vencimento (%)
tokenControleUsuario	string	"parcela-1-abc"	Token para idempotência

Exemplo de Body Completo

{
  "batch": {
    "boletos": [
      {
        "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
        "pagador": {
          "nome": "Alberto Santos Dumont",
          "cprf": "111.111.111-11",
          "endereco": {
            "cep": "36240-000",
            "uf": "MG",
            "localidade": "Santos Dumont",
            "bairro": "Casa Natal",
            "logradouro": "BR-499",
            "numero": "s/n"
          }
        },
        "instrucao": ["Parcela 1 de 3"],
        "emissao": "2024-01-15",
        "vencimento": "2024-02-15",
        "valor": 500.00,
        "titulo": "DM",
        "documento": "PARC-001",
        "sequencial": 1
      },
      {
        "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
        "pagador": {
          "nome": "Alberto Santos Dumont",
          "cprf": "111.111.111-11",
          "endereco": {
            "cep": "36240-000",
            "uf": "MG",
            "localidade": "Santos Dumont",
            "bairro": "Casa Natal",
            "logradouro": "BR-499",
            "numero": "s/n"
          }
        },
        "instrucao": ["Parcela 2 de 3"],
        "emissao": "2024-01-15",
        "vencimento": "2024-03-15",
        "valor": 500.00,
        "titulo": "DM",
        "documento": "PARC-002",
        "sequencial": 2
      },
      {
        "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
        "pagador": {
          "nome": "Alberto Santos Dumont",
          "cprf": "111.111.111-11",
          "endereco": {
            "cep": "36240-000",
            "uf": "MG",
            "localidade": "Santos Dumont",
            "bairro": "Casa Natal",
            "logradouro": "BR-499",
            "numero": "s/n"
          }
        },
        "instrucao": ["Parcela 3 de 3"],
        "emissao": "2024-01-15",
        "vencimento": "2024-04-15",
        "valor": 500.00,
        "titulo": "DM",
        "documento": "PARC-003",
        "sequencial": 3
      }
    ]
  }
}

---

Respostas

201 Created — Sucesso

O carnê foi criado com sucesso. O body contém o JSON com os tokens.

Headers da Resposta (201)

Header	Descrição	Exemplo
Content-Type	Tipo do conteúdo	application/json; charset=UTF-8
X-BoletoCloud-Token	Token do carnê (para obter PDF)	abc123def456...
Location	Path para obter o PDF do carnê	/api/v1/carnes/abc123def456
X-BoletoCloud-Version	Versão da plataforma	2.0.0

Body da Resposta (201)

{
  "batch": {
    "token": "token-do-carne-para-obter-pdf",
    "boletos": [
      { "token": "token-boleto-parcela-1" },
      { "token": "token-boleto-parcela-2" },
      { "token": "token-boleto-parcela-3" }
    ]
  }
}

Campo	Descrição
batch.token	Token do carnê — use para buscar o PDF
batch.boletos[].token	Token individual de cada boleto — use para operações em boletos específicos

Guarde os Tokens

Guarde todos os tokens no seu banco de dados:

• O batch.token para obter o PDF do carnê completo
• Os boletos[].token individuais para operações como consulta de status, baixa ou alteração de vencimento

---

409 Conflict — Boleto Já Existe

Retornado quando já existe um boleto com o mesmo Nosso Número ou tokenControleUsuario.

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 para este campo.",
        "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. Isso é especialmente útil em cenários de retry.

---

400 Bad Request — Dados Inválidos

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

Body da Resposta (400)

{
  "erro": {
    "status": 400,
    "tipo": "requisicao",
    "causas": [
      {
        "codigo": "842EF62A",
        "mensagem": "Campo (boleto.vencimento) - O valor informado não corresponde com o formato válido (AAAA-MM-DD).",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Erros Comuns de Validação

Campo	Formato Incorreto	Formato Correto
emissao	15/01/2024	2024-01-15
vencimento	15-02-2024	2024-02-15
valor	1.500,00	1500.00
pagador.cprf	11111111111	111.111.111-11

---

Comunicação com o Banco

Após a criação dos boletos do carnê, a comunicação com o banco funciona da mesma forma que boletos individuais:

Tipo de Comunicação	Comportamento
API/Webservice (automático)	Os boletos são enviados automaticamente para registro no banco
Arquivo CNAB (manual)	Os boletos são incluídos no próximo arquivo de remessa

Nota

Para verificar se os boletos foram registrados, use o endpoint Status do Registro com o token individual de cada boleto.

---

Próximo Passo: Obter o PDF

Após criar o carnê, use o token retornado para obter o PDF:

GET https://sandbox.boletocloud.com/api/v1/carnes/{token}

Buscar PDF do Carnê Obter o PDF consolidado com 3 boletos por página

---

Idempotência (Evitando Duplicação)

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

{
  "batch": {
    "boletos": [
      {
        "tokenControleUsuario": "pedido-123-parcela-1",
        ...
      },
      {
        "tokenControleUsuario": "pedido-123-parcela-2",
        ...
      }
    ]
  }
}

Idempotência Documentação completa sobre como evitar boletos duplicados

---

Exemplos de Código — Criar Carnê

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/carnes" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: */*" \
  -X "POST" \
  -u "api-key_SUA-API-KEY:token" \
  -d '{
    "batch": {
      "boletos": [
        {
          "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
          "pagador": {
            "nome": "Alberto Santos Dumont",
            "cprf": "111.111.111-11",
            "endereco": {
              "cep": "36240-000",
              "uf": "MG",
              "localidade": "Santos Dumont",
              "bairro": "Casa Natal",
              "logradouro": "BR-499",
              "numero": "s/n"
            }
          },
          "instrucao": ["Parcela 1 de 3"],
          "emissao": "2024-01-15",
          "vencimento": "2024-02-15",
          "valor": 500.00,
          "titulo": "DM",
          "documento": "PARC-001",
          "sequencial": 1
        },
        {
          "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
          "pagador": {
            "nome": "Alberto Santos Dumont",
            "cprf": "111.111.111-11",
            "endereco": {
              "cep": "36240-000",
              "uf": "MG",
              "localidade": "Santos Dumont",
              "bairro": "Casa Natal",
              "logradouro": "BR-499",
              "numero": "s/n"
            }
          },
          "instrucao": ["Parcela 2 de 3"],
          "emissao": "2024-01-15",
          "vencimento": "2024-03-15",
          "valor": 500.00,
          "titulo": "DM",
          "documento": "PARC-002",
          "sequencial": 2
        },
        {
          "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
          "pagador": {
            "nome": "Alberto Santos Dumont",
            "cprf": "111.111.111-11",
            "endereco": {
              "cep": "36240-000",
              "uf": "MG",
              "localidade": "Santos Dumont",
              "bairro": "Casa Natal",
              "logradouro": "BR-499",
              "numero": "s/n"
            }
          },
          "instrucao": ["Parcela 3 de 3"],
          "emissao": "2024-01-15",
          "vencimento": "2024-04-15",
          "valor": 500.00,
          "titulo": "DM",
          "documento": "PARC-003",
          "sequencial": 3
        }
      ]
    }
  }'

# O token do carnê estará no header X-BoletoCloud-Token
# Use esse token para buscar o PDF: GET /carnes/{token}

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
import static javax.ws.rs.core.Response.Status.CREATED;

public class CriarCarne {
    public static void main(String[] args) {
        String json = """
            {
              "batch": {
                "boletos": [
                  {
                    "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                    "pagador": {
                      "nome": "Alberto Santos Dumont",
                      "cprf": "111.111.111-11",
                      "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                      }
                    },
                    "instrucao": ["Parcela 1 de 3"],
                    "emissao": "2024-01-15",
                    "vencimento": "2024-02-15",
                    "valor": 500.00,
                    "titulo": "DM",
                    "documento": "PARC-001",
                    "sequencial": 1
                  },
                  {
                    "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                    "pagador": {
                      "nome": "Alberto Santos Dumont",
                      "cprf": "111.111.111-11",
                      "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                      }
                    },
                    "instrucao": ["Parcela 2 de 3"],
                    "emissao": "2024-01-15",
                    "vencimento": "2024-03-15",
                    "valor": 500.00,
                    "titulo": "DM",
                    "documento": "PARC-002",
                    "sequencial": 2
                  },
                  {
                    "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                    "pagador": {
                      "nome": "Alberto Santos Dumont",
                      "cprf": "111.111.111-11",
                      "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                      }
                    },
                    "instrucao": ["Parcela 3 de 3"],
                    "emissao": "2024-01-15",
                    "vencimento": "2024-04-15",
                    "valor": 500.00,
                    "titulo": "DM",
                    "documento": "PARC-003",
                    "sequencial": 3
                  }
                ]
              }
            }
            """;

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

        if (response.getStatus() == CREATED.getStatusCode()) {
            String carneToken = response.getHeaderString("X-BoletoCloud-Token");
            String location = response.getHeaderString("Location");
            String body = response.readEntity(String.class);

            System.out.println("Carne criado com sucesso!");
            System.out.println("Token do carne: " + carneToken);
            System.out.println("Location: " + location);
            System.out.println("Response: " + body);

            // Proximo passo: GET /carnes/{carneToken} para obter o PDF
        } else {
            System.out.println("Erro: " + response.readEntity(String.class));
        }
    }
}

Kotlin

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

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

    val json = """
        {
          "batch": {
            "boletos": [
              {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                  "nome": "Alberto Santos Dumont",
                  "cprf": "111.111.111-11",
                  "endereco": {
                    "cep": "36240-000",
                    "uf": "MG",
                    "localidade": "Santos Dumont",
                    "bairro": "Casa Natal",
                    "logradouro": "BR-499",
                    "numero": "s/n"
                  }
                },
                "instrucao": ["Parcela 1 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-02-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-001",
                "sequencial": 1
              },
              {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                  "nome": "Alberto Santos Dumont",
                  "cprf": "111.111.111-11",
                  "endereco": {
                    "cep": "36240-000",
                    "uf": "MG",
                    "localidade": "Santos Dumont",
                    "bairro": "Casa Natal",
                    "logradouro": "BR-499",
                    "numero": "s/n"
                  }
                },
                "instrucao": ["Parcela 2 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-03-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-002",
                "sequencial": 2
              },
              {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                  "nome": "Alberto Santos Dumont",
                  "cprf": "111.111.111-11",
                  "endereco": {
                    "cep": "36240-000",
                    "uf": "MG",
                    "localidade": "Santos Dumont",
                    "bairro": "Casa Natal",
                    "logradouro": "BR-499",
                    "numero": "s/n"
                  }
                },
                "instrucao": ["Parcela 3 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-04-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-003",
                "sequencial": 3
              }
            ]
          }
        }
    """.trimIndent()

    val body = json.toRequestBody("application/json; charset=utf-8".toMediaType())

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

    client.newCall(request).execute().use { response ->
        when (response.code) {
            201 -> {
                val carneToken = response.header("X-BoletoCloud-Token")
                println("Carne criado com sucesso!")
                println("Token: $carneToken")
                println("Response: ${response.body?.string()}")
                // Proximo passo: GET /carnes/$carneToken para obter o PDF
            }
            409 -> println("Carne ja existe")
            else -> println("Erro: ${response.code}")
        }
    }
}

C#

using System;
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 json = @"{
          ""batch"": {
            ""boletos"": [
              {
                ""conta"": {""token"": ""api-key_SEU-TOKEN-DA-CONTA""},
                ""pagador"": {
                  ""nome"": ""Alberto Santos Dumont"",
                  ""cprf"": ""111.111.111-11"",
                  ""endereco"": {
                    ""cep"": ""36240-000"",
                    ""uf"": ""MG"",
                    ""localidade"": ""Santos Dumont"",
                    ""bairro"": ""Casa Natal"",
                    ""logradouro"": ""BR-499"",
                    ""numero"": ""s/n""
                  }
                },
                ""instrucao"": [""Parcela 1 de 3""],
                ""emissao"": ""2024-01-15"",
                ""vencimento"": ""2024-02-15"",
                ""valor"": 500.00,
                ""titulo"": ""DM"",
                ""documento"": ""PARC-001"",
                ""sequencial"": 1
              },
              {
                ""conta"": {""token"": ""api-key_SEU-TOKEN-DA-CONTA""},
                ""pagador"": {
                  ""nome"": ""Alberto Santos Dumont"",
                  ""cprf"": ""111.111.111-11"",
                  ""endereco"": {
                    ""cep"": ""36240-000"",
                    ""uf"": ""MG"",
                    ""localidade"": ""Santos Dumont"",
                    ""bairro"": ""Casa Natal"",
                    ""logradouro"": ""BR-499"",
                    ""numero"": ""s/n""
                  }
                },
                ""instrucao"": [""Parcela 2 de 3""],
                ""emissao"": ""2024-01-15"",
                ""vencimento"": ""2024-03-15"",
                ""valor"": 500.00,
                ""titulo"": ""DM"",
                ""documento"": ""PARC-002"",
                ""sequencial"": 2
              },
              {
                ""conta"": {""token"": ""api-key_SEU-TOKEN-DA-CONTA""},
                ""pagador"": {
                  ""nome"": ""Alberto Santos Dumont"",
                  ""cprf"": ""111.111.111-11"",
                  ""endereco"": {
                    ""cep"": ""36240-000"",
                    ""uf"": ""MG"",
                    ""localidade"": ""Santos Dumont"",
                    ""bairro"": ""Casa Natal"",
                    ""logradouro"": ""BR-499"",
                    ""numero"": ""s/n""
                  }
                },
                ""instrucao"": [""Parcela 3 de 3""],
                ""emissao"": ""2024-01-15"",
                ""vencimento"": ""2024-04-15"",
                ""valor"": 500.00,
                ""titulo"": ""DM"",
                ""documento"": ""PARC-003"",
                ""sequencial"": 3
              }
            ]
          }
        }";

        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await client.PostAsync(
            "https://sandbox.boletocloud.com/api/v1/carnes", content);

        var statusCode = (int)response.StatusCode;
        var responseBody = await response.Content.ReadAsStringAsync();

        switch (statusCode)
        {
            case 201:
                var carneToken = string.Join("",
                    response.Headers.GetValues("X-BoletoCloud-Token"));
                Console.WriteLine("Carne criado com sucesso!");
                Console.WriteLine($"Token: {carneToken}");
                Console.WriteLine($"Response: {responseBody}");
                // Proximo passo: GET /carnes/{carneToken} para obter o PDF
                break;
            case 409:
                Console.WriteLine("Carne ja existe");
                break;
            default:
                Console.WriteLine($"Erro ({statusCode}): {responseBody}");
                break;
        }
    }
}

Node

const https = require('https');

const json = JSON.stringify({
  batch: {
    boletos: [
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 1 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-02-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-001",
        sequencial: 1
      },
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 2 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-03-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-002",
        sequencial: 2
      },
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 3 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-04-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-003",
        sequencial: 3
      }
    ]
  }
});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/carnes',
  method: 'POST',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': Buffer.byteLength(json)
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => {
    const carneToken = res.headers['x-boletocloud-token'];

    switch (res.statusCode) {
      case 201:
        console.log('Carne criado com sucesso!');
        console.log('Token:', carneToken);
        const result = JSON.parse(data);
        console.log('Boletos:', result.batch.boletos.length);
        result.batch.boletos.forEach((b, i) =>
          console.log(`Parcela ${i+1}: ${b.token}`));
        // Proximo passo: GET /carnes/{carneToken} para obter o PDF
        break;
      case 409:
        console.log('Carne ja existe. Token:', carneToken);
        break;
      default:
        console.log(`Erro (${res.statusCode}):`, data);
    }
  });
});

req.write(json);
req.end();

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    jsonData := `{
      "batch": {
        "boletos": [
          {
            "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
            "pagador": {
              "nome": "Alberto Santos Dumont",
              "cprf": "111.111.111-11",
              "endereco": {
                "cep": "36240-000",
                "uf": "MG",
                "localidade": "Santos Dumont",
                "bairro": "Casa Natal",
                "logradouro": "BR-499",
                "numero": "s/n"
              }
            },
            "instrucao": ["Parcela 1 de 3"],
            "emissao": "2024-01-15",
            "vencimento": "2024-02-15",
            "valor": 500.00,
            "titulo": "DM",
            "documento": "PARC-001",
            "sequencial": 1
          },
          {
            "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
            "pagador": {
              "nome": "Alberto Santos Dumont",
              "cprf": "111.111.111-11",
              "endereco": {
                "cep": "36240-000",
                "uf": "MG",
                "localidade": "Santos Dumont",
                "bairro": "Casa Natal",
                "logradouro": "BR-499",
                "numero": "s/n"
              }
            },
            "instrucao": ["Parcela 2 de 3"],
            "emissao": "2024-01-15",
            "vencimento": "2024-03-15",
            "valor": 500.00,
            "titulo": "DM",
            "documento": "PARC-002",
            "sequencial": 2
          },
          {
            "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
            "pagador": {
              "nome": "Alberto Santos Dumont",
              "cprf": "111.111.111-11",
              "endereco": {
                "cep": "36240-000",
                "uf": "MG",
                "localidade": "Santos Dumont",
                "bairro": "Casa Natal",
                "logradouro": "BR-499",
                "numero": "s/n"
              }
            },
            "instrucao": ["Parcela 3 de 3"],
            "emissao": "2024-01-15",
            "vencimento": "2024-04-15",
            "valor": 500.00,
            "titulo": "DM",
            "documento": "PARC-003",
            "sequencial": 3
          }
        ]
      }
    }`

    req, _ := http.NewRequest("POST",
        "https://sandbox.boletocloud.com/api/v1/carnes",
        bytes.NewBufferString(jsonData))
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type", "application/json; charset=utf-8")

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

    body, _ := io.ReadAll(resp.Body)
    carneToken := resp.Header.Get("X-BoletoCloud-Token")

    switch resp.StatusCode {
    case 201:
        fmt.Println("Carne criado com sucesso!")
        fmt.Println("Token:", carneToken)
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        fmt.Printf("Response: %+v\n", result)
        // Proximo passo: GET /carnes/{carneToken} para obter o PDF
    case 409:
        fmt.Println("Carne ja existe. Token:", carneToken)
    default:
        fmt.Printf("Erro (%d): %s\n", resp.StatusCode, string(body))
    }
}

PHP

<?php
$boleto1 = [
    'conta' => ['token' => 'api-key_SEU-TOKEN-DA-CONTA'],
    'pagador' => [
        'nome' => 'Alberto Santos Dumont',
        'cprf' => '111.111.111-11',
        'endereco' => [
            'cep' => '36240-000',
            'uf' => 'MG',
            'localidade' => 'Santos Dumont',
            'bairro' => 'Casa Natal',
            'logradouro' => 'BR-499',
            'numero' => 's/n'
        ]
    ],
    'instrucao' => ['Parcela 1 de 3'],
    'emissao' => '2024-01-15',
    'vencimento' => '2024-02-15',
    'valor' => 500.00,
    'titulo' => 'DM',
    'documento' => 'PARC-001',
    'sequencial' => 1
];

$boleto2 = $boleto1;
$boleto2['sequencial'] = 2;
$boleto2['documento'] = 'PARC-002';
$boleto2['vencimento'] = '2024-03-15';
$boleto2['instrucao'] = ['Parcela 2 de 3'];

$boleto3 = $boleto1;
$boleto3['sequencial'] = 3;
$boleto3['documento'] = 'PARC-003';
$boleto3['vencimento'] = '2024-04-15';
$boleto3['instrucao'] = ['Parcela 3 de 3'];

$batch = ['batch' => ['boletos' => [$boleto1, $boleto2, $boleto3]]];
$json = json_encode($batch, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://sandbox.boletocloud.com/api/v1/carnes');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: */*',
    'Content-Type: application/json; charset=utf-8'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_USERPWD, "api-key_SUA-API-KEY:token");
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 token do header
preg_match('/X-BoletoCloud-Token:\s*(.+)/i', $headers, $tokenMatch);
$carneToken = trim($tokenMatch[1] ?? '');

switch ($http_code) {
    case 201:
        $result = json_decode($body, true);
        echo "Carne criado com sucesso!\n";
        echo "Token do carne: $carneToken\n";
        foreach ($result['batch']['boletos'] as $i => $boleto) {
            echo "Parcela " . ($i + 1) . ": " . $boleto['token'] . "\n";
        }
        // Proximo passo: GET /carnes/{carneToken} para obter o PDF
        break;
    case 409:
        echo "Carne ja existe. Token: $carneToken\n";
        break;
    default:
        echo "Erro ($http_code): $body\n";
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

data = {
    "batch": {
        "boletos": [
            {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                    "nome": "Alberto Santos Dumont",
                    "cprf": "111.111.111-11",
                    "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                    }
                },
                "instrucao": ["Parcela 1 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-02-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-001",
                "sequencial": 1
            },
            {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                    "nome": "Alberto Santos Dumont",
                    "cprf": "111.111.111-11",
                    "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                    }
                },
                "instrucao": ["Parcela 2 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-03-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-002",
                "sequencial": 2
            },
            {
                "conta": {"token": "api-key_SEU-TOKEN-DA-CONTA"},
                "pagador": {
                    "nome": "Alberto Santos Dumont",
                    "cprf": "111.111.111-11",
                    "endereco": {
                        "cep": "36240-000",
                        "uf": "MG",
                        "localidade": "Santos Dumont",
                        "bairro": "Casa Natal",
                        "logradouro": "BR-499",
                        "numero": "s/n"
                    }
                },
                "instrucao": ["Parcela 3 de 3"],
                "emissao": "2024-01-15",
                "vencimento": "2024-04-15",
                "valor": 500.00,
                "titulo": "DM",
                "documento": "PARC-003",
                "sequencial": 3
            }
        ]
    }
}

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

carne_token = response.headers.get('X-BoletoCloud-Token')

if response.status_code == 201:
    print('Carne criado com sucesso!')
    print(f'Token do carne: {carne_token}')
    result = response.json()
    for i, boleto in enumerate(result['batch']['boletos']):
        print(f"Parcela {i+1}: {boleto['token']}")
    # Proximo passo: GET /carnes/{carne_token} para obter o PDF
elif response.status_code == 409:
    print(f'Carne ja existe. Token: {carne_token}')
else:
    print(f'Erro ({response.status_code}): {response.text}')

Ruby

require 'net/http'
require 'uri'
require 'json'

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

data = {
  batch: {
    boletos: [
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 1 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-02-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-001",
        sequencial: 1
      },
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 2 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-03-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-002",
        sequencial: 2
      },
      {
        conta: { token: "api-key_SEU-TOKEN-DA-CONTA" },
        pagador: {
          nome: "Alberto Santos Dumont",
          cprf: "111.111.111-11",
          endereco: {
            cep: "36240-000",
            uf: "MG",
            localidade: "Santos Dumont",
            bairro: "Casa Natal",
            logradouro: "BR-499",
            numero: "s/n"
          }
        },
        instrucao: ["Parcela 3 de 3"],
        emissao: "2024-01-15",
        vencimento: "2024-04-15",
        valor: 500.00,
        titulo: "DM",
        documento: "PARC-003",
        sequencial: 3
      }
    ]
  }
}

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['Content-Type'] = 'application/json; charset=utf-8'
  request.body = data.to_json

  response = http.request(request)
  carne_token = response['X-BoletoCloud-Token']

  case response.code
  when '201'
    puts 'Carne criado com sucesso!'
    puts "Token do carne: #{carne_token}"
    result = JSON.parse(response.body)
    result['batch']['boletos'].each_with_index do |boleto, i|
      puts "Parcela #{i+1}: #{boleto['token']}"
    end
    # Proximo passo: GET /carnes/#{carne_token} para obter o PDF
  when '409'
    puts "Carne ja existe. Token: #{carne_token}"
  else
    puts "Erro (#{response.code}): #{response.body}"
  end
end

Clojure

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

(let [data {:batch
            {:boletos
             [{:conta {:token "api-key_SEU-TOKEN-DA-CONTA"}
               :pagador {:nome "Alberto Santos Dumont"
                         :cprf "111.111.111-11"
                         :endereco {:cep "36240-000"
                                    :uf "MG"
                                    :localidade "Santos Dumont"
                                    :bairro "Casa Natal"
                                    :logradouro "BR-499"
                                    :numero "s/n"}}
               :instrucao ["Parcela 1 de 3"]
               :emissao "2024-01-15"
               :vencimento "2024-02-15"
               :valor 500.00
               :titulo "DM"
               :documento "PARC-001"
               :sequencial 1}
              {:conta {:token "api-key_SEU-TOKEN-DA-CONTA"}
               :pagador {:nome "Alberto Santos Dumont"
                         :cprf "111.111.111-11"
                         :endereco {:cep "36240-000"
                                    :uf "MG"
                                    :localidade "Santos Dumont"
                                    :bairro "Casa Natal"
                                    :logradouro "BR-499"
                                    :numero "s/n"}}
               :instrucao ["Parcela 2 de 3"]
               :emissao "2024-01-15"
               :vencimento "2024-03-15"
               :valor 500.00
               :titulo "DM"
               :documento "PARC-002"
               :sequencial 2}
              {:conta {:token "api-key_SEU-TOKEN-DA-CONTA"}
               :pagador {:nome "Alberto Santos Dumont"
                         :cprf "111.111.111-11"
                         :endereco {:cep "36240-000"
                                    :uf "MG"
                                    :localidade "Santos Dumont"
                                    :bairro "Casa Natal"
                                    :logradouro "BR-499"
                                    :numero "s/n"}}
               :instrucao ["Parcela 3 de 3"]
               :emissao "2024-01-15"
               :vencimento "2024-04-15"
               :valor 500.00
               :titulo "DM"
               :documento "PARC-003"
               :sequencial 3}]}}
      response (client/post
                "https://sandbox.boletocloud.com/api/v1/carnes"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :content-type :json
                 :body (json/write-str data)
                 :as :json
                 :throw-exceptions false})
      carne-token (get-in response [:headers "X-BoletoCloud-Token"])]
  (case (:status response)
    201 (do
          (println "Carne criado com sucesso!")
          (println "Token do carne:" carne-token)
          (doseq [[i boleto] (map-indexed vector
                               (get-in response [:body :batch :boletos]))]
            (println (str "Parcela " (inc i) ": " (:token boleto)))))
          ;; Proximo passo: GET /carnes/{carne-token} para obter o PDF
    409 (println "Carne ja existe. Token:" carne-token)
    (println "Erro:" (:status response))))

---

Veja Tambem

Buscar PDF do Carne Obter o PDF consolidado apos criar o carne

Campos do Boleto Referencia completa de todos os campos

Idempotencia Como evitar boletos duplicados

Criar em Lote Emitir multiplos boletos (1 por pagina)