Criar Boletos em Batch

Criar Batch (POST)

Cria múltiplos boletos de uma só vez, gerando um PDF com 1 boleto por página. Ideal para emissão em massa de boletos diversos (diferentes pagadores, valores ou vencimentos).

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 array de boletos no formato JSON
2. Valida os dados de cada boleto
3. Cria os boletos na plataforma
4. Retorna JSON com tokens para buscar o PDF

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  POST /batch/    │─────▶│   Validar e      │─────▶│   Retornar       │
│  boletos         │      │   criar boletos  │      │   tokens (JSON)  │
└──────────────────┘      └──────────────────┘      └──────────────────┘
                                                             │
                                                             ▼
┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  Retornar PDF    │◀─────│   Gerar PDF      │◀─────│  GET /batch/     │
│  (1 por página)  │      │   consolidado    │      │  boletos/{token} │
└──────────────────┘      └──────────────────┘      └──────────────────┘

Fluxo em Duas Etapas

Diferente do endpoint /boletos que retorna o PDF diretamente, o endpoint /batch/boletos requer duas chamadas:

1. POST para criar os boletos → recebe JSON com tokens
2. GET para buscar o PDF → recebe o arquivo PDF

---

Quando Usar

Cenário	Descrição
Emissão em massa	Gerar vários boletos de uma vez para diferentes clientes
Cobranças diversas	Boletos com valores, vencimentos ou pagadores diferentes
Integração automatizada	Processos batch que geram múltiplos boletos periodicamente

Comparação com Outros Endpoints

Endpoint	Layout PDF	Plano	Limite	Uso Típico
POST /batch/boletos	1 boleto/página	Personalizado	300/req	Emissão em massa
POST /carnes	3 boletos/página	Personalizado	300/req	Parcelamentos
POST /boletos	1 boleto (direto)	Gratuito/Personalizado	1/req	Boleto individual

---

Endpoint

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

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

---

Requisição

Headers

