Boleto

Emitir

curl -X POST https://api.tamino.com.br/v1/boletos \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "payerDocument": "12345678900",
    "payerName": "Maria da Silva",
    "externalId": "pedido-12345"
  }'

const boleto = await gateway.boletos.create({
  amountInCents: 5000,
  payerDocument: '12345678900',
  payerName: 'Maria da Silva',
  externalId: 'pedido-12345',
});

{
  "id": "9480f523-...",
  "object": "boleto",
  "externalId": "pedido-12345",
  "status": "pending_payment",
  "amountInCents": 5000,
  "ourNumber": "mock_boleto_...",
  "barcode": "00190000090000000000000000000000000000000000",
  "digitableLine": "00190.00009 00000.000000 00000.000000 0 00000000000000",
  "dueDate": "2026-08-28"
}

payerDocument e payerName são obrigatórios — todo boleto precisa de um sacado identificável. O vencimento (dueDate) é definido automaticamente (alguns dias de folga a partir da criação) — não é configurável via /v1/boletos nesta entrega.

Seu id do pedido (externalId) e timeout

Mande em externalId o id do pedido no seu sistema (até 64 caracteres: letras, números, ., _, : e -). Ele volta em todas as respostas da cobrança (criação e consulta; null se não enviado) e em todos os webhooks dela, e é único por merchant: repetir o POST com o mesmo externalId devolve a cobrança que já existe — mesmo id, mesmo boleto (barcode/digitableLine) — sem criar outra. O mesmo externalId com outro valor ou outro método responde 409.

Exceção: se a tentativa anterior falhou no provider e nenhum boleto chegou a ser emitido, reenviar com o mesmo externalId tenta de novo na mesma cobrança (mesmo id) e devolve o boleto novo.

Se o pedido der timeout ou erro de rede, você não recebe o nosso id, mas não perde a cobrança:

• consulte pelo seu id: GET /v1/boletos/external/{externalId} (404 = a cobrança não foi criada);
• ou simplesmente reenvie o mesmo pedido com o mesmo externalId — nunca nasce uma segunda cobrança.

Com uma API key do tenant (não presa a um merchant), passe ?merchantId= na consulta quando o mesmo externalId existir em mais de um merchant (senão a resposta é 400).

curl https://api.tamino.com.br/v1/boletos/external/pedido-12345 \
  -H "Authorization: Bearer sk_test_..."

Consultar

GET /v1/boletos/:id reconsulta ao vivo — barcode/digitableLine voltam de novo:

const boleto = await gateway.boletos.get('pay_123');

Cancelar

Só funciona enquanto o boleto ainda não foi pago:

await gateway.boletos.cancel('pay_123');

Confirmação de pagamento

Boleto não confirma pagamento em tempo real — a compensação bancária pode levar até alguns dias úteis. Trate o webhook boleto.paid/payment.paid (ver Webhooks); não existe hoje um jeito de "adiantar" essa confirmação, nem em sandbox.