Pular para o conteúdo
API Boleto Cloud

Planos & API

A API V1 está disponível nos planos Grátis e Personalizado. Veja o que cada plano cobre no fluxo de boletos, compare as rotas e confira o comportamento no sandbox.

O mesmo núcleo, mais recursosA moldura verde do Personalizado contém a base do Grátis e os recursos adicionais lado a lado. No alto, a pílula do Personalizado acompanha a frase O mesmo núcleo, com mais possibilidades na API. À esquerda, a caixa cinza-azulada do Grátis mostra o boleto em PDF e os arquivos de remessa e retorno. À direita, da esquerda para a direita e de cima para baixo: boleto com imagem genérica no corpo, três boletos empilhados para o carnê, linhas X- para headers adicionais, pílulas GET, PUT e POST para mais endpoints, banco com setas de sincronização para a troca automática conforme o canal disponível, e envelope saindo para o e-mail ao pagador quando seu e-mail é informado. Os métodos e headers são símbolos dos recursos ampliados, sem rotas, nomes completos ou valores reais.Plano: PersonalizadoO mesmo núcleo, com mais possibilidades na API.Plano: GrátisPDFRemessaRetornoSeu modeloCarnêX-X-X-HeadersGETPUTPOSTEndpointsAutomaçãoE-mail

Plano Grátis

Seção intitulada “Plano Grátis”

O plano Grátis cobre boa parte do fluxo de boletos pela API: criar o boleto e obter o PDF, gerar a remessa para registrar os boletos no banco e conciliar os pagamentos enviando o arquivo de retorno para a API. Nesse fluxo, levar a remessa ao banco e trazer o retorno do banco são etapas manuais suas.

  • Emissão e PDF: POST /boletos cria o boleto e devolve o PDF; GET /boletos/{token} recupera o PDF original.
  • Registro no banco: POST /arquivos/cnab/remessas gera o arquivo de remessa CNAB. O envio desse arquivo ao banco fica a cargo de você.
  • Conciliação: POST /arquivos/cnab/retornos processa o arquivo de retorno do banco e devolve em JSON ocorrências como liquidação, baixa e registro confirmado.
  • O que o Grátis não traz: o PDF usa o modelo padrão; a emissão pela API não envia e-mail ao pagador; as respostas não trazem os headers de código de barras, linha digitável e Pix copia e cola. Os detalhes estão em O que muda na resposta no plano Grátis.

As demais rotas da API são do plano Personalizado (veja Rotas).

Plano Personalizado

Seção intitulada “Plano Personalizado”

O plano Personalizado inclui tudo o que o Grátis oferece e elimina as etapas manuais com o banco: o registro e o retorno passam a ser trocados automaticamente. Ele também amplia a gestão dos boletos pela API e traz personalização e comunicação com o pagador.

Seu fluxo de boletos, antes e depoisO mesmo fluxo de boletos aparece em duas versões. No Grátis, a API cria o boleto, fornece o PDF e gera a remessa CNAB. O cliente leva a remessa ao banco para registrar os boletos, baixa o retorno no banco e o envia à API, que devolve as ocorrências em JSON para a conciliação. No Personalizado, essas duas ações manuais aparecem riscadas e substituídas pela troca automática com o banco. O primeiro cartão destaca boleto e e-mail personalizados, avisos automáticos por e-mail e PDF anexado ao e-mail enviado pelo painel. O segundo cartão destaca situação do boleto e do registro, alteração de vencimento e valor, baixa, abatimento, lotes e carnês pela API. A automação com o banco depende do canal disponível para o seu banco.Seu fluxo de boletos, antes e depoisDo envio manual à troca automática com o banco.Plano: GrátisBásico pela APIVocê faz a troca com o bancoAPIBoleto + PDFGera remessaCNABVOCÊLevar remessaao bancoMANUALBancoRegistroVOCÊBaixar retornoe enviar à APIMANUALAPIConciliaçãoOcorrênciasem JSONPlano: PersonalizadoTroca automática com o bancoAPIBoleto + PDFEmissão pelaAPILevar remessaao bancoAutomáticoBancoRegistroBaixar retornoe enviar à APIAutomáticoAPIConciliaçãoOcorrênciasem JSONTAMBÉM NO PERSONALIZADOBoleto e e-mailpersonalizadosAvisos automáticos por e-mailPDF anexado no painelGestão e acompanhamentoSituação do boleto e do registroAlterar vencimento e valorBaixar • Abatimento • Lote e carnêA automação com o banco depende do canal disponível para o seu banco.

Gestão do boleto

Seção intitulada “Gestão do boleto”

