PluggyDocs

API de Gerenciamento de Boleto

Com nossa API de Gerenciamento de Boleto, você pode criar rapidamente um Boleto e receber notificações de pagamento para ele, permitindo automatizar todo o seu processo de cobrança.

Com nossa API de Gerenciamento de Boleto, você pode criar rapidamente um Boleto e receber notificações de pagamento para ele, permitindo automatizar todo o seu processo de cobrança aproveitando nossas integrações diretas com bancos.

Exponhamos uma única API uniforme para gerenciar Boletos, enquanto nos bastidores cuidamos de coisas como autenticação segura e os diferentes detalhes de integração com cada banco.

Recurso BETA

Este recurso está atualmente em BETA, com suporte para Inter Empresas. Estamos trabalhando na integração com muitos outros!

Introdução#

Para começar a usar esta API, primeiro precisamos criar uma Conexão de Boleto: um conjunto de credenciais que pode gerenciar boletos em uma Instituição.

Já resolvemos a questão de conectar contas bancárias com o conceito de Itens, que são usados para coleta de dados. Eles também podem ser usados para criar Conexões de Boleto (se suas configurações de permissão permitirem). Você também pode criar uma conexão de boleto enviando credenciais brutas.

Usando nossa Conexão de Boleto, podemos criar, obter e cancelar Boletos. Também podemos usar webhooks para ser notificado quando eles forem pagos ou expirados. Vamos ver os passos para fazer isso!

Começando (exemplo Inter)#

  1. Primeiro, crie um Item Pluggy conectando sua conta. Você pode fazer isso a partir do Dashboard -> qualquer aplicação -> Pré-visualização em Demo.

  2. Selecione Inter Empresas.

  3. No site da Inter Empresas, crie seu conjunto de credenciais de integração para fazer login. Certifique-se de habilitar as permissões de Boleto e Extrato.

  4. Copie o ID do Item criado.

  5. Obtenha uma chave de API do nosso endpoint Auth, usando as credenciais da sua aplicação do primeiro passo.

{
  "clientId": "{YOUR-CLIENT-ID}",
  "clientSecret": "{YOUR-CLIENT-SECRET}"
}
  1. Crie uma Conexão de Boleto a partir do Item, enviando seu ID:
{
  "itemId": "{YOUR-ITEM-ID}"
}
  1. Copie o ID da Conexão de Boleto da resposta:
{
  "id": "dc3537ad-13b4-4770-b248-e4578983899c",
  "connectorId": 225,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}
  1. Agora, crie um Boleto para essa Conexão de Boleto:
{
  "boletoConnectionId": "{YOUR-BOLETO-CONNECTION-ID}",
  "boleto": {
    "seuNumero": "1234567891",
    "amount": 2.5,
    "dueDate": "2025-03-01",
    "payer": {
      "taxNumber": "1234567890",
      "name": "Nome de exemplo",
      "addressState": "SP",
      "addressZipCode": "01239030",
      "addressCity": "Não informado",
      "addressStreet": "Não informado"
    }
  }
}
  1. Você receberá uma resposta como esta:
{
  "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
  "amount": 2.5,
  "status": "OPEN",
  "seuNumero": "1234567891",
  "dueDate": "2025-03-01",
  "payer": {
    "ddd": "",
    "name": "Nome de exemplo",
    "email": "",
    "taxNumber": "1234567890",
    "personType": "FISICA",
    "addressCity": "Não informado",
    "phoneNumber": "",
    "addressState": "SP",
    "addressNumber": "",
    "addressStreet": "Não informado",
    "addressZipCode": "01239030",
    "addressComplement": "",
    "addressNeighborhood": ""
  },
  "pixQr": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20",
  "digitableLine": "01120001161117012359902128847071234570777000110",
  "nossoNumero": "10000004701",
  "barcode": "01120001161117012359902128847071234570",
  "amountPaid": null,
  "paymentOrigin": null
}
  1. Tudo pronto! Agora você pode cancelar o Boleto com POST /boletos/{id}/cancel para limpar.

Notificações de pagamento#

Para receber uma notificação quando um Boleto for pago, configure o webhook boleto/updated, e você receberá um evento assim:

{
  "boletoId": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "boleto/updated"
}

Ao receber o evento, você pode fazer um GET /boleto/ para ver o Boleto atualizado. Quando ele for pago, o Boleto terá mudado o status para PAID, e os campos amountPaid e paymentOrigin estarão presentes:

{
  "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
  "amount": 2.5,
  "status": "PAID",
  "seuNumero": "1234567891",
  "dueDate": "2025-03-01",
  "payer": {
    "ddd": "",
    "name": "Nome de exemplo",
    "email": "",
    "taxNumber": "1234567890",
    "personType": "FISICA",
    "addressCity": "Não informado",
    "phoneNumber": "",
    "addressState": "SP",
    "addressNumber": "",
    "addressStreet": "Não informado",
    "addressZipCode": "01239030",
    "addressComplement": "",
    "addressNeighborhood": ""
  },
  "pixQr": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20",
  "digitableLine": "01120001161117012359902128847071234570777000110",
  "nossoNumero": "10000004701",
  "barcode": "01120001161117012359902128847071234570",
  "amountPaid": 2.5,
  "paymentOrigin": "PIX"
}