Header	Valor	Obrigatório
Content-Type	application/json; charset=utf-8	Sim
Accept	*/*	Não
Authorization	Basic {credenciais_base64}	Sim

Estrutura do Body

{
  "batch": {
    "boletos": [
      {
        "conta": {"token": "api-key_TOKEN-DA-CONTA"},
        "pagador": {
          "nome": "Cliente 1",
          "cprf": "111.111.111-11",
          "endereco": {
            "cep": "36240-000",
            "uf": "MG",
            "localidade": "Santos Dumont",
            "bairro": "Centro",
            "logradouro": "Rua Principal",
            "numero": "100"
          }
        },
        "emissao": "2024-01-15",
        "vencimento": "2024-02-15",
        "valor": 150.00,
        "documento": "DOC-001",
        "sequencial": 1
      },
      {
        "conta": {"token": "api-key_TOKEN-DA-CONTA"},
        "pagador": {
          "nome": "Cliente 2",
          "cprf": "222.222.222-22",
          "endereco": {
            "cep": "01310-100",
            "uf": "SP",
            "localidade": "São Paulo",
            "bairro": "Paulista",
            "logradouro": "Av. Paulista",
            "numero": "1000"
          }
        },
        "emissao": "2024-01-15",
        "vencimento": "2024-02-20",
        "valor": 250.00,
        "documento": "DOC-002",
        "sequencial": 2
      }
    ]
  }
}

Campos do Boleto

Cada boleto no array aceita os mesmos campos do endpoint /boletos. Consulte a referência completa de campos para todas as opções disponíveis.

---

Respostas

201 Created — Sucesso

O lote foi criado com sucesso. A resposta contém os tokens necessários para buscar o PDF.

Headers da Resposta (201)

Header	Descrição	Exemplo
X-BoletoCloud-Version	Versão da plataforma	2.0.0
X-BoletoCloud-Token	Token do lote (para buscar PDF)	abc123...
Location	URL para buscar o PDF	/api/v1/batch/boletos/abc123...
Content-Type	Tipo do conteúdo	application/json; charset=UTF-8

Body da Resposta (201)

{
  "batch": {
    "token": "xYz789AbCdEfGhIjKlMnOpQrStUvWxYz-A1B2C3D4E5F=",
    "boletos": [
      { "token": "token-boleto-1-abc123..." },
      { "token": "token-boleto-2-def456..." }
    ]
  }
}

Campo	Descrição
batch.token	Token para buscar o PDF consolidado via GET
batch.boletos[].token	Token individual de cada boleto (para operações específicas)

---

409 Conflict — Boleto Duplicado

Retornado quando já existe um boleto com os mesmos dados únicos.

{
  "erro": {
    "status": 409,
    "tipo": "conflito",
    "causas": [
      {
        "codigo": "XXXXXXXX",
        "mensagem": "Boleto já existe com esses dados.",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

Idempotência

Use o campo tokenControleUsuario em cada boleto para controlar duplicatas. Veja Idempotência.

---

400 Bad Request — Erro de Validação

Retornado quando há erros nos dados enviados.

{
  "erro": {
    "status": 400,
    "tipo": "validacao",
    "causas": [
      {
        "codigo": "XXXXXXXX",
        "mensagem": "Campo obrigatório não informado.",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

---

Buscar o PDF (Segunda Etapa)

Após criar o lote, use o token retornado para buscar o PDF consolidado:

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

Buscar PDF do Lote Documentação completa do endpoint GET /batch/boletos/{token}

---

Comunicação com o Banco

Os boletos criados via lote seguem o mesmo ciclo de vida de boletos individuais:

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CRIAÇÃO DOS BOLETOS                                │
│                                                                                 │
│   POST /batch/boletos                                                           │
│   ► Boletos criados com status: CRIADO                                          │
│   ► PDF gerado e disponível via GET /batch/boletos/{token}                      │
│                                                                                 │
└────────────────────────────────────┬────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         REGISTRO NO BANCO / PSP                                 │
│                                                                                 │
│   Via CNAB Remessa, API Bancária ou VAN                                         │
│   ► Boletos enviados para registro                                              │
│   ► Status: REGISTRADO (após confirmação)                                       │
│                                                                                 │
└────────────────────────────────────┬────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              PAGAMENTO                                          │
│                                                                                 │
│   Pagador efetua pagamento via boleto ou PIX                                    │
│   ► Status: LIQUIDADO                                                           │
│   ► Informação disponível via CNAB Retorno ou Webhook                           │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Registro Bancário

Os boletos do lote precisam ser registrados no banco antes de poderem ser pagos. Use CNAB Remessa ou aguarde o registro automático (plano personalizado).

Exemplos de Código - Criar Batch

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/batch/boletos" \
  -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"
            }
          },
          "emissao": "2024-01-15",
          "vencimento": "2024-02-15",
          "valor": 150.43,
          "titulo": "DM",
          "documento": "EX1",
          "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"
            }
          },
          "emissao": "2024-01-15",
          "vencimento": "2024-02-15",
          "valor": 150.43,
          "titulo": "DM",
          "documento": "EX2",
          "sequencial": 2
        }
      ]
    }
  }' \
  -o batch-response.json

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 CriarBatchBoletos {
    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"
                      }
                    },
                    "emissao": "2024-01-15",
                    "vencimento": "2024-02-15",
                    "valor": 150.43,
                    "titulo": "DM",
                    "documento": "EX1",
                    "sequencial": 1
                  }
                ]
              }
            }
            """;

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

        if (response.getStatus() == CREATED.getStatusCode()) {
            String batchToken = response.getHeaderString("X-BoletoCloud-Token");
            String location = response.getHeaderString("Location");
            System.out.println("Batch criado com sucesso!");
            System.out.println("Token: " + batchToken);
            System.out.println("Location: " + location);
            System.out.println("Response: " + response.readEntity(String.class));
        } 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"
                  }
                },
                "emissao": "2024-01-15",
                "vencimento": "2024-02-15",
                "valor": 150.43,
                "titulo": "DM",
                "documento": "EX1",
                "sequencial": 1
              }
            ]
          }
        }
    """.trimIndent()

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

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

    client.newCall(request).execute().use { response ->
        if (response.code == 201) {
            val batchToken = response.header("X-BoletoCloud-Token")
            val location = response.header("Location")
            println("Batch criado com sucesso!")
            println("Token: $batchToken")
            println("Location: $location")
            println("Response: ${response.body?.string()}")
        } 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""
                  }
                },
                ""emissao"": ""2024-01-15"",
                ""vencimento"": ""2024-02-15"",
                ""valor"": 150.43,
                ""titulo"": ""DM"",
                ""documento"": ""EX1"",
                ""sequencial"": 1
              }
            ]
          }
        }";

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

        if ((int)response.StatusCode == 201) {
            var batchToken = response.Headers.GetValues("X-BoletoCloud-Token");
            var location = response.Headers.Location;
            var responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Batch criado com sucesso!");
            Console.WriteLine($"Token: {string.Join("", batchToken)}");
            Console.WriteLine($"Location: {location}");
            Console.WriteLine($"Response: {responseBody}");
        } else {
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
        }
    }
}

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"
          }
        },
        emissao: "2024-01-15",
        vencimento: "2024-02-15",
        valor: 150.43,
        titulo: "DM",
        documento: "EX1",
        sequencial: 1
      }
    ]
  }
});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/batch/boletos',
  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', () => {
    if (res.statusCode === 201) {
      console.log('Batch criado com sucesso!');
      console.log('Token:', res.headers['x-boletocloud-token']);
      console.log('Location:', res.headers['location']);
      console.log('Response:', JSON.parse(data));
    } else {
      console.log(`Erro: ${res.statusCode}`);
    }
  });
});

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"
              }
            },
            "emissao": "2024-01-15",
            "vencimento": "2024-02-15",
            "valor": 150.43,
            "titulo": "DM",
            "documento": "EX1",
            "sequencial": 1
          }
        ]
      }
    }`

    req, _ := http.NewRequest("POST",
        "https://sandbox.boletocloud.com/api/v1/batch/boletos",
        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)

    if resp.StatusCode == 201 {
        fmt.Println("Batch criado com sucesso!")
        fmt.Println("Token:", resp.Header.Get("X-BoletoCloud-Token"))
        fmt.Println("Location:", resp.Header.Get("Location"))
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        fmt.Printf("Response: %+v\n", result)
    } else {
        fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

PHP

<?php
$boleto1 = array(
    'conta' => array('token' => 'api-key_SEU-TOKEN-DA-CONTA'),
    'pagador' => array(
        'nome' => 'Alberto Santos Dumont',
        'cprf' => '111.111.111-11',
        'endereco' => array(
            'cep' => '36240-000',
            'uf' => 'MG',
            'localidade' => 'Santos Dumont',
            'bairro' => 'Casa Natal',
            'logradouro' => 'BR-499',
            'numero' => 's/n'
        )
    ),
    'emissao' => '2024-01-15',
    'vencimento' => '2024-02-15',
    'valor' => 150.43,
    'titulo' => 'DM',
    'documento' => 'EX1',
    'sequencial' => 1
);

$boleto2 = $boleto1;
$boleto2['sequencial'] = 2;
$boleto2['documento'] = 'EX2';

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

$host = 'https://sandbox.boletocloud.com';
$api_key = 'api-key_SUA-API-KEY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $host . '/api/v1/batch/boletos');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Accept: */*',
    'Content-Type: application/json; charset=utf-8'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
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);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);

