Consultar Situação do Boleto

Novo Consulta a situação operacional completa do boleto em JSON: registro, pagamento, baixa, protesto e Pix, além dos dados de conferência da emissão (pagador, multa, juros e descontos). É a visão mais completa da vida do boleto disponível na API.

Situação Resumo

O campo boleto.situacao (topo da resposta) é o resumo:

Situação	Significado
PAGO	Há pagamento informado para o boleto
BAIXADO	O boleto foi baixado/cancelado
EM_ABERTO	Nenhum dos anteriores

Nota

O resumo deriva apenas de pagamento/baixa. Um boleto protestado e não pago segue EM_ABERTO no topo — o detalhe está sempre nos blocos (registro, pagamento, baixa, protesto, pix).

Quando Usar

Cenário	Recomendação
Acompanhar o registro com motivo estruturado (código + origem + data)	Sim
Conciliar pagamento/baixa e exibir a situação ao seu usuário	Sim
Obter o Pix Copia e Cola (codigoEMV) de um boleto já emitido	Sim
Conferir os dados gravados na emissão (pagador, multa, juros, descontos)	Sim
Atender chamados de suporte com a visão completa do boleto	Sim

Endpoints

GET https://sandbox.boletocloud.com/api/v1/boletos/{token}/situacao
GET https://sandbox.boletocloud.com/api/v1/boletos/controle/{tokenControleUsuario}/situacao

• Rota por {token}: use quando você guarda o token retornado pela Boleto Cloud na criação do boleto.
• Rota por {tokenControleUsuario}: use quando você informou boleto.tokenControleUsuario na criação e quer consultar pelo identificador do seu sistema.

As duas rotas exigem a autenticação padrão da API e retornam o mesmo contrato JSON (raiz boleto).

Dica

A rota /controle/ permite consultar sem armazenar o token da Boleto Cloud — basta o identificador que o seu sistema já conhece (ex.: número do pedido). Veja Idempotência para como definir o tokenControleUsuario.

Headers

Header	Valor
Accept	application/json
Authorization	Basic {credenciais}

Parâmetros da URL

Parâmetro	Tipo	Descrição
token	string	Token identificador do boleto, retornado na criação
tokenControleUsuario	string	Valor de boleto.tokenControleUsuario informado na criação (rota /controle/)

Estrutura da Resposta

Cenário do exemplo: boleto registrado online com PIX gerenciado pelo banco solicitado, mas o banco não disponibilizou o QR Code (única combinação em que pix.erro aparece — o erro de PIX só nasce após o registro confirmar).

{
  "boleto": {
    "situacao": "EM_ABERTO",
    "token": "TOKEN_DO_BOLETO",
    "tokenControleUsuario": "pedido-12345",
    "numero": "12345678901",
    "documento": "PED-12345",
    "valor": 800.00,
    "emissao": "2026-07-01",
    "vencimento": "2026-07-30",
    "pagador": {
      "nome": "Lucas Mendes",
      "cprf": "111.111.111-11"
    },
    "multa": {
      "percentual": 2.00,
      "valor": null,
      "diasParaEncargos": 1
    },
    "juros": {
      "percentualAoDia": 0.0333,
      "valorFixoAoDia": null,
      "diasParaEncargos": 1
    },
    "descontos": [
      {
        "percentual": 5.00,
        "valor": null,
        "dias": 10
      }
    ],
    "linhaDigitavel": "23790.50004 00000.000000 00000.000000 1 00000000080000",
    "codigoDeBarras": "23791000000000800005000000000000000000000000",
    "registro": {
      "situacao": "REGISTRO_CONFIRMADO",
      "registrar": true,
      "data": "2026-07-01",
      "erro": null,
      "descricao": null
    },
    "pagamento": null,
    "baixa": null,
    "protesto": null,
    "pix": {
      "situacao": "PIX_NAO_GERADO",
      "erro": {
        "origem": "BANCO",
        "codigo": "CHAVE_PIX_NAO_CADASTRADA",
        "mensagem": "O boleto foi registrado online, mas o banco nao disponibilizou o QR Code PIX porque a conta bancaria nao possui chave PIX cadastrada ou disponivel.",
        "informadoEm": "2026-07-01"
      },
      "txId": null,
      "codigoEMV": null
    }
  }
}

Retrato do momento

A resposta é point-in-time: registro.situacao/erro podem mudar entre duas consultas (ex.: um registro em andamento expira no vencimento) sem que exista um novo evento bancário.

Campos do Topo