Altere vencimento, valor e registro pela API. Você também pode baixar o boleto e conceder abatimento.

Gestão do boleto pela APINo Personalizado, da esquerda para a direita: alterar o vencimento e o valor do boleto, alterar seu registro, baixar o boleto, representado por um círculo com X, e conceder abatimento, representado por um círculo com sinal de menos. As duas ações têm o mesmo destaque.Plano: PersonalizadoGestão do boleto pela APIAlterarVencimento e valorAlterar registroPela APIBaixaAbatimento

Acompanhamento

Seção intitulada “Acompanhamento”

Consulte a situação pelo token do boleto ou pelo seu token de controle. Obtenha também o status do registro e o PDF atualizado pela API.

Situação e documentos atualizadosNo Personalizado, da esquerda para a direita: consultar a situação do boleto, obter o status do registro e obter o PDF atualizado pela API.Plano: PersonalizadoSituação e documentos atualizadosSituação do boletoConsulta pela APIStatus do registroConsulta pela APIPDF atualizadoObtenção pela API

Carnês

Seção intitulada “Carnês”

Crie carnês para parcelamentos e mensalidades e obtenha o PDF consolidado com 3 boletos por página. Consulte a situação agregada pelo token do carnê ou pelo token de controle e recupere a criação pelo token de controle.

Carnê: parcelamentos e mensalidadesNo Personalizado, da esquerda para a direita: criar um carnê para parcelamentos e mensalidades, obter o PDF consolidado com 3 boletos por página e consultar a situação agregada do carnê.Plano: PersonalizadoCarnê: parcelamentos e mensalidadesParcelamentose mensalidadesPDF consolidado3 boletos por páginaSituação agregadaVisão do carnê

Lotes

Seção intitulada “Lotes”

Crie vários boletos em uma chamada e obtenha o PDF consolidado do lote (batch). Consulte a situação agregada pelo token do lote ou pelo token de controle e recupere a criação pelo token de controle.

Lote: vários boletos numa chamadaNo Personalizado, da esquerda para a direita: criar vários boletos em uma chamada, obter o PDF consolidado do lote e consultar a situação agregada do batch.Plano: PersonalizadoLote: vários boletos numa chamadaVários boletosUma chamadaPDF consolidadoUm único PDFSituação agregadaVisão do lote

Remessas e retornos

Seção intitulada “Remessas e retornos”

Liste e obtenha remessas e retornos pela API para consultar o histórico. O retorno do Personalizado inclui todos os títulos e o bloco pagador; gerar remessa e processar retorno por upload estão disponíveis nos dois planos.

Histórico de arquivos para conciliarNo Personalizado, da esquerda para a direita: listar e obter remessas pela API; listar e obter retornos pela API; e receber o retorno completo, com todos os títulos e o bloco pagador. Arquivos neutros representam o CNAB: seta cheia de envio nas remessas e seta tracejada de volta nos retornos. A imagem destaca somente esses recursos exclusivos.Plano: PersonalizadoHistórico de arquivos para conciliarRemessasListar e obterRetornosListar e obterRetorno completoTodos os títulospagador

Mais dados na resposta

Seção intitulada “Mais dados na resposta”

Receba código de barras, linha digitável e Pix copia e cola nos headers das respostas de criação e obtenção do PDF original. Na criação, a resposta também traz o header X-BoletoCloud-Status-Registrado-Banco. Veja O que muda na resposta no plano Grátis.

Mais dados na respostaNo Personalizado, a resposta de criação e obtenção do PDF original traz, nos headers, código de barras, linha digitável e Pix copia e cola. Da esquerda para a direita, três documentos representam esses dados, sem valores reais.Plano: PersonalizadoMais dados na respostaCódigo de barrasLinha digitávelPix copia e colaNos headers de criação e obtenção do PDF original.

Troca automática com o banco

Seção intitulada “Troca automática com o banco”

Registro online (API bancária), VAN, envio automático de remessa e troca automática de arquivos de remessa e retorno, conforme o canal disponível para o seu banco. No Grátis, você leva a remessa ao banco e traz o retorno para enviar à API.

Troca automática com o bancoNo Personalizado, a API Boleto Cloud e o banco trocam informações automaticamente. Da esquerda para a direita, nuvem da API, envio e retorno, e banco. Abaixo, os canais possíveis: registro online por API bancária, VAN, envio automático de remessa e troca automática de remessa e retorno. As possibilidades dependem do canal disponível para o banco.Plano: PersonalizadoTroca automática com o bancoAPI BoletoCloudBancoEnvioRetornoRegistro onlineAPI bancáriaVANEnvio deremessaRemessae retornoConforme o canal disponível para o seu banco.