if ($http_code == 201) {
    $batch_array = json_decode($body, true);
    $batch_token = $batch_array['batch']['token'];
    echo "Batch criado com sucesso!\n";
    echo "Token do batch: $batch_token\n";
    foreach ($batch_array['batch']['boletos'] as $index => $boleto) {
        echo "Token boleto " . ($index + 1) . ": " . $boleto['token'] . "\n";
    }
} else {
    echo "Erro ($http_code): $body\n";
}
?>

Python

import requests
import json
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"
                    }
                },
                "emissao": "2024-01-15",
                "vencimento": "2024-02-15",
                "valor": 150.43,
                "titulo": "DM",
                "documento": "EX1",
                "sequencial": 1
            }
        ]
    }
}

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

if response.status_code == 201:
    batch_token = response.headers.get('X-BoletoCloud-Token')
    location = response.headers.get('Location')
    print('Batch criado com sucesso!')
    print(f'Token: {batch_token}')
    print(f'Location: {location}')
    result = response.json()
    for i, boleto in enumerate(result['batch']['boletos']):
        print(f"Token boleto {i+1}: {boleto['token']}")
else:
    print(f'Erro: {response.status_code}')

Ruby

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

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

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"
          }
        },
        emissao: "2024-01-15",
        vencimento: "2024-02-15",
        valor: 150.43,
        titulo: "DM",
        documento: "EX1",
        sequencial: 1
      }
    ]
  }
}

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)
  if response.code == '201'
    puts 'Batch criado com sucesso!'
    puts "Token: #{response['X-BoletoCloud-Token']}"
    puts "Location: #{response['Location']}"
    result = JSON.parse(response.body)
    result['batch']['boletos'].each_with_index do |boleto, i|
      puts "Token boleto #{i+1}: #{boleto['token']}"
    end
  else
    puts "Erro: #{response.code}"
  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"}}
               :emissao "2024-01-15"
               :vencimento "2024-02-15"
               :valor 150.43
               :titulo "DM"
               :documento "EX1"
               :sequencial 1}]}}
      response (client/post
                "https://sandbox.boletocloud.com/api/v1/batch/boletos"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :content-type :json
                 :body (json/write-str data)
                 :as :json
                 :throw-exceptions false})]
  (if (= 201 (:status response))
    (do
      (println "Batch criado com sucesso!")
      (println "Token:" (get-in response [:headers "X-BoletoCloud-Token"]))
      (println "Location:" (get-in response [:headers "Location"]))
      (doseq [[i boleto] (map-indexed vector (get-in response [:body :batch :boletos]))]
        (println (str "Token boleto " (inc i) ": " (:token boleto)))))
    (println "Erro:" (:status response))))