Campo	Tipo	Descrição
situacao	string	Resumo: PAGO, BAIXADO ou EM_ABERTO (ver Situação Resumo)
token	string	Token do boleto na Boleto Cloud
tokenControleUsuario	string | null	Identificador do seu sistema, quando informado na criação
numero	string	NIB (nosso número) do boleto
documento	string	Número do documento informado na criação
valor	decimal	Valor do boleto
emissao	date	Data de emissão (AAAA-MM-DD)
vencimento	date	Data de vencimento (AAAA-MM-DD)
linhaDigitavel	string	Linha digitável do boleto
codigoDeBarras	string	Código de barras do boleto

Política de Nulos

Regras transversais da resposta — valem para todos os blocos:

• Blocos opcionais nunca são omitidos: pagamento, baixa, protesto e pix vêm como null quando não se aplicam.
• O bloco registro está sempre presente (no mínimo REGISTRO_NAO_SOLICITADO).
• multa e juros são null quando o boleto não define esses encargos (nunca vêm como {campos: null}).
• descontos é lista sempre presente — vazia ([]) quando não há desconto; itens só para os descontos efetivamente definidos, na ordem 1→2→3.
• pagador pode ser null em boletos antigos com dados de pagador incompletos no snapshot da emissão.
• Em multa, juros e descontos[], os pares percentual/valor (e percentualAoDia/valorFixoAoDia) são mutuamente exclusivos: um preenchido, o outro null.

Dados de Conferência

Os blocos pagador, multa, juros e descontos retornam o que foi gravado na emissão:

Campo	Descrição
pagador.nome	Nome do pagador gravado no boleto emitido
pagador.cprf	CPF ou CNPJ do pagador, formatado (mesmo formato aceito na criação)
multa.percentual	Percentual da multa (2 casas), quando definida em percentual
multa.valor	Valor fixo da multa (2 casas), quando definida em valor
multa.diasParaEncargos	Carência: dias após o vencimento para iniciar a cobrança dos encargos (0 = sem carência)
juros.percentualAoDia	Percentual diário de juros (4 casas) — mesma semântica diária do campo de criação
juros.valorFixoAoDia	Valor fixo de juros por dia (2 casas)
juros.diasParaEncargos	Carência (mesma regra da multa — a carência vale para multa e juros)
descontos[].percentual	Percentual do desconto (2 casas)
descontos[].valor	Valor fixo do desconto (2 casas)
descontos[].dias	Prazo em dias do desconto — espelha boleto.descontoDetalhe.N.dias da criação (0 quando não informado)

Condições de emissão × valores aplicados

boleto.multa/juros/descontos (raiz) são as condições configuradas na emissão — o que foi impresso/registrado. Já boleto.pagamento.multa/juros/desconto, quando presentes, são os valores efetivamente aplicados/informados na liquidação pelo banco. Não são o mesmo conceito e podem divergir.

Bloco registro

registro.situacao responde onde o registro está no pipeline; registro.erro responde qual foi o último impedimento conhecido — e um não implica o outro.

registro.situacao	Significado
REGISTRO_CONFIRMADO	Registrado no banco (estado final positivo; data preenchida)
REGISTRO_PENDENTE	Solicitado, ainda sem evidência de envio ao banco
REGISTRO_EM_PROGRESSO	Enviado ao banco e em janela viva de acompanhamento
REGISTRO_REJEITADO	Terminal: não foi registrado e não há expectativa de conclusão automática
REGISTRO_NAO_SOLICITADO	Boleto sem registro solicitado

Regras de leitura:

• erro pode coexistir com REGISTRO_PENDENTE/REGISTRO_EM_PROGRESSO: é o último impedimento conhecido, não sinal de terminalidade. Um boleto pode estar “em progresso com erro anterior” (retentativa).
• REGISTRO_REJEITADO com erro: null significa registro encerrado por supersessão — o boleto foi pago/baixado antes de o registro concluir; nesse caso descricao explica e o motivo real está em pagamento/baixa. Não é rejeição do banco.
• Nos estados vivos, descricao traz textos fixos: "Registro aguardando envio ao banco." (REGISTRO_PENDENTE) e "Registro enviado ao banco; aguardando processamento." (REGISTRO_EM_PROGRESSO).
• registrar é a intenção operacional legada — novos integradores devem usar situacao + erro.codigo.

registro.erro

Estrutura: { origem, codigo, mensagem, informadoEm }.

• informadoEm (AAAA-MM-DD) é a data em que a plataforma tomou ciência do impedimento — não necessariamente a data do fato no banco.
• origem ∈ CONTA, BANCO, INTEGRACAO_BANCARIA, PLATAFORMA — enum próprio deste bloco (não assuma um enum global de origem).

