FAQ - Perguntas Frequentes

Respostas às dúvidas mais comuns sobre integração, API e operação da Boleto Cloud.

Primeiros Passos

O que é a Boleto Cloud?

A Boleto Cloud é uma plataforma para emitir e gerenciar boletos bancários com integração via API REST, focada em reduzir burocracia bancária e centralizar sua operação de cobrança em um único lugar.

A Boleto Cloud retém o dinheiro dos meus clientes?

Não. A Boleto Cloud não faz intermediação de pagamentos. Todo o valor pago pelo seu cliente é creditado integralmente e diretamente na sua conta bancária configurada. A plataforma atua como facilitadora tecnológica (Gateway), mas o fluxo financeiro ocorre diretamente entre o pagador e o seu banco.

O que preciso para começar a emitir boletos?

Você precisa de dois requisitos básicos:

Uma conta na Boleto Cloud (Grátis ou Personalizada)
Uma conta corrente bancária (PF ou PJ) com Carteira de Cobrança contratada junto ao seu gerente

Quais bancos são aceitos pela plataforma?

Suportamos emissão via arquivos CNAB 240/400 para os principais bancos: Banco do Brasil, Bradesco, Itaú, Santander, Caixa, e cooperativas como Sicoob, Sicredi, Ailos, Cresol, entre outros.

Para bancos como Inter, Santander, BB, Itaú e Sicoob, também oferecemos suporte a registro online via API/Webservice.

Integração via API

Existe API da Boleto Cloud?

Sim. A plataforma oferece API REST para integrar emissão, consulta e gestão de boletos, além de endpoints para processamento de arquivos CNAB (remessas/retornos).

Preciso pagar para usar a API?

Não necessariamente. O plano Grátis já dá acesso completo à API.

Existe ambiente de testes (Sandbox)?

Sim. Há um endpoint de Sandbox em https://sandbox.boletocloud.com/api para desenvolvimento.

O Sandbox suporta registro online (API/Webservice bancário)?

Não. A integração online via API/Webservices bancários e VAN não está disponível no Sandbox. Essas integrações só funcionam no ambiente de Produção com o plano personalizado.

No Sandbox, você pode:

Gerar boletos e validar o fluxo completo da sua aplicação
Exportar arquivos CNAB de remessa manualmente para validar no sistema do banco, se necessário
Testar toda a lógica de integração antes de ir para produção

Os dados do Sandbox e Produção são compartilhados?

Não. Os ambientes Sandbox e Produção são completamente independentes:

Os cadastros de um ambiente não existem no outro
Tokens de conta do Sandbox não funcionam em Produção (e vice-versa)
API Keys são diferentes para cada ambiente

Impacto prático: Se você configurou uma conta bancária no Sandbox, após validar os testes, precisará replicar manualmente a configuração no ambiente de Produção.

Como gerar meu token (API Key)?

Crie uma conta no ambiente desejado (Sandbox ou Produção)
Acesse a área do usuário
Gere seu token de API na seção de configurações

Como autenticar na API?

A autenticação é feita via HTTP Basic Auth:

Usuário: sua API Key (ex: api-key_123)
Senha: use a palavra token

Veja mais detalhes na seção de Autenticação.

Como emitir um boleto via API?

Você envia um POST para /api/v1/boletos com os dados necessários. Em caso de sucesso, a API retorna o token do boleto e a localização do recurso para consulta/download.

Veja mais detalhes na seção Criar Boletos.

Como obter o PDF de um boleto pela API?

Você faz um GET no recurso do boleto (pelo token) e recebe o PDF (content-type: application/pdf).

Veja mais detalhes na seção Obter PDF.

Existe link de 2ª via que posso usar no meu sistema?

Sim. Existe um padrão de URL de 2ª via onde você substitui o token do boleto para disponibilizar a segunda via atualizada aos seus clientes.

A API suporta webhooks ou notificações de pagamento?

