Habilitar Boleto para Registro

Alterar Registro (PUT)

Altera o status de registro do boleto, permitindo habilitar um boleto criado com cobrancaBancaria.registrar = false para que seja enviado ao banco.

O que Faz

Este endpoint permite controlar quando um boleto deve ser registrado no banco. Ao alterar o campo registrar para true, o boleto será incluído na próxima remessa CNAB ou enviado automaticamente ao banco, dependendo da configuração da sua conta.

Ação	Resultado
registrar: true	Boleto será enviado ao banco para registro
registrar: false	Boleto permanece sem registro (não pode ser pago)

Quando Usar

Esta funcionalidade é útil quando você precisa criar boletos mas controlar o momento exato do registro no banco.

Cenário	Recomendação
Cliente confirmou intenção de pagamento	Sim
Proposta comercial foi aceita	Sim
Pedido de e-commerce foi confirmado	Sim
Entrega foi realizada com sucesso	Sim
Apenas visualizar boleto para orçamento	Não (mantenha registrar: false)

Ciclo de Vida do Registro

┌────────────────────────────────────────────────────────────────────────┐
│                                                                        │
│  ┌─────────────┐     ┌───────────────┐     ┌──────────────────────┐   │
│  │ CRIAR       │     │ AGUARDANDO    │     │ HABILITAR            │   │
│  │ BOLETO      │────►│ DECISÃO       │────►│ REGISTRO             │   │
│  │ registrar=  │     │               │     │ PUT .../registro     │   │
│  │ false       │     │ Boleto existe │     │ registrar=true       │   │
│  └─────────────┘     │ mas não será  │     └──────────┬───────────┘   │
│                      │ registrado    │                │               │
│                      └───────────────┘                ▼               │
│                                              ┌──────────────────────┐ │
│                                              │ REGISTRADO           │ │
│                                              │ Enviado ao banco     │ │
│                                              │ Apto para pagamento  │ │
│                                              └──────────────────────┘ │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Guia Prático Completo

Para entender o fluxo completo de como criar boletos e registrar depois, incluindo exemplos práticos de criação e consulta de status, consulte o guia Registrar Boleto Depois.

Endpoint

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

Fluxo de Requisição

Headers

Header	Valor
Content-Type	application/json; charset=utf-8
Authorization	Basic {credenciais}

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
token_do_boleto	string	Sim	Token identificador do boleto

Body da Requisição

O corpo da requisição deve conter o novo valor do campo registrar em formato JSON.

{
  "boleto": {
    "cobrancaBancaria": {
      "registrar": true
    }
  }
}

Campo	Tipo	Descrição
boleto.cobrancaBancaria.registrar	boolean	true para habilitar registro, false para desabilitar

Validações

Validação	Erro	Código HTTP
Token do boleto inválido ou inexistente	Boleto não encontrado	500 (será 404 futuramente)
JSON malformado	Erro de parsing	400

Códigos de Resposta

Código	Descrição	Próximo Passo
200 OK	Registro alterado com sucesso	Aguardar envio ao banco ou consultar status
400 Bad Request	Requisição inválida	Verificar formato do JSON
500 Internal Server Error	Boleto não encontrado	Verificar token do boleto

Resposta de Sucesso

HTTP/1.1 200 OK

Nota

O endpoint retorna apenas o código HTTP 200 OK em caso de sucesso, sem corpo na resposta. Para verificar o status atualizado do registro, utilize o endpoint Obter Status do Registro.

Comportamento com o Banco

O comportamento após habilitar o registro depende do tipo de comunicação configurado na sua conta bancária:

Tipo de Comunicação	O que acontece
API/Webservice (automático)	Boleto é enviado automaticamente ao banco para registro
Arquivo CNAB (manual)	Boleto é incluído na próxima remessa CNAB gerada

Importante

Boletos com registrar = false não podem ser pagos nos canais bancários. Certifique-se de habilitar o registro antes de disponibilizar o boleto para pagamento ao cliente.

Exemplos de Código

cURL