codigo	origem	Quando ocorre	Ação sugerida
CONTA_SEM_ACESSO_API	CONTA	Conta sem acesso ativo/autorizado à API do banco	Habilitar/configurar a conta no banco
PRODUTO_NAO_CONTRATADO	CONTA	Registro/e-commerce não contratado	Contratar o produto com o banco
CREDENCIAL_BANCARIA_INVALIDA	CONTA	Certificado/token expirado ou inválido	Recadastrar certificado/credencial
NUMERO_JA_REGISTRADO	BANCO	Nosso número/título já cadastrado	Gerar nova numeração
ENDERECO_PAGADOR_INVALIDO	BANCO	CEP/endereço do pagador inválido	Corrigir endereço
VENCIMENTO_INVALIDO	BANCO	Vencimento/prazo inválido	Ajustar vencimento
DADOS_PAGADOR_INVALIDOS	BANCO	CPF/CNPJ/nome do pagador inválido	Corrigir dados do pagador
VALOR_OU_ENCARGOS_INVALIDOS	BANCO	Valor/multa/juros/desconto inválido	Corrigir valor/encargos
REGISTRO_TEMPORARIAMENTE_INDISPONIVEL	INTEGRACAO_BANCARIA	Indisponibilidade transitória	Aguardar retentativa
REGISTRO_NAO_REALIZADO_PELO_BANCO	BANCO	Rejeição bancária não classificada	Ler mensagem / acionar o suporte
REGISTRO_NAO_CONCLUIDO	INTEGRACAO_BANCARIA	Enviado sem veredito dentro da janela	Reemitir se ainda desejado
BOLETO_VENCIDO_SEM_REGISTRO	PLATAFORMA	Boleto online venceu antes do registro	Atualizar o vencimento para re-solicitar

Nota

Em REGISTRO_REJEITADO, a “ação sugerida” vira reemitir se ainda desejado — o boleto saiu da janela de registro. A situacao qualifica a ação; o codigo dá a causa.

Blocos pagamento, baixa e protesto

• pagamento (ou null): { situacao: "PAGAMENTO_INFORMADO", data, valor, dataCredito, forma, origem, marcadoComoPago, multa, juros, desconto, pix }. Cobre tanto a confirmação bancária quanto a marcação manual — distinga por origem + marcadoComoPago. Os multa/juros/desconto deste bloco são os aplicados na liquidação (ver Dados de Conferência).
• baixa (ou null): { situacao, dataSistema, dataBanco, motivo, descricao, origem } — situacao ∈ BAIXA_NO_SISTEMA, BAIXA_EM_PROGRESSO, BAIXA_CONFIRMADA.
• protesto (ou null): { situacao, dataSistema, dataBanco, origem, descricao } — situacao ∈ PROTESTO_NO_SISTEMA, PROTESTO_EM_PROGRESSO, PROTESTO_CONFIRMADO, CANCELAMENTO_NO_SISTEMA, CANCELAMENTO_EM_PROGRESSO, CANCELAMENTO_CONFIRMADO.

Semântica de datas

Nos três blocos, dataSistema é quando a plataforma registrou o movimento; dataBanco é a data do fato confirmada pelo banco. Podem divergir por atraso de sincronização.

Bloco pix

Cenário	Conteúdo
pix: null	Sem instrumento PIX relevante (não solicitado, ou emissão via CNAB sem dados de PIX)
PIX_GERADO	Instrumento usável: txId + codigoEMV preenchidos, erro: null
PIX_NAO_GERADO	O boleto foi registrado online com PIX gerenciado pelo banco solicitado, mas o banco não disponibilizou o QR Code: txId/codigoEMV null e erro preenchido

codigoEMV é o “Pix Copia e Cola”. Exemplo de PIX gerado com sucesso:

"pix": { "situacao": "PIX_GERADO", "erro": null, "txId": "tx-abc-123", "codigoEMV": "00020126580014BR.GOV.BCB.PIX..." }

pix.erro

Estrutura: { origem, codigo, mensagem, informadoEm }.

• origem: sempre BANCO hoje (o resultado do registro bancário não disponibilizou o PIX).
• codigo: CHAVE_PIX_NAO_CADASTRADA (acionável: cadastre/disponibilize a chave PIX da conta no banco) ou PIX_NAO_DISPONIBILIZADO_PELO_BANCO (genérico: use a linha digitável/código de barras).
• mensagem: fixa por código. O retorno técnico cru do banco nunca é exposto.
• informadoEm (AAAA-MM-DD): data em que a plataforma registrou a falha de geração do PIX (ciência da plataforma, não data do fato no banco). Em dados históricos raros pode ser null — o bloco erro continua presente.

Códigos de Resposta

Código	Descrição
200 OK	Consulta realizada com sucesso
400 Bad Request	Token malformado
404 Not Found	Boleto não existe ou foi excluído

Exemplos de Código

cURL

# Pelo token da Boleto Cloud
curl "https://sandbox.boletocloud.com/api/v1/boletos/TOKEN_DO_BOLETO/situacao" \
  -H "Accept: application/json" \
  -u "api-key_SUA-API-KEY:token"

