Referência de Campos do Boleto

Campos da Requisição

Esta página documenta todos os campos disponíveis para criação de boletos na API Boleto Cloud. Os campos, tipos, tamanhos e validações descritos aqui se aplicam aos seguintes endpoints:

Criar Boleto (POST /boletos) Emissão de boleto individual com retorno do PDF

Criar em Lote (POST /boletos/lote) Emissão de múltiplos boletos em uma única requisição

Criar Carnê (POST /carnes) Emissão de carnês com múltiplas parcelas

Formatos Suportados

A API aceita requisições em dois formatos. Os nomes dos campos, tipos, tamanhos e validações são idênticos em ambos:

Content-Type	Formato	Exemplo
application/x-www-form-urlencoded	Chave=valor	boleto.valor=1250.43&boleto.documento=PED-123
application/json	Objeto JSON	{"boleto": {"valor": 1250.43, "documento": "PED-123"}}

Notação dos campos

Os campos são documentados na notação com ponto (ex: boleto.pagador.nome). No formato JSON, isso corresponde a objetos aninhados: {"boleto": {"pagador": {"nome": "..."}}}.

---

Dados do Documento (Boleto)

Campo	Tipo	Obrigatório	Tamanho/Limite	Exemplo	Descrição
boleto.conta.token	string	Sim	Token válido	"api-key_Omeu..."	Token da conta bancária. Saiba mais →
boleto.tokenControleUsuario	string	Não	Alfanumérico	"pedido-12345-abc"	Token para evitar boletos duplicados. Saiba mais →
boleto.numero	string	Não	Máx. 20 caracteres	"123456789-0"	NIB pré-formatado conforme requisitos do banco. Saiba mais →
boleto.sequencial	integer	Não	Número inteiro	12345	Número sequencial para gerar o NIB automaticamente. Saiba mais →
boleto.titulo	string	Sim	Códigos válidos	"DM"	Tipo de título/documento
boleto.documento	string	Sim	Máx. 20 caracteres	"DOC-XPTO-1/A"	Número do documento
boleto.aceite	boolean	Não	true ou false	false	Indica se o boleto foi aceito
boleto.emissao	date	Sim	AAAA-MM-DD (passado ou presente)	"2024-01-15"	Data de emissão
boleto.vencimento	date	Sim	AAAA-MM-DD (passado, presente ou futuro)	"2024-02-15"	Data de vencimento
boleto.valor	decimal	Sim	0.00 a 99.999.999,99	50207.93	Valor do boleto (8 inteiros + 2 decimais)
boleto.juros	decimal	Não	0.0000 a 100.0000	3.33	Taxa de juros ao mês (3 inteiros + 4 decimais)
boleto.multa	decimal	Não	0.00 a 100.00	2.10	Percentual de multa (3 inteiros + 2 decimais)
boleto.instrucao	string	Não	Máx. 8 linhas de 100 caracteres	"Não receber após vencimento"	Instruções para o caixa
boleto.info	string	Não	Máx. 2 linhas de 100 caracteres	"Referente ao pedido #12345"	Informações ao pagador
boleto.desconto	decimal	Não	0.00 a 100.00	5.00	Percentual de desconto até o vencimento

Campos de data

• emissao: Deve ser uma data no passado ou presente (não aceita datas futuras)
• vencimento: Aceita datas no passado, presente ou futuro
• Ambos devem estar no formato AAAA-MM-DD. Saiba mais sobre formatos →

Tipos de Documento Aceitos

Código	Descrição
AP	Apólice de Seguro
BDP	Boleto de Proposta
CC	Cartão de Crédito
CH	Cheque
CPR	Cédula de Produto Rural
DAE	Dívida Ativa de Estado
DAM	Dívida Ativa de Município
DAU	Dívida Ativa da União
DD	Documento de Dívida
DM	Duplicata Mercantil
DMI	Duplicata Mercantil para Indicação
DR	Duplicata Rural
DS	Duplicata de Serviço
DSI	Duplicata de Serviço para Indicação
EC	Encargos Condominiais
FAT	Fatura
LC	Letra de Câmbio
ME	Mensalidade Escolar
NCC	Nota de Crédito Comercial
NCE	Nota de Crédito à Exportação
NCI	Nota de Crédito Industrial
NCR	Nota de Crédito Rural
ND	Nota de Débito
NF	Nota Fiscal
NP	Nota Promissória
NPR	Nota Promissória Rural
NS	Nota de Seguro
O	Outros
PC	Parcela de Consórcio
RC	Recibo
TM	Triplicata Mercantil
TS	Triplicata de Serviço
W	Warrant