Esses recursos não funcionam no sandbox.

Campos personalizados

Seção intitulada “Campos personalizados”

Envie dados definidos pela sua integração ao criar o boleto. Campos como “Unidade” e “Contrato” aparecem no modelo personalizado de boleto da conta.

Seus dados no modelo do boletoNo Personalizado, à esquerda, o integrador define dados como Unidade e Contrato e os envia na criação do boleto. À direita, esses dados aparecem no modelo de boleto da conta. Os nomes exibidos são rótulos genéricos, sem nomes de parâmetros ou caminhos de campos.Plano: PersonalizadoSeus dados no modelo do boletoDados da sua integraçãoUnidadeContratoEnviados na criaçãoModelo da contaUnidadeContrato

Modelos personalizados

Seção intitulada “Modelos personalizados”

Personalize o layout do boleto: o PDF pode usar os modelos Fatura e Proposta ou o modelo personalizado da conta. No Grátis, o boleto usa o modelo padrão.

PDF com o modelo da contaNo Personalizado, da esquerda para a direita, o PDF pode usar os modelos Fatura, Proposta ou o modelo personalizado da conta.Plano: PersonalizadoPDF com o modelo da contaFaturaPropostaPersonalizado

E-mails automáticos

Seção intitulada “E-mails automáticos”

A emissão pela API envia e-mail ao pagador quando o e-mail do pagador é informado. Os avisos automáticos ocorrem cinco dias antes do vencimento, no dia do vencimento e em atraso.

O plano também permite personalizar o e-mail e enviá-lo em lote. O PDF anexado ao e-mail é um recurso do envio pelo painel.

Avisos automáticos ao pagadorNo Personalizado, no alto, o e-mail é enviado ao pagador na emissão do boleto pela API quando seu e-mail é informado. Abaixo, da esquerda para a direita, avisos automáticos cinco dias antes do vencimento, no dia do vencimento e em atraso.Plano: PersonalizadoAvisos automáticos ao pagadorNa emissão via APICom e-mail do pagador informado5 dias antesNo vencimentoEm atraso

No painel e no atendimento

Seção intitulada “No painel e no atendimento”
  • Boleto recorrente, carnê e parcelamento e segunda via com escolha do vencimento.
  • Relatórios de boletos e de pagadores em PDF e XLS.
  • Suporte via voz e adição de bancos ainda não suportados.

Quer usar o plano Personalizado?

Seção intitulada “Quer usar o plano Personalizado?”

Fale com a Boleto Cloud sobre a contratação.

Rotas

Seção intitulada “Rotas”

Todas as rotas usam o prefixo /api/v1. Sem o plano Personalizado ativo, as rotas exclusivas desse plano respondem 403 com o código 8D1C5814.

Boletos individuais

Seção intitulada “Boletos individuais”

Sim: incluída no plano · Não: exige o Personalizado. A marca à esquerda indica as rotas exclusivas do Personalizado.

Boletos individuais: disponibilidade por plano
Operação / Método e rotaGrátisPersonalizado
Criar boleto (PDF)
POST /boletos		SimSim
Obter PDF original
GET /boletos/{token}		SimSim
Alterar vencimento
PUT /boletos/{token}/vencimento — exclusiva do plano Personalizado		NãoSim
Obter PDF atualizado
GET /boletos/{token}/atualizado/vencimento/{data} — exclusiva do plano Personalizado		NãoSim
Alterar valor
PUT /boletos/{token}/valor — exclusiva do plano Personalizado		NãoSim
Obter status do registro
GET /boletos/{token}/registro — exclusiva do plano Personalizado		NãoSim
Alterar registro
PUT /boletos/{token}/registro — exclusiva do plano Personalizado		NãoSim
Consultar situação
GET /boletos/{token}/situacao — exclusiva do plano Personalizado		NãoSim
Consultar situação pelo token de controle
GET /boletos/controle/{tokenControleUsuario}/situacao — exclusiva do plano Personalizado		NãoSim
Baixar boleto
PUT /boletos/{token}/baixa — exclusiva do plano Personalizado		NãoSim
Conceder abatimento
PUT /boletos/{token}/abatimento — exclusiva do plano Personalizado		NãoSim

Arquivos CNAB (remessas e retornos)

Seção intitulada “Arquivos CNAB (remessas e retornos)”

Sim: incluída no plano · Não: exige o Personalizado. A marca à esquerda indica as rotas exclusivas do Personalizado.