Atualmente, a conciliação via API é feita através do endpoint de processamento de Arquivos de Retorno. Você envia o arquivo CNAB via POST e recebe um JSON com os títulos liquidados.

Vocês oferecem SDK pronto (PHP/Node/Java)?

Não há SDK oficial. A documentação disponibiliza exemplos em cURL, Java e PHP que você pode adaptar para seu stack preferido.

Arquivos CNAB (Remessa e Retorno)

O que é Arquivo de Remessa?

É o arquivo enviado ao banco para registrar os boletos. Sem ele, o banco não sabe que o boleto existe e o pagamento pode ser recusado.

O que é Arquivo de Retorno?

É o arquivo que o banco disponibiliza com ocorrências (pagamento, baixa, rejeições). Você importa na Boleto Cloud para dar baixa automática e conciliar o financeiro.

Como gerar arquivo de remessa via API?

Você chama o endpoint /api/v1/arquivos/cnab/remessas informando o token da conta bancária. Em sucesso, a resposta entrega o arquivo CNAB.

Veja mais detalhes na seção CNAB Remessa.

Como processar arquivo de retorno via API?

Você envia o arquivo retorno para o endpoint /api/v1/arquivos/cnab/retornos (upload multipart/form-data). A API retorna um JSON com o resultado do processamento e ocorrências.

Veja mais detalhes na seção CNAB Retorno.

Por que o banco “não reconhece” meu boleto?

Na maioria dos casos, é porque o boleto não foi registrado no banco. Em fluxos CNAB, isso exige gerar a remessa na Boleto Cloud e importar no sistema do banco.

Paguei o boleto, mas ele não aparece como “pago”. Por quê?

A atualização de status depende da conciliação: você precisa obter o arquivo de retorno no banco e processá-lo para atualizar as ocorrências no sistema.

O registro do boleto é imediato?

Depende do banco e da tecnologia usada:

Via Arquivo (CNAB): Pode levar algumas horas até o dia seguinte para ser processado
Via API/Webservice: Para bancos suportados (BB, Inter, Itaú, Santander, Sicoob), o registro ocorre no mesmo minuto, permitindo pagamento imediato

Configuração e Homologação

O que é a Homologação Bancária?

A homologação é um teste de segurança obrigatório para garantir que o dinheiro cairá na conta certa. Consiste em 5 passos:

Emitir um boleto de teste (valor simbólico, ex: R$ 3,00)
Registrar o boleto (via remessa CNAB ou API)
Pagar o boleto e aguardar compensação
Conciliar (importar arquivo de retorno)
Confirmar os dados no sistema para remover a marca “Em Homologação”

Por que a homologação é obrigatória?

Ela garante que os dados cadastrados estão corretos e que os valores pagos vão cair na conta certa antes de você cobrar clientes reais.

Onde encontro os dados “Carteira”, “Convênio” e “Nosso Número”?

Esses dados são fornecidos exclusivamente pelo gerente da sua conta bancária no momento da contratação da carteira de cobrança. Sem eles, não é possível configurar a emissão de boletos válidos.

O que é “boleto registrado”?

É o boleto cujos dados foram registrados na instituição financeira antes do pagamento. Com a Nova Plataforma de Cobrança, o registro é obrigatório para evitar fraudes e inconsistências.

Quais dados do pagador são obrigatórios?

Em geral, CPF/CNPJ, nome e endereço do pagador são exigidos nas regras do boleto registrado.

Planos e Preços

A Boleto Cloud tem plano grátis?

Sim. O plano Grátis permite começar sem custo de plataforma e inclui: emissão de boletos, link de download, envio por e-mail e integração via API.

Qual a diferença entre Grátis e Personalizado?

Recurso	Grátis	Personalizado
Emissão de boletos	Ilimitado	Ilimitado
Integração via API	Sim	Sim
Remessa/Retorno CNAB	Manual	Automático*
Registro online (API bancária)	-	Sim*
Personalização HTML/CSS	-	Sim
Lembretes automáticos	-	Sim
Boletos recorrentes	-	Sim

