Consultar Status do Registro

Consulta se o boleto foi registrado com sucesso no banco ou se houve erro/rejeição. Esta verificação é importante para garantir que o boleto está apto para pagamento antes de enviá-lo ao pagador.

Visão completa em JSON

Esta página cobre o eixo específico do registro. Para a situação operacional completa do boleto — registro com motivo estruturado, pagamento, baixa, protesto, Pix e condições de emissão — use Consultar Situação.

Possíveis Status

Status	Descrição	Ação Recomendada
Registrado	Boleto confirmado no banco, apto para pagamento	Pode ser enviado ao pagador
Aguardando	Boleto enviado, aguardando confirmação do banco	Aguardar ou consultar novamente
Rejeitado	Banco recusou o registro (ex: CEP inválido)	Corrigir dados e reemitir

Quando Usar

Cenário	Recomendação
Verificar se o boleto está apto para pagamento antes de enviar ao cliente	Sim
Implementar lógica de retry em caso de rejeição	Sim
Monitorar o status de boletos em integração via arquivo CNAB	Sim
Automatizar fluxo de reemissão de boletos rejeitados	Sim

Dica

Em integrações via arquivo CNAB, o status de registro é atualizado quando você processa o arquivo de retorno enviado pelo banco.

Endpoint

GET https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro

Headers

Header	Valor
Accept	application/json
Authorization	Basic {credenciais}

Parâmetros da URL

Parâmetro	Tipo	Descrição
token_do_boleto	string	Token identificador do boleto

Estrutura da Resposta

{
  "status": {
    "token": "token_do_boleto",
    "registrado": "2024-01-06",
    "erro": null
  }
}

Campos da Resposta

Campo	Tipo	Descrição
token	string	Token do boleto consultado
registrado	date | null	Data em que o boleto foi registrado (formato AAAA-MM-DD). null se não foi registrado
erro	string | null	Mensagem de erro caso o registro tenha sido rejeitado. null se não houve erro

Códigos de Resposta

Código	Descrição
200 OK	Consulta realizada com sucesso

Cenários de Resposta

Boleto Registrado com Sucesso

{
  "status": {
    "token": "token_exemplo_123",
    "registrado": "2024-01-06",
    "erro": null
  }
}

Boleto com Registro Rejeitado

{
  "status": {
    "token": "token_exemplo_123",
    "registrado": null,
    "erro": "03-Entrada rejeitada\nMotivo(s):\n48-CEP irregular"
  }
}

Exemplos de Código

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro" \
  -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 ConsultaStatusRegistro {
    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 + "/registro")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request(APPLICATION_JSON)
            .get();

        if (response.getStatus() == 200) {
            System.out.println("Status: " + 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/registro")
        .header("Authorization", credential)
        .header("Accept", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            println("Status: ${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}/registro");

        if (response.IsSuccessStatusCode) {
            var json = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Status: {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}/registro`,
  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) console.log('Status:', JSON.parse(data));
    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+"/registro", 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("Status:", 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/registro";
$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['status']);
} 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}/registro',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    headers={'Accept': 'application/json'}
)

if response.status_code == 200:
    status = response.json()['status']
    if status['registrado']:
        print(f"Boleto registrado em: {status['registrado']}")
    elif status['erro']:
        print(f"Erro no registro: {status['erro']}")
    else:
        print("Boleto aguardando registro")
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}/registro")

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'
    status = JSON.parse(response.body)['status']
    puts "Status: #{status}"
  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 "/registro")
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :accept :json
                 :as :json})]
  (if (= 200 (:status response))
    (println "Status:" (get-in response [:body :status]))
    (println "Erro:" (:status response))))

Dica

Utilize esta consulta para verificar se um boleto foi registrado com sucesso antes de enviá-lo ao pagador, especialmente quando o banco exige registro prévio.

Nota

O campo erro pode conter múltiplas linhas com os motivos da rejeição. Certifique-se de tratar adequadamente as quebras de linha (\n) ao exibir a mensagem para o usuário.

Veja Também

Consultar SituaçãoVisão completa do boleto em JSON

Criar Boleto/PDFCriar novos boletos

Arquivo de RetornoProcessar confirmações via CNAB

Alterar RegistroHabilitar boleto para registro

Arquivo de RemessaIntegração via arquivo CNAB