Dados do Pagador

O pagador é a pessoa física ou jurídica responsável pelo pagamento do boleto.

Campo	Tipo	Obrigatório	Tamanho	Exemplo
boleto.pagador.nome	string	Sim	6-150 caracteres	"Alberto Santos Dumont"
boleto.pagador.cprf	string	Sim	CPF ou CNPJ válido	"111.111.111-11"
boleto.pagador.email	string	Não	Máx. 1000 caracteres	"pagador@email.com"
boleto.pagador.endereco.cep	string	Sim	Formato XXXXX-XXX	"36240-000"
boleto.pagador.endereco.uf	string	Sim	2 caracteres (sigla)	"MG"
boleto.pagador.endereco.localidade	string	Sim	3-150 caracteres	"Santos Dumont"
boleto.pagador.endereco.bairro	string	Sim	1-100 caracteres	"Casa Natal"
boleto.pagador.endereco.logradouro	string	Sim	3-150 caracteres	"BR-499"
boleto.pagador.endereco.numero	string	Sim	Máx. 15 caracteres	"s/n"
boleto.pagador.endereco.complemento	string	Não	Máx. 150 caracteres	"Km 211"

Envio de Boleto por E-mail

O campo boleto.pagador.email permite o envio automático do boleto por e-mail no momento da emissão.

Múltiplos destinatários

Você pode informar múltiplos e-mails separados por ponto e vírgula (;):

boleto.pagador.email=financeiro@empresa.com;cobranca@empresa.com

Recurso do Plano Personalizado

O envio automático de boletos por e-mail está disponível para assinantes do plano personalizado (pago). O boleto é enviado imediatamente após a emissão via API.

Preparando para o futuro

No plano grátis, o campo boleto.pagador.email fica vinculado ao cadastro do pagador. Caso você migre para o plano personalizado posteriormente, o e-mail já estará associado e não será necessário reimportar este dado — o envio automático funcionará imediatamente.

Dados do Sacador/Avalista

O Sacador/Avalista é uma terceira parte que pode ser incluída no boleto, geralmente utilizado em operações de desconto de duplicatas ou quando há um terceiro garantidor da dívida.

Campo	Tipo	Obrigatório	Tamanho	Exemplo
boleto.sacador.nome	string	Sim	6-150 caracteres	"Empresa Sacadora Ltda"
boleto.sacador.cprf	string	Sim	CPF ou CNPJ válido	"12.345.678/0001-90"
boleto.sacador.endereco.cep	string	Sim	Formato XXXXX-XXX	"01310-100"
boleto.sacador.endereco.uf	string	Sim	2 caracteres (sigla)	"SP"
boleto.sacador.endereco.localidade	string	Sim	3-150 caracteres	"São Paulo"
boleto.sacador.endereco.bairro	string	Sim	1-100 caracteres	"Bela Vista"
boleto.sacador.endereco.logradouro	string	Sim	3-150 caracteres	"Av. Paulista"
boleto.sacador.endereco.numero	string	Sim	Máx. 15 caracteres	"1000"
boleto.sacador.endereco.complemento	string	Não	Máx. 150 caracteres	"10º andar, sala 1001"

Quando usar o Sacador/Avalista?

• Desconto de duplicatas: Quando a empresa cede o título a uma instituição financeira
• Operações de factoring: Para identificar o cedente original
• Garantia de terceiros: Quando há um avalista garantindo o pagamento

Campos opcionais

Todos os campos do Sacador/Avalista são condicionalmente obrigatórios: se você informar o boleto.sacador.nome, todos os demais campos (exceto complemento) passam a ser obrigatórios.