curl -v "https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro" \
  -H "Content-Type: application/json; charset=utf-8" \
  -X "PUT" \
  -u "api-key_SUA-API-KEY:token" \
  -d '{"boleto":{"cobrancaBancaria":{"registrar":true}}}'

Java

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

public class AlterarRegistro {
    public static void main(String[] args) {
        String tokenBoleto = "TOKEN_DO_BOLETO";
        String json = "{\"boleto\":{\"cobrancaBancaria\":{\"registrar\":true}}}";

        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)
            .put(Entity.json(json));

        if (response.getStatus() == 200) {
            System.out.println("Boleto habilitado para registro!");
        } else {
            System.out.println("Erro: " + response.getStatus());
        }
    }
}

Kotlin

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

fun main() {
    val tokenBoleto = "TOKEN_DO_BOLETO"
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")
    val json = """{"boleto":{"cobrancaBancaria":{"registrar":true}}}"""

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

    client.newCall(request).execute().use { response ->
        if (response.code == 200) println("Boleto habilitado para registro!")
        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);

        var json = "{\"boleto\":{\"cobrancaBancaria\":{\"registrar\":true}}}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await client.PutAsync(
            $"https://sandbox.boletocloud.com/api/v1/boletos/{tokenBoleto}/registro", content);

        if ((int)response.StatusCode == 200)
            Console.WriteLine("Boleto habilitado para registro!");
        else
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
    }
}

Node

const https = require('https');

const tokenBoleto = 'TOKEN_DO_BOLETO';
const data = JSON.stringify({boleto: {cobrancaBancaria: {registrar: true}}});

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: `/api/v1/boletos/${tokenBoleto}/registro`,
  method: 'PUT',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data)}
};

const req = https.request(options, (res) => {
  if (res.statusCode === 200) console.log('Boleto habilitado para registro!');
  else console.log(`Erro: ${res.statusCode}`);
});

req.write(data);
req.end();

Go

package main

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

func main() {
    tokenBoleto := "TOKEN_DO_BOLETO"
    json := `{"boleto":{"cobrancaBancaria":{"registrar":true}}}`
    url := "https://sandbox.boletocloud.com/api/v1/boletos/" + tokenBoleto + "/registro"

    req, _ := http.NewRequest("PUT", url, strings.NewReader(json))
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type", "application/json")

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

    if resp.StatusCode == 200 {
        fmt.Println("Boleto habilitado para registro!")
    } 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';
$data = json_encode(['boleto' => ['cobrancaBancaria' => ['registrar' => true]]]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: 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) echo "Boleto habilitado para registro!\n";
else echo "Erro ($http_code): $response\n";
?>

Python

import requests
from requests.auth import HTTPBasicAuth

token_boleto = 'TOKEN_DO_BOLETO'
response = requests.put(
    f'https://sandbox.boletocloud.com/api/v1/boletos/{token_boleto}/registro',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    json={'boleto': {'cobrancaBancaria': {'registrar': True}}}
)

if response.status_code == 200:
    print('Boleto habilitado para 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::Put.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request['Content-Type'] = 'application/json'
  request.body = {boleto: {cobrancaBancaria: {registrar: true}}}.to_json

  response = http.request(request)
  if response.code == '200'
    puts 'Boleto habilitado para registro!'
  else
    puts "Erro: #{response.code}"
  end
end

Clojure

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

(let [token-boleto "TOKEN_DO_BOLETO"
      response (client/put
                (str "https://sandbox.boletocloud.com/api/v1/boletos/" token-boleto "/registro")
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :content-type :json
                 :body "{\"boleto\":{\"cobrancaBancaria\":{\"registrar\":true}}}"
                 :throw-exceptions false})]
  (if (= 200 (:status response))
    (println "Boleto habilitado para registro!")
    (println "Erro:" (:status response))))

Veja Também

Guia: Registrar Boleto Depois Fluxo completo com exemplos de criação e consulta

Obter Status do Registro Consultar se o boleto foi registrado no banco

Arquivo de Remessa Integração via arquivo CNAB

Arquivo de Retorno Processar confirmações do banco