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.
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.
{
"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"
}
Updated 13 days ago