---

Dados do Pix (Importação)

Os campos boleto.pix.* permitem importar boletos já registrados em outros sistemas que possuem Pix vinculado. Assim como o campo boleto.numero, esses campos são utilizados para informar dados de boletos gerados externamente.

Campo	Tipo	Obrigatório	Tamanho	Exemplo
boleto.pix.txid	string	Não	Exatamente 35 caracteres	"20220725237092656003585100000118803"
boleto.pix.url	string	Não	67-77 caracteres	"qrcodepix.bb.com.br/pix/v2/cobv/09e1e779-f64b-4b2c-989c-9eab7ead3c10"

Especificações dos Campos

boleto.pix.txid

O txid (Transaction ID) é o identificador único da transação Pix no padrão EMV (campo 62-05).

Atributo	Valor
Tamanho	Exatamente 35 caracteres
Caracteres permitidos	Letras (a-z, A-Z), dígitos (0-9) e caracteres especiais: $ % * + - . /

boleto.pix.url

A URL é o endereço do QR Code Pix gerado pelo banco (payload location).

Atributo	Valor
Tamanho	67 a 77 caracteres
Domínios aceitos	qrcodepix.bb.com.br/pix/v2/cobv/ (Banco do Brasil) ou qrpix.bradesco.com.br/qr/v2/cobv/ (Bradesco)

Uso exclusivo para importação

Esses campos são destinados apenas para importação de boletos já registrados em outros sistemas. Para criar boletos com Pix integrado diretamente na plataforma Boleto Cloud, consulte o guia Boleto com Pix.

Campos condicionalmente obrigatórios

Se você informar boleto.pix.txid, o campo boleto.pix.url também deve ser informado, e vice-versa.

---

Dados da Nota Fiscal Eletrônica (NF-e)

Os campos boleto.nfe.* permitem vincular dados de uma Nota Fiscal Eletrônica ao boleto. Este recurso é utilizado principalmente para:

• Antecipação de recebíveis: Enviar dados da NF-e junto ao registro do boleto para operações de desconto de duplicatas
• Rastreabilidade fiscal: Vincular a cobrança financeira à operação fiscal de forma automática, segura e transparente
• Importação: Importar boletos de outros sistemas mantendo o vínculo com a nota fiscal

Campo	Tipo	Obrigatório	Tamanho/Formato	Exemplo
boleto.nfe.numero	string	Não	1-9 caracteres	"123456789"
boleto.nfe.chaveAcesso	string	Não	Exatamente 44 dígitos	"35240112345678000199550010001234561123456789"
boleto.nfe.emissao	date	Não	Formato AAAA-MM-DD	"2024-01-15"
boleto.nfe.valor	decimal	Não	0.00 a 999.999.999.999,99	1250.00

Especificações dos Campos

boleto.nfe.numero

O número da Nota Fiscal Eletrônica conforme consta no DANFE.

Atributo	Valor
Tamanho	1 a 9 caracteres
Formato	Numérico

boleto.nfe.chaveAcesso

A chave de acesso é o identificador único da NF-e, composto por 44 dígitos numéricos que incluem informações como UF, data de emissão, CNPJ do emitente, modelo, série, número e código verificador.

Atributo	Valor
Tamanho	Exatamente 44 dígitos
Formato	Apenas dígitos (0-9)

boleto.nfe.emissao

A data de emissão da Nota Fiscal Eletrônica.

Atributo	Valor
Formato	AAAA-MM-DD (ano-mês-dia)
Validação	Deve ser uma data no passado ou presente

boleto.nfe.valor

O valor total da Nota Fiscal Eletrônica.

Atributo	Valor
Mínimo	0.00
Máximo	999999999999.99 (até 12 dígitos inteiros)
Casas decimais	2

Antecipação de Recebíveis

Ao informar os dados da NF-e no momento da criação do boleto, essas informações são enviadas ao banco durante o registro. Isso facilita operações de desconto de duplicatas e antecipação de recebíveis, pois o banco já recebe a documentação fiscal vinculada à cobrança.

---

Controle de Registro

