Registrar Boleto Depois

Registrar Boleto Depois

Esta funcionalidade permite criar um boleto e escolher quando ele deve ser registrado no banco. O boleto é gerado normalmente, mas não é enviado para registro até que você decida.

Como Funciona

Ao criar um boleto com boleto.cobrancaBancaria.registrar = false:

1. O boleto é criado e o PDF é gerado normalmente
2. O boleto não é incluído em nenhuma remessa CNAB
3. O boleto não é enviado automaticamente para o banco
4. Você pode habilitar o registro posteriormente via nossa API

Quando Usar

• E-commerce: Criar boleto no checkout e registrar apenas quando o cliente confirmar
• Propostas comerciais: Gerar boleto para orçamento sem custo de registro
• Distribuidoras: Imprimir boleto junto com a carga e registrar apenas após confirmação de entrega, evitando custos com devoluções
• Controle de fluxo/custos: Decidir o momento exato do registro conforme sua regra de negócio

1. Criar Boleto sem Registrar

cURL

curl -X POST "https://sandbox.boletocloud.com/api/v1/boletos" \
  -u "api-key_SUA-API-KEY:token" \
  -d "boleto.conta.token=TOKEN_DA_CONTA" \
  -d "boleto.cobrancaBancaria.registrar=false" \
  -d "boleto.emissao=2024-01-15" \
  -d "boleto.vencimento=2024-01-30" \
  -d "boleto.documento=PROP-001" \
  -d "boleto.titulo=DM" \
  -d "boleto.valor=150.00" \
  -d "boleto.pagador.nome=Alberto Santos Dumont" \
  -d "boleto.pagador.cprf=000.000.000-00" \
  -d "boleto.pagador.endereco.cep=00000-000" \
  -d "boleto.pagador.endereco.uf=MG" \
  -d "boleto.pagador.endereco.localidade=Santos Dumont" \
  -d "boleto.pagador.endereco.bairro=Centro" \
  -d "boleto.pagador.endereco.logradouro=Rua Principal" \
  -d "boleto.pagador.endereco.numero=100" \
  -o boleto.pdf

Java

Response response = ClientBuilder.newClient()
    .target("https://sandbox.boletocloud.com/api/v1/boletos")
    .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
    .request(WILDCARD)
    .post(Entity.form(new Form()
        .param("boleto.conta.token", "TOKEN_DA_CONTA")
        .param("boleto.cobrancaBancaria.registrar", "false")
        .param("boleto.emissao", "2024-01-15")
        .param("boleto.vencimento", "2024-01-30")
        .param("boleto.documento", "PROP-001")
        .param("boleto.titulo", "DM")
        .param("boleto.valor", "150.00")
        .param("boleto.pagador.nome", "Alberto Santos Dumont")
        .param("boleto.pagador.cprf", "000.000.000-00")
        .param("boleto.pagador.endereco.cep", "00000-000")
        .param("boleto.pagador.endereco.uf", "MG")
        .param("boleto.pagador.endereco.localidade", "Santos Dumont")
        .param("boleto.pagador.endereco.bairro", "Centro")
        .param("boleto.pagador.endereco.logradouro", "Rua Principal")
        .param("boleto.pagador.endereco.numero", "100")));

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://sandbox.boletocloud.com/api/v1/boletos',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    data={
        'boleto.conta.token': 'TOKEN_DA_CONTA',
        'boleto.cobrancaBancaria.registrar': 'false',
        'boleto.emissao': '2024-01-15',
        'boleto.vencimento': '2024-01-30',
        'boleto.documento': 'PROP-001',
        'boleto.titulo': 'DM',
        'boleto.valor': '150.00',
        'boleto.pagador.nome': 'Alberto Santos Dumont',
        'boleto.pagador.cprf': '000.000.000-00',
        'boleto.pagador.endereco.cep': '00000-000',
        'boleto.pagador.endereco.uf': 'MG',
        'boleto.pagador.endereco.localidade': 'Santos Dumont',
        'boleto.pagador.endereco.bairro': 'Centro',
        'boleto.pagador.endereco.logradouro': 'Rua Principal',
        'boleto.pagador.endereco.numero': '100'
    }
)

if response.status_code == 201:
    with open('boleto.pdf', 'wb') as f:
        f.write(response.content)

Documentação Completa

Para conhecer todos os parâmetros disponíveis na criação de boletos, incluindo instruções de multa, juros, descontos e outras opções, consulte a documentação do endpoint Criar Boleto.

2. Consultar Status do Registro

Verifique se o boleto está marcado para registro, se já foi registrado ou se houve erro.

cURL

curl "https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro" \
  -u "api-key_SUA-API-KEY:token" \
  -H "Content-Type: application/json"

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    headers={'Content-Type': 'application/json'}
)

print(response.json())

Resposta

{
  "status": {
    "token": "token_do_boleto",
    "registrar": false,
    "registrado": null,
    "erro": null
  }
}

Campo	Descrição
registrar	true = marcado para registrar, false = não será registrado
registrado	true = já registrado no banco, null = ainda não registrado
erro	Mensagem de erro caso o registro tenha falhado

3. Habilitar o Registro

Quando decidir que o boleto deve ser registrado, altere o campo via API. O boleto será incluído na próxima remessa ou enviado automaticamente ao banco.

cURL

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

Java

Response response = ClientBuilder.newClient()
    .target("https://sandbox.boletocloud.com/api/v1/boletos/{token_do_boleto}/registro")
    .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
    .request(MediaType.APPLICATION_JSON)
    .put(Entity.json("{\"boleto\":{\"cobrancaBancaria\":{\"registrar\":true}}}"));

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

if response.status_code == 200:
    print('Boleto habilitado para registro!')

Resposta

HTTP/1.1 200 OK

Envio Automático

Se sua conta estiver configurada para envio automático, o boleto será registrado no banco assim que você alterar o campo para true. Caso contrário, ele será incluído na próxima remessa CNAB gerada.

Fluxo Completo

┌─────────────────────────────────────────────────────────────────────┐
│  1. CRIAR BOLETO (cobrancaBancaria.registrar = false)               │
│     └──► Boleto criado, PDF gerado, NÃO enviado ao banco            │
│                                                                     │
│  2. CONSULTAR STATUS (GET /boletos/{token}/registro)                │
│     └──► Verificar: registrar=false, registrado=null                │
│                                                                     │
│  3. HABILITAR REGISTRO (PUT /boletos/{token}/registro)              │
│     └──► Alterar: registrar=true                                    │
│     └──► Boleto será enviado ao banco (automático ou via remessa)   │
│                                                                     │
│  4. CONSULTAR STATUS NOVAMENTE                                      │
│     └──► Verificar: registrar=true, registrado=true (após envio)    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Atenção

Boletos não registrados não podem ser pagos nos canais bancários. Certifique-se de habilitar o registro antes de disponibilizar o boleto para pagamento.

Veja Também

• Obter Status do Registro - Endpoint de consulta de status
• Boleto Proposta - Casos de uso para boletos não registrados
• Arquivos CNAB - Geração de remessas
• Alterar Registro - Habilitar boleto para registro