Arquivos CNAB (remessas e retornos): disponibilidade por plano
Operação / Método e rotaGrátisPersonalizado
Gerar remessa CNAB
POST /arquivos/cnab/remessas		SimSim
Listar remessas
GET /arquivos/cnab/remessas — exclusiva do plano Personalizado		NãoSim
Obter remessa
GET /arquivos/cnab/remessas/{token} — exclusiva do plano Personalizado		NãoSim
Processar retorno CNAB
POST /arquivos/cnab/retornos		SimSim
Listar retornos
GET /arquivos/cnab/retornos — exclusiva do plano Personalizado		NãoSim
Obter retorno
GET /arquivos/cnab/retornos/{token} — exclusiva do plano Personalizado		NãoSim

Lotes e carnês (batch e carnê)

Seção intitulada “Lotes e carnês (batch e carnê)”

Sim: incluída no plano · Não: exige o Personalizado. A marca à esquerda indica as rotas exclusivas do Personalizado.

Lotes e carnês (batch e carnê): disponibilidade por plano
Operação / Método e rotaGrátisPersonalizado
Criar batch
POST /batch/boletos — exclusiva do plano Personalizado		NãoSim
Situação do batch
GET /batch/boletos/{token}/situacao — exclusiva do plano Personalizado		NãoSim
Situação do batch pelo token de controle
GET /batch/boletos/controle/{tokenControleUsuario}/situacao — exclusiva do plano Personalizado		NãoSim
Obter PDF do batch
GET /batch/boletos/{token} — exclusiva do plano Personalizado		NãoSim
Criar carnê
POST /carnes — exclusiva do plano Personalizado		NãoSim
Situação do carnê
GET /carnes/{token}/situacao — exclusiva do plano Personalizado		NãoSim
Situação do carnê pelo token de controle
GET /carnes/controle/{tokenControleUsuario}/situacao — exclusiva do plano Personalizado		NãoSim
Obter PDF do carnê
GET /carnes/{token} — exclusiva do plano Personalizado		NãoSim

O que muda na resposta no plano Grátis

Seção intitulada “O que muda na resposta no plano Grátis”
  • POST /boletos: 201 com o PDF, sem os headers X-BoletoCloud-Codigo-De-Barras, X-BoletoCloud-Linha-Digitavel, X-BoletoCloud-Pix-Codigo-EMV e X-BoletoCloud-Status-Registrado-Banco.
  • GET /boletos/{token}: 200 com o PDF, sem X-BoletoCloud-Codigo-De-Barras, X-BoletoCloud-Linha-Digitavel e X-BoletoCloud-Pix-Codigo-EMV. Nos dois planos vêm X-BoletoCloud-Version, Content-Type, X-BoletoCloud-Token e, quando houver, X-BoletoCloud-NIB-Nosso-Numero.
  • PDF: no plano Grátis, o boleto sai no modelo padrão da plataforma (no sandbox, no modelo de sandbox). Os modelos Fatura e Proposta e o modelo personalizado da conta são do plano Personalizado.
  • E-mail ao pagador na emissão: quando pagador.email é informado, o envio ocorre só no plano Personalizado.
  • POST /arquivos/cnab/retornos: no plano Grátis, os títulos do JSON não trazem o bloco pagador.
  • No plano Grátis, o JSON inclui só os títulos que correspondem a boletos da conta. No plano Personalizado, os demais títulos também entram, com token nulo.
  • POST /arquivos/cnab/remessas: a resposta é a mesma nos dois planos.

Sandbox

Seção intitulada “Sandbox”

Após a contratação, o plano Personalizado também é ativado na conta de sandbox. Antes dessa ativação, as rotas do Personalizado respondem 403 com o código 8D1C5814 no sandbox também.

Registro online, VAN e envio automático de remessa não funcionam no sandbox.

Para testar retornos no sandbox, envie o arquivo em Processar retorno e depois liste ou obtenha o resultado em Listar retornos e Obter retorno (rotas do Personalizado). Em produção, com integração automática (VAN ou API bancária), os retornos chegam sem upload. Ao informar a conta bancária (gerar remessa, listar remessas e listar retornos), ela precisa usar cobrança com registro; caso contrário, a resposta é 400 com o código B14DD6FE.

Veja Também

Seção intitulada “Veja Também”
Criar boletoRota do plano Grátis: emitir o boleto e obter o PDF
Processar retornoRota do plano Grátis: enviar o arquivo de retorno CNAB
Consultar situaçãoRota do plano Personalizado: estado do boleto em JSON
Códigos de erroCatálogo dos códigos de erro da API e o que fazer