*Mediante autorização bancária

Além da plataforma, eu pago tarifas ao banco?

Sim. Como o dinheiro cai direto na sua conta, a relação comercial da tarifa bancária é entre você e o seu banco. A Boleto Cloud cobra pelo uso do software/API, enquanto o banco cobra pelo serviço de cobrança.

Posso emitir boletos ilimitados?

Sim. A plataforma oferece boletos ilimitados em ambos os planos.

Posso ter múltiplas contas bancárias de CNPJs diferentes?

Sim. A Boleto Cloud suporta cenários com múltiplos beneficiários e CNPJs diferentes.

Na prática, funciona assim:

Sua empresa possui uma conta de login (usuário) na plataforma
Dentro dessa conta, você cadastra seus clientes como Beneficiários
Cada Beneficiário pode ter uma ou mais contas bancárias
Cada conta bancária possui seu próprio token para uso via API
Cada conta conta com personalização independente de mensagens, instruções e imagens

Exemplo de uso: Empresas de software (SaaS) que emitem boletos em nome de seus clientes, ou holdings com múltiplas empresas.

Segurança e Boas Práticas

Qual a recomendação principal para evitar problemas em produção?

Desenvolva e teste sempre no Sandbox primeiro. Isso evita inconsistências, bloqueios e problemas por chamadas incorretas em produção.

Posso compartilhar minha API Key?

Não. A API Key é secreta e dá acesso à sua conta/recursos. Se suspeitar de exposição, gere uma nova chave imediatamente.

Os dados do Sandbox ficam para sempre?

Não. O Sandbox pode apagar dados periodicamente. Use apenas para testes, não como armazenamento permanente.

Qual o prazo de compensação de boleto?

Com as novas regras de compensação bancária implementadas desde 2024, o prazo foi significativamente reduzido:

Situação	Prazo de Compensação
Pagamento em dia útil até 13h30	Mesmo dia (D+0)
Pagamento em dia útil após 13h30	Próximo dia útil (D+1)
Pagamento em fins de semana/feriados	Próximo dia útil (D+1 ou D+2)
BolePix (boleto com QR Code Pix)	Instantâneo

Quando o status muda na Boleto Cloud?

A velocidade de atualização do status depende do tipo de integração configurada:

Integração	Atualização do Status
Pix (BolePix)	Segundos (instantâneo)
API/Webservice bancário	Mesmo dia (até D+0 se pago antes das 13h30)
VAN bancária	Mesmo dia ou D+1
Arquivo CNAB (retorno)	Quando você processar o arquivo de retorno

Fatores que influenciam o prazo

Horário do pagamento: Pagar antes das 13h30 pode garantir compensação no mesmo dia
Dia da semana: Fins de semana e feriados adiam para o próximo dia útil
Instituição financeira: Cada banco pode ter particularidades no processamento
Forma de pagamento: Pix é instantâneo; boleto tradicional segue prazos D+0/D+1

Migração e Suporte

Como funciona a migração de outras plataformas?

O caminho mais rápido costuma ser:

Importar/cadastrar pagadores (suporta CSV)
Configurar beneficiário e contas bancárias
Definir fluxo de registro (CNAB vs online) e conciliação
Integrar via API (se aplicável)

Posso importar pagadores em massa?

Sim. Você pode importar pagadores via CSV com campos separados por ponto e vírgula (;).

Vocês oferecem suporte por quais canais?

Há suporte por e-mail e, conforme o plano, suporte por voz. Use também a página de Status para verificar disponibilidade dos serviços.

Tenho um banco/layout específico. Vocês suportam?

Se o banco/layout não estiver disponível na lista padrão, avalie o Plano Personalizado para inclusão conforme necessidade.

Anterior
Registrar Boleto Depois Próximo
Suporte