Campo	Tipo	Obrigatório	Exemplo	Descrição
boleto.cobrancaBancaria.registrar	boolean	Não	false	Controla se o boleto deve ser registrado no banco. Saiba mais →

Comportamento

• true (padrão): O boleto será incluído na próxima remessa CNAB ou enviado automaticamente ao banco
• false: O boleto é criado mas não é registrado até que o campo seja alterado via API

Casos de Uso

Use boleto.cobrancaBancaria.registrar=false para criar boletos proposta, orçamentos ou em situações onde você deseja controlar o momento exato do registro no banco.

---

Descontos

A API oferece duas formas de configurar descontos: simplificada (apenas percentual) e detalhada (percentual ou valor fixo, com prazo de validade e múltiplos descontos).

Forma Simplificada

Use o campo boleto.desconto para aplicar um desconto percentual válido até a data de vencimento.

Campo	Tipo	Exemplo	Descrição
boleto.desconto	decimal	5.00	Percentual de desconto até o vencimento

Forma Detalhada

Para maior controle, utilize os campos boleto.descontoDetalhe.*:

Campo	Tipo	Exemplo	Descrição
boleto.descontoDetalhe.percentual	decimal	5.00	Desconto em percentual
boleto.descontoDetalhe.valor	decimal	25.50	Desconto em valor fixo (R$)
boleto.descontoDetalhe.dias	integer	5	Dias antes do vencimento em que o desconto é válido

Nota

• Use percentual ou valor, nunca ambos simultaneamente
• Se dias não for informado (ou for zero), o desconto vale até a data de vencimento

Múltiplos Descontos

Alguns bancos permitem configurar até 3 faixas de desconto escalonadas. Utilize:

Desconto	Campos
1º Desconto	boleto.descontoDetalhe.percentual / boleto.descontoDetalhe.valor / boleto.descontoDetalhe.dias
2º Desconto	boleto.descontoDetalhe2.percentual / boleto.descontoDetalhe2.valor / boleto.descontoDetalhe2.dias
3º Desconto	boleto.descontoDetalhe3.percentual / boleto.descontoDetalhe3.valor / boleto.descontoDetalhe3.dias

Exemplo de descontos escalonados:

boleto.descontoDetalhe.percentual=10.00
boleto.descontoDetalhe.dias=10

boleto.descontoDetalhe2.percentual=5.00
boleto.descontoDetalhe2.dias=5

boleto.descontoDetalhe3.percentual=2.00
boleto.descontoDetalhe3.dias=0

Neste exemplo:

• 10% de desconto se pago até 10 dias antes do vencimento
• 5% de desconto se pago até 5 dias antes do vencimento
• 2% de desconto se pago até a data de vencimento

Restrição Bancária

Quando utilizar múltiplos descontos, todos devem ser do mesmo tipo: ou todos em percentual, ou todos em valor fixo. Não é permitido misturar tipos de desconto na mesma cobrança.

---

Informações ao Pagador

O campo boleto.info permite incluir informações adicionais no recibo do pagador, exibidas na área “Informações ao Pagador” do boleto PDF.

Especificação

Atributo	Valor
Campo	boleto.info
Tipo	string
Linhas máximas	2
Caracteres por linha	100
Obrigatório	Não

Uso

Envie o campo múltiplas vezes para adicionar mais de uma linha:

boleto.valor=1250.00
boleto.info=Referente ao contrato #CT-2024-0042
boleto.info=Vencimento original: 15/01/2024 - Parcela 3/12
boleto.documento=CT-2024-0042-P3

Diferença entre instrucao e info

Campo	Destinatário	Localização no Boleto	Finalidade
boleto.instrucao	Caixa/Banco	Instruções de cobrança	Orientações para o processamento do pagamento (ex: “Não receber após 30 dias”)
boleto.info	Pagador	Informações ao Pagador	Detalhes sobre a cobrança para o cliente (ex: “Referente ao pedido #123”)

Boas práticas

Use boleto.info para:

• Identificar o pedido, contrato ou serviço relacionado
• Informar detalhes de parcelamento
• Incluir referências que ajudem o pagador a identificar a cobrança