Cobrança de Boletos

Objetivo

Emitir boleto de cobrança na conta titular: o POST cria a cobrança (visível em Cobranças inteligentes) e já devolve os dados do boleto.

Pré-requisito: Login da conta. Scopes baas.charges.bankslips.write (criar) e baas.charges.bankslips.read (consultar, listar, PDF). HMAC em todos os pedidos. Algoritmo: Autenticação da plataforma BaaS (Bearer da conta).

Ordem de uso

A emissão cabe em um único pedido. POST /api/v2/baas/charges/bankslips cria a cobrança e o boleto e responde 201 com linha digitável, código de barras, status, id (numérico do boleto), charge_id (UUID da cobrança) e checkout_url. O corpo não traz PDF.

Guarde o id do boleto. Com ele, GET /api/v2/baas/charges/bankslips/{id} devolve o mesmo JSON (consulta de status, código de barras após atualização, etc.), também sem PDF.

Se precisar do arquivo para impressão ou anexo, chame GET /api/v2/baas/charges/bankslips/{id}/pdf. Se o PDF ainda não existir, a API inicia a geração e responde 202 pedindo espera. Quando estiver pronto, o mesmo GET devolve { "pdf": "<base64>" }. No POST, o PDF só começa se generate_pdf for true (padrão: não gerar).

Para buscar vários boletos da conta (painel, conciliação), use GET /api/v2/baas/charges/bankslips com os filtros de query. Cada item da lista segue o mesmo formato da consulta por id, sem PDF.

Autenticação: sem HMAC, 401. Scope trocado (.read no POST ou .write nos GETs), 403. {id} de outra conta ou inexistente, 404.

Endpoints

Criar

Autenticação

Bearer da conta, HMAC. Corpo JSON idêntico na assinatura.

Corpo mínimo

Campos dentro de customer.address:

Campos opcionais

Com items: o total dos itens é quantity × unit_amount em cada linha. Se você enviar amount junto, ele deve ser só essa soma. shipping_fee e discount não entram no amount dos itens; entram no valor final cobrado.

generate_pdf: booleano. Omitido ou false (padrão): o POST não gera PDF. true: a API enfileira a geração em segundo plano. O 201 sempre vem sem chave pdf; busque o arquivo depois em GET .../{id}/pdf (pode responder 202 enquanto processa).

Resposta

201 com dados do boleto (barcode, digitable_line, our_number, valores, datas, status do boleto), id numérico, charge_id (uuid da cobrança) e checkout_url. Sem chave pdf.

status na resposta é o do boleto (pending, paid, canceled, expired).

{
  "id": 999001,
  "charge_id": "018f1b2c-3d4e-7a89-b012-3456789abcde",
  "checkout_url": "https://pagamento-h.nuvende.com.br/018f1b2c-3d4e-7a89-b012-3456789abcde",
  "barcode": "38293120500000259654765254329385806906458038",
  "digitable_line": "38294765265432938580869064580389312050000025965",
  "our_number": "O1",
  "your_number": "Y1",
  "status": "pending",
  "value_total": 100.5,
  "value_original": 100.5,
  "due_date": "2026-09-20T00:00:00+00:00",
  "payer_name": "Maria Silva",
  "payer_document": "00000000000"
}

Valores value_total / value_original vêm em reais. O amount do pedido em centavos.

Consultar

Autenticação

Bearer da conta, HMAC. Corpo [] na assinatura.

Path

{id} = campo id numérico da resposta do POST.

Resposta

200 com o mesmo objeto do POST (sem chave pdf).

{
  "id": 999001,
  "charge_id": "018f1b2c-3d4e-7a89-b012-3456789abcde",
  "checkout_url": "https://pagamento-h.nuvende.com.br/018f1b2c-3d4e-7a89-b012-3456789abcde",
  "barcode": "38293120500000259654765254329385806906458038",
  "digitable_line": "38294765265432938580869064580389312050000025965",
  "our_number": "O1",
  "your_number": "Y1",
  "status": "pending",
  "value_total": 100.5,
  "value_original": 100.5,
  "due_date": "2026-09-20T00:00:00+00:00",
  "payer_name": "Maria Silva",
  "payer_document": "00000000000"
}

Regras de negócio

• Boleto que não pertence à conta → 404.

Obter PDF

Autenticação

Bearer da conta, HMAC. Corpo [] na assinatura.

Resposta

Se o PDF já estiver pronto: 200 com JSON { "pdf": "<base64>" }. Decodifique o base64 para obter o arquivo.

Se ainda não houver geração em andamento para aquele boleto, a API inicia o print e responde 202:

{
  "message": "O PDF do boleto ainda está sendo gerado. Tente novamente em instantes."
}

Repita o GET até receber 200. Se já existir geração em andamento, o GET não dispara outra geração de PDF: consulta o mesmo pedido e devolve 202 enquanto estiver pendente, ou 200 quando concluir.

Falha definitiva na geração: 502. Consulte o JSON (GET .../{id}) e tente o PDF de novo.

{
  "pdf": "JVBERi0xLjQK..."
}

Listar

Autenticação

Bearer da conta, HMAC. Corpo [] na assinatura. A query da URL entra na linha QUERY da mensagem HMAC.

Parâmetros de query (URL)

Filtros e paginação vão na URL, após o ?. Cada parâmetro usa nome=valor. Combine vários com &. Todos são opcionais.

Exemplo completo:

GET /api/v2/baas/charges/bankslips?status=pending&per_page=10&page=1

Outros exemplos: ?reference_id=PED-123, ?due_date_from=2026-01-01&due_date_to=2026-12-31, ?document=11144477735.

Resposta

200 com JSON paginado (data, current_page, per_page, total). Cada item em data segue o mesmo formato da consulta por {id} acima, sem chave pdf.

Erros frequentes