Campos do Lote/Carnê

Atenção

Enquanto sua aplicação estiver em desenvolvimento, use 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. Quando os testes terminarem, siga o roteiro Do Sandbox para a Produção.

Novo Esta página documenta o que muda ao criar boletos em lote (batch) ou carnê. Os campos de cada boleto são exatamente os do boleto individual — a referência canônica segue sendo Campos do Boleto; aqui ficam apenas os deltas do envelope e do comportamento em lote.

Formato da Requisição

	Individual	Lote/Carnê
Content-Type	application/x-www-form-urlencoded ou application/json	application/json apenas
Estrutura	Campos boleto.*	Envelope batch com array boletos[]

No JSON, campos de múltiplas linhas como instrucao e info são arrays de strings — isso vale para qualquer requisição JSON (inclusive a individual), não é uma particularidade do lote; no formato de formulário, a chave é repetida. Limites: instrucao até 8 linhas de 100 caracteres; info até 2 linhas de 100 caracteres.

Campos do Envelope batch

Campo	Tipo	Obrigatório	Descrição
batch.tokenControleUsuario	string	Não — recomendado em toda integração nova	Token de controle do lote inteiro: bloqueia reenvio duplicado (409) e permite recuperar a criação após timeout. Até 44 caracteres (A-Z a-z 0-9 - _ =), único por conta, case-insensitive
batch.boletos[]	array	Sim	Os boletos do lote — até 300 por requisição. Cada item aceita os campos do boleto individual, inclusive o tokenControleUsuario por boleto

Dois níveis de token de controle

batch.tokenControleUsuario (lote) e boletos[].tokenControleUsuario (boleto) são níveis diferentes do mesmo conceito — veja Idempotência no Lote/Carnê para namespaces, precedência e recuperação.

Comportamentos por Boleto no Lote

• Numeração: use valores distintos de sequencial/numero entre os boletos do lote — a plataforma rejeita nosso número repetido no contexto da conta bancária. Regras completas em Numeração.
• documento: identifique cada boleto/parcela (ex.: PARC-001, PARC-002).
• pagador: por boleto — no batch pode variar (clientes diversos); no carnê tipicamente repete (parcelas do mesmo pagador).

O que muda na Resposta 201

Campo	Descrição
batch.token	Token do lote — PDF e situação agregada
batch.tokenControleUsuario	Echo do token de controle do lote (null quando não usado)
batch.total	Quantidade de boletos criados — sempre igual ao tamanho de batch.boletos[] e de batch.titulos[]
batch.boletos[]	Lista com o token (string) de cada boleto criado — boletos[i] corresponde a titulos[i].token
batch.titulos[]	Resumo de cada boleto criado: token, numero, documento, codigoDeBarras, linhaDigitavel, pixCodigoEMV, tokenControleUsuario (o do boleto)

Exemplos completos de requisição e resposta nas páginas de criação de cada família.

Veja Também

Campos do BoletoA referência canônica de todos os campos por boleto

Idempotência no Lote/CarnêOs dois níveis de token de controle

Criar Batch (POST)Requisição completa com os dois níveis

Criar Carnê (POST)Requisição completa com os dois níveis