Exemplos de Código - Buscar PDF do Batch

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/batch/boletos/{token_do_batch}" \
  -u "api-key_SUA-API-KEY:token" \
  -o boletos-batch.pdf

Java

import javax.ws.rs.client.ClientBuilder;
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 javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.OK;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;

public class BuscarPdfBatch {
    public static void main(String[] args) throws Exception {
        String batchToken = "TOKEN_DO_BATCH";

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/batch/boletos")
            .path("/" + batchToken)
            .register(HttpAuthenticationFeature.basic(
                "api-key_SUA-API-KEY",
                "token"))
            .request(WILDCARD)
            .get();

        if (response.getStatus() == OK.getStatusCode()) {
            Files.copy(
                response.readEntity(InputStream.class),
                Paths.get("boletos-batch.pdf"),
                REPLACE_EXISTING
            );
            System.out.println("PDF do batch salvo com sucesso!");
        } else {
            System.out.println("Erro: " + response.getStatus());
        }
    }
}

Kotlin

import okhttp3.*
import java.io.File

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

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

    client.newCall(request).execute().use { response ->
        if (response.code == 200) {
            File("boletos-batch.pdf").writeBytes(response.body!!.bytes())
            println("PDF do batch salvo com sucesso!")
        } else {
            println("Erro: ${response.code}")
        }
    }
}

C#

