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
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.
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-2070-4ce0-b496-9c5d36e91579",
"correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
"status": "UPDATED",
"barCode": "20893929900003927000050013606201261603478710",
"digitableLine": "20890050091360620126016034787107392990000392700",
"payee": {
"accountId": "44167119000129-208-50-003478711"
},
"payer": {
"name": "JUBIABA PARTICIPACOES LTDA",
"taxId": "1000000000000"
},
"amount": 3927,
"dueDate": "2023-04-10"
}
bank-slips.canceled
Boleto cancelado.
{
"bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
"correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
"status": "CANCELED",
"barCode": "20893929900003927000050013606201261603478710",
"digitableLine": "20890050091360620126016034787107392990000392700",
"payee": {
"accountId": "44167119000129-208-50-003478711"
},
"payer": {
"name": "JUBIABA PARTICIPACOES LTDA",
"taxId": "1000000000000"
},
"amount": 3927,
"dueDate": "2023-04-10"
}
bank-slips.cancel_failed
Falha ao cancelar boleto.
{
"bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
"correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
"status": "CANCEL_FAILED",
"barCode": "20893929900003927000050013606201261603478710",
"digitableLine": "20890050091360620126016034787107392990000392700",
"payee": {
"accountId": "44167119000129-208-50-003478711"
},
"payer": {
"name": "JUBIABA PARTICIPACOES LTDA",
"taxId": "1000000000000"
},
"amount": 3927,
"dueDate": "2023-04-10"
}
bank-slips.paid
Boleto pago.
{
"bankSlipId": "1bdd6d6b-2070-4ce0-b496-9c5d36e91579",
"correlationId": "rrt-1140542935249616503-a-gsa1-16666-27479025-277",
"status": "PAID",
"barCode": "20893929900003927000050013606201261603478710",
"digitableLine": "20890050091360620126016034787107392990000392700",
"payee": {
"accountId": "44167119000129-208-50-003478711"
},
"payer": {
"name": "JUBIABA PARTICIPACOES LTDA",
"taxId": "1000000000000"
},
"amount": 3927,
"dueDate": "2023-04-10"
}
bank-slips.failed
Falha ao criar boleto.
{
"eventId": "bank-slips.failed",
"metadataId": "46467854000183-208-50-004116558",
"tenantId": "46467854000183",
"message": {
"bankSlipId": "863532c6-ff68-4dac-8989-601e34bedc86",
"correlationId": "2385751161",
"status": "FAILED",
"barCode": "2089492810000012770005001000000001510000550",
"digitableLine": "20890050091000000001751041165500092810000012770",
"payee": {
"accountId": "46467854000183-208-50-004116558"
},
"payer": {
"name": "JUBIABA PARTICIPACOES LTDA",
"taxId": "00000000000000001"
},
"amount": 127.7,
"dueDate": "2023-03-06"
}
}
Updated 12 months ago