Emitir Boletos em Lote
A API Boleto Cloud oferece dois endpoints especializados para emissão de múltiplos boletos em uma única requisição: Batch (1 boleto por página) e Carnê (3 boletos por página).
Quando Usar Emissão em Lote
Seção intitulada “Quando Usar Emissão em Lote”| Cenário | Endpoint Recomendado | Layout |
|---|---|---|
| Cobranças diversas — diferentes clientes, valores, vencimentos | Batch | 1 boleto/página |
| Parcelamentos — mesmo cliente, valores iguais ou diferentes | Carnê | 3 boletos/página |
| Mensalidades — mesmo cliente, período fixo | Carnê | 3 boletos/página |
| Emissão em massa — muitos clientes de uma vez | Batch | 1 boleto/página |
Comparação: Batch vs Carnê
Seção intitulada “Comparação: Batch vs Carnê”| Característica | Batch | Carnê |
|---|---|---|
| Layout do PDF | 1 boleto por página | 3 boletos por página |
| Limite por chamada | Até 300 boletos | Até 300 boletos |
| Uso típico | Cobranças diversas | Parcelamentos |
| Mesmo pagador | Não necessariamente | Geralmente sim |
| Endpoint POST | /batch/boletos |
/carnes |
| Endpoint GET | /batch/boletos/{token} |
/carnes/{token} |
| Plano | Personalizado | Personalizado |
Fluxo de Requisição
Seção intitulada “Fluxo de Requisição”Ambos os endpoints seguem o mesmo fluxo de duas etapas:
┌─────────────────────────────────────────────────────────────────────────────────┐│ ETAPA 1: CRIAR BOLETOS ││ ││ POST /batch/boletos ou POST /carnes ││ ► Envia array JSON com até 300 boletos ││ ► Recebe JSON com tokens (batch + individuais) ││ │└────────────────────────────────────┬────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────────────────────┐│ ETAPA 2: OBTER PDF ││ ││ GET /batch/boletos/{token} ou GET /carnes/{token} ││ ► Usa o token retornado na etapa 1 ││ ► Recebe PDF consolidado (1 ou 3 boletos por página) ││ │└─────────────────────────────────────────────────────────────────────────────────┘Limites e Validações
Seção intitulada “Limites e Validações”| Aspecto | Limite |
|---|---|
| Boletos por requisição | Máximo 300 |
| Tamanho do payload | Sem limite específico (recomendado < 10MB) |
| Timeout recomendado | 60 segundos para 300 boletos |
| Campos obrigatórios | Mesmos do boleto individual |
Onde se Encaixa no Ciclo de Vida
Seção intitulada “Onde se Encaixa no Ciclo de Vida”┌─────────────────────────────────────────────────────────────────────────────┐│ CRIAÇÃO DOS BOLETOS ││ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ POST /boletos │ │ POST /batch/ │ │ POST /carnes │ ││ │ (individual) │ │ boletos (lote) │ │ (parcelamento) │ ││ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ ││ │ │ │ ││ └─────────────────────┼─────────────────────┘ ││ ▼ │└──────────────────────────────[ CRIADO ]─────────────────────────────────────┘ │ (envio automático ou via CNAB) ▼┌────────────────────────[ REGISTRO PENDENTE ]────────────────────────────────┐│ ││ Próximos passos: ││ • Obter PDF: GET /batch/boletos/{token} ou GET /carnes/{token} ││ • Consultar status individual: GET /boletos/{token-individual}/registro ││ • Baixar boleto individual: PUT /boletos/{token-individual}/baixa ││ │└─────────────────────────────────────────────────────────────────────────────┘Endpoints Disponíveis
Seção intitulada “Endpoints Disponíveis”Batch (1 boleto por página)
Seção intitulada “Batch (1 boleto por página)”Criar Batch (POST)Criar múltiplos boletos com layout 1 por página
Obter PDF do Batch (GET)Baixar o PDF consolidado do batch
Carnê (3 boletos por página)
Seção intitulada “Carnê (3 boletos por página)”Criar Carnê (POST)Criar parcelamento com layout 3 por página
Obter PDF do Carnê (GET)Baixar o PDF consolidado do carnê
Veja Também
Seção intitulada “Veja Também”Boleto IndividualCriar um único boleto com PDF na resposta
Campos do BoletoReferência completa de todos os campos
IdempotênciaEvitar boletos duplicados
CNAB RemessaEnviar boletos para registro no banco