using System;
using System.IO;
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 batchToken = "TOKEN_DO_BATCH";
        var response = await client.GetAsync(
            $"https://sandbox.boletocloud.com/api/v1/batch/boletos/{batchToken}");

        if (response.IsSuccessStatusCode) {
            var bytes = await response.Content.ReadAsByteArrayAsync();
            await File.WriteAllBytesAsync("boletos-batch.pdf", bytes);
            Console.WriteLine("PDF do batch salvo com sucesso!");
        } else {
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
        }
    }
}

Node

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

const batchToken = 'TOKEN_DO_BATCH';

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: `/api/v1/batch/boletos/${batchToken}`,
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token'
};

const req = https.request(options, (res) => {
  if (res.statusCode === 200) {
    const file = fs.createWriteStream('boletos-batch.pdf');
    res.pipe(file);
    file.on('finish', () => {
      console.log('PDF do batch salvo com sucesso!');
    });
  } else {
    console.log(`Erro: ${res.statusCode}`);
  }
});

req.end();

Go

package main

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

func main() {
    batchToken := "TOKEN_DO_BATCH"
    req, _ := http.NewRequest("GET",
        "https://sandbox.boletocloud.com/api/v1/batch/boletos/"+batchToken, nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")

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

    if resp.StatusCode == 200 {
        file, _ := os.Create("boletos-batch.pdf")
        defer file.Close()
        io.Copy(file, resp.Body)
        fmt.Println("PDF do batch salvo com sucesso!")
    } else {
        fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

PHP

<?php
$batch_token = 'TOKEN_DO_BATCH';
$host = 'https://sandbox.boletocloud.com';
$api_key = 'api-key_SUA-API-KEY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $host . '/api/v1/batch/boletos/' . $batch_token);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    file_put_contents("boletos-batch.pdf", $response);
    echo "PDF do batch salvo com sucesso!\n";
} else {
    echo "Erro: $http_code\n";
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

batch_token = 'TOKEN_DO_BATCH'

response = requests.get(
    f'https://sandbox.boletocloud.com/api/v1/batch/boletos/{batch_token}',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token')
)

if response.status_code == 200:
    with open('boletos-batch.pdf', 'wb') as f:
        f.write(response.content)
    print('PDF do batch salvo com sucesso!')
else:
    print(f'Erro: {response.status_code}')

Ruby

require 'net/http'
require 'uri'

batch_token = 'TOKEN_DO_BATCH'
uri = URI("https://sandbox.boletocloud.com/api/v1/batch/boletos/#{batch_token}")

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Get.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')

  response = http.request(request)
  if response.code == '200'
    File.write('boletos-batch.pdf', response.body)
    puts 'PDF do batch salvo com sucesso!'
  else
    puts "Erro: #{response.code}"
  end
end

Clojure

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

(let [batch-token "TOKEN_DO_BATCH"
      response (client/get
                (str "https://sandbox.boletocloud.com/api/v1/batch/boletos/" batch-token)
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :as :byte-array
                 :throw-exceptions false})]
  (if (= 200 (:status response))
    (do
      (clojure.java.io/copy (:body response)
                            (clojure.java.io/file "boletos-batch.pdf"))
      (println "PDF do batch salvo com sucesso!"))
    (println "Erro:" (:status response))))

Tokens e Operações Individuais

Os tokens individuais retornados para cada boleto permitem operações específicas:

Operação	Endpoint	Descrição
Segunda via	GET /boletos/{token}	PDF de um boleto específico
Status do registro	GET /boletos/{token}/registro	Verificar se foi registrado
Baixa	PUT /boletos/{token}/baixa	Cancelar boleto específico

Numeração Única

Cada boleto no lote deve ter um sequencial ou numero único para evitar conflitos de numeração bancária.

Idempotência

Para evitar boletos duplicados em cenários de retry, use o campo tokenControleUsuario com um valor único para cada boleto. Veja mais em Idempotência.

---

Veja Também

Buscar PDF do Lote Segunda etapa: obter o PDF consolidado

Criar Carnê Alternativa com 3 boletos por página

Campos do Boleto Referência completa de todos os campos

Idempotência Evite boletos duplicados