Boletos
Gere boletos únicos, parcelados ou em lote com a API de 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:
| Escopo | Descrição |
|---|---|
empresas.btgpactual.com/bank-slips | Permite criação e consulta de boletos. |
empresas.btgpactual.com/bank-slips.readonly | Permite consulta de boletos e recebimento de webhooks. |
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
Campo ourNumber
Você pode definir os 16 dígitos do boleto no campo ourNumber. Pode-se utilizar 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:
| Status | Descrição |
|---|---|
| CREATED | Boleto emitido |
| PAID | Boleto pago |
| CANCELED | Boleto cancelado |
| EXPIRED | Boleto vencido |
| PROCESSING | Boleto em processamento |
| FAILED | Falha na emissão do boleto |
| UPDATED | Boleto atualizado |
| UPDATING | Boleto em atualização |
| CANCEL_FAILED | Falha no cancelamento do boleto |
| RETURNED | Boleto estornado |
| CANCELING | Boleto em cancelamento |
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:
| Identificação do Evento | Descrição |
|---|---|
bank-slips.failed | Falha ao criar boleto |
bank-slips.updated | Boleto atualizado |
bank-slips.update_failed | Falha ao atualizar boleto |
bank-slips.canceled | Boleto cancelado |
bank-slips.cancel_failed | Falha ao cancelar boleto |
bank-slips.paid | Boleto pago |
bank-slips.reversed | Boleto estornado |
bank-slips.rejected | Boleto rejeitado |
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.
{
"payee": {
"taxId": "00000000000",
"number": "111111111",
"bankCode": "208",
"accountId": "0000000000-208-50-1111111",
"branchCode": "50"
},
"payer": {
"name": "Nome do pagador",
"taxId": "2222222222222"
},
"amount": 1,
"paidAt": "2024-03-23",
"status": "PAID",
"barCode": "111111111111111111111111111111",
"dueDate": "2024-04-01",
"pixInfo": {
"emv": "11111111111111111111111br.gov.bcb.pix1111api.developer.btgpactual.com/v1/p/v2/cobv/teste",
"key": "pixkey_teste",
"txId": "44444444444440"
},
"settledAt": "2024-03-23T20:08:38.783Z",
"amountPaid": 0.01,
"bankSlipId": "5555555555555b55555f55555",
"correlationId": "doc-teste",
"digitableLine": "555555555555dddddddfffff555555",
"paymentMethod": "BARCODE"
}
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"
}
Updated 15 days ago