Boletos

A API de boletos permite que você crie boletos únicos, parcelados e em lote para um ou múltiplos clientes, assim como a assinatura de eventos de boletos. Com esta API, você pode criar boletos com códigos de barras e QR codes para pagamento por Pix.

Um boletos tem três participantes:

• O cedente ou beneficiário, que vendeu um produto ou serviço e emitiu o boleto.
• O sacado, que vai pagar o boleto.
• O sacador avalista, que emite o boleto para outra empresa.

Para emitir um boleto, apenas as informações do sacado são necessárias.

*Só é possível emitir boletos em nome da sua empresa.

*O formato para inserir quantias é 0.10.

Casos de Uso

• Usar boletos do BTG Empresas como meio de pagamento.
• Criar boletos a partir de um sistema de gestão empresarial.
• Integrar com sistemas de contas a receber.
• Aplicativos móveis com emissão e gerenciamento de boletos.

Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Boletos deve ser gerado usando o Authorization Code.

O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário escolher um dos seguintes escopos:

Recursos Disponíveis

Com a API de Boletos, você pode:

• Criar boletos BTG Empresas personalizados para seus clientes, com opções de parcelamento, criação em lote e pagamento via Pix.
• Atualizar informações em boletos como valor, data de vencimento, multas e juros.
• Organizar boletos por data de criação, vencimento ou pagamento, além de status e pagador.

Os recursos da API de Boletos estão disponíveis no API Reference.

📘

API Reference

Boletos API

Nosso número

Você pode definir os 16 dígitos do boleto no campo nosso número (ourNumber). Pode ser qualquer código, desde que não seja o mesmo de um boleto apto para pagamento. Caso o campo esteja em branco, os 16 dígitos do boleto serão gerados automaticamente.

Status de boletos

Um boleto pode ter diversos status:

Os status seguem os seguintes fluxos:

Fluxo normal

Um boleto é emitido e pago, podendo ser cancelado depois da emissão.

Fluxo de atualização

Um boleto emitido é atualizado, podendo ser cancelado após a atualização.

Fluxo de vencimento

Um boleto emitido perde a validade, podendo ser pago ou atualizado.

Eventos

A API de Boletos disponibiliza os seguintes eventos de webhook:

bank-slips.updated

Boleto atualizado.
*Boletos com QR Code não podem ser atualizados.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "UPDATED",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 39.27,
  "dueDate": "2023-04-10"
}

bank-slips.canceled

Boleto cancelado.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "CANCELED",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.cancel_failed

Falha ao cancelar boleto.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "CANCEL_FAILED",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 3927,
  "dueDate": "2023-04-10"
}

bank-slips.paid

Boleto pago.

{
  "bankSlipId": "1bdd6d6b-0000-0000-0000-9c5d36e91579",
  "correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
  "status": "PAID",
  "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
  },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 39.27,
  "dueDate": "2023-04-10"
}

bank-slips.failed

Falha ao criar boleto.

{
    "bankSlipId": "863532c6-0000-0000-0000-601e34bedc86",
    "correlationId": "2385751161",
    "status": "FAILED",
    "barCode": "20000000000000000000000000000000000000000",
  "digitableLine": "20000000000000000000000000000000000000000",
  "payee": {
    "accountId": "0000000000009-008-00-00000001"
     },
  "payer": {
    "name": "PAYER LTDA",
    "taxId": "1000000000000"
  },
  "amount": 392.7,
  "dueDate": "2023-04-10"
}