# Pelo identificador do seu sistema (tokenControleUsuario)
curl "https://sandbox.boletocloud.com/api/v1/boletos/controle/pedido-12345/situacao" \
  -H "Accept: application/json" \
  -u "api-key_SUA-API-KEY:token"

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import static javax.ws.rs.core.MediaType.APPLICATION_JSON;

public class ConsultaSituacao {
    public static void main(String[] args) {
        String tokenBoleto = "TOKEN_DO_BOLETO";
        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos")
            .path("/" + tokenBoleto + "/situacao")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request(APPLICATION_JSON)
            .get();

        if (response.getStatus() == 200) {
            System.out.println("Situação: " + response.readEntity(String.class));
        } else {
            System.out.println("Erro: " + response.getStatus());
        }
    }
}

Kotlin

import okhttp3.Credentials
import okhttp3.OkHttpClient
import okhttp3.Request

fun main() {
    val tokenBoleto = "TOKEN_DO_BOLETO"
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos/$tokenBoleto/situacao")
        .header("Authorization", credential)
        .header("Accept", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            println("Situação: ${response.body?.string()}")
        } else {
            println("Erro: ${response.code}")
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var tokenBoleto = "TOKEN_DO_BOLETO";
        using var client = new HttpClient();
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);
        client.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));

        var response = await client.GetAsync(
            $"https://sandbox.boletocloud.com/api/v1/boletos/{tokenBoleto}/situacao");

        if (response.IsSuccessStatusCode) {
            var json = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Situação: {json}");
        } else {
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
        }
    }
}

Node

const https = require('https');

const tokenBoleto = 'TOKEN_DO_BOLETO';
const options = {
  hostname: 'sandbox.boletocloud.com',
  path: `/api/v1/boletos/${tokenBoleto}/situacao`,
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {'Accept': 'application/json'}
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => {
    if (res.statusCode === 200) {
      const { boleto } = JSON.parse(data);
      console.log('Situação:', boleto.situacao);
      console.log('Registro:', boleto.registro.situacao);
    } else {
      console.log(`Erro: ${res.statusCode}`);
    }
  });
});

req.end();

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    tokenBoleto := "TOKEN_DO_BOLETO"
    req, _ := http.NewRequest("GET",
        "https://sandbox.boletocloud.com/api/v1/boletos/"+tokenBoleto+"/situacao", nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Accept", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    if resp.StatusCode == 200 {
        fmt.Println("Situação:", string(body))
    } else {
        fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

PHP

<?php
$tokenBoleto = 'TOKEN_DO_BOLETO';
$url = "https://sandbox.boletocloud.com/api/v1/boletos/$tokenBoleto/situacao";
$api_key = 'api-key_SUA-API-KEY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $data = json_decode($response, true);
    print_r($data['boleto']);
} else {
    echo "Erro ($http_code): $response\n";
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

token_boleto = 'TOKEN_DO_BOLETO'
response = requests.get(
    f'https://sandbox.boletocloud.com/api/v1/boletos/{token_boleto}/situacao',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    headers={'Accept': 'application/json'}
)

if response.status_code == 200:
    boleto = response.json()['boleto']
    print(f"Situação: {boleto['situacao']}")
    print(f"Registro: {boleto['registro']['situacao']}")
    if boleto['registro']['erro']:
        erro = boleto['registro']['erro']
        print(f"Impedimento: {erro['codigo']} ({erro['origem']}) em {erro['informadoEm']}")
else:
    print(f'Erro: {response.status_code}')

Ruby

require 'net/http'
require 'uri'
require 'json'

token_boleto = 'TOKEN_DO_BOLETO'
uri = URI("https://sandbox.boletocloud.com/api/v1/boletos/#{token_boleto}/situacao")

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Get.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request['Accept'] = 'application/json'

  response = http.request(request)
  if response.code == '200'
    boleto = JSON.parse(response.body)['boleto']
    puts "Situação: #{boleto['situacao']}"
  else
    puts "Erro: #{response.code}"
  end
end

Clojure

(require '[clj-http.client :as client])

(let [token-boleto "TOKEN_DO_BOLETO"
      response (client/get
                (str "https://sandbox.boletocloud.com/api/v1/boletos/" token-boleto "/situacao")
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :accept :json
                 :as :json})]
  (if (= 200 (:status response))
    (println "Situação:" (get-in response [:body :boleto :situacao]))
    (println "Erro:" (:status response))))

Veja Também

Criar Boleto/PDFCriar novos boletos

Status do RegistroConsulta específica do eixo de registro

IdempotênciaComo definir o tokenControleUsuario

Alterar VencimentoRe-solicitar registro de boleto vencido