API de consulta de eventos

Um evento é um conjunto de informações sobre uma determinada ação executada em nossas APIs, relacionada a uma conta específica.

Os eventos trazem dados mais detalhados sobre uma transação do que o seu comprovante. Quando realizamos uma transferência externa, por exemplo, o comprovante se limitará a exibir informações sobre os valores e o tipo da transação realizada (para conciliação e contabilização).

Portanto, para que o parceiro possa obter mais detalhes sobre uma transação, além do registro financeiro realizado pelo comprovante, é gerado um evento no qual se adicionam metadados referentes à operação ocorrida, como a conta destinatária, dados da conta remetente etc.

Para que sua aplicação também possa consumir esses dados armazenados, disponibilizamos o endpoint de consulta /events.

Etapas

Endpoint

Para consumo do endpoint de eventos, no path da requisição, é obrigatório informar os dados da conta da qual se deseja obter os eventos:

• branch: número da agência;
• account: número da conta.

🚧

Importante

No header da requisição, é obrigatório informar o campo x-correlation-id com um Guid.

Opcionalmente, para detalhar a pesquisa, insira no path as seguintes informações:

• page: indique o número da página que deseja visualizar;
• pageSize: especifique o número de eventos por páginas (máximo de 100 itens);
• includeDetails: inclua esse campo com o valor true para obter o objeto data no corpo da resposta, com os detalhes do evento;
• beginDateTime: insira a data de início dos eventos que deseja consultar no formato AAAA-MM-DD. Utilize esse campo em conjunto com o endDateTime para filtrar eventos por um range de datas;
• endDateTime: insira a data final dos eventos que deseja consultar (formato AAAA-MM-DD);
• cardProxy: informe o proxy (código identificador com 19 dígitos, gerado na solicitação de emissão de cartões) para pesquisar eventos de cartão;
• eventName: nome do evento do qual deseja obter informações. Suas possibilidades de preenchimento são:

📘

Nota

A consulta de eventos retorna no máximo 10.000 eventos por vez. Recomendamos salvar o retorno da última consulta realizada no fim do dia para que não seja necessário consultar todo o conteúdo novamente a cada pesquisa.

cURL  
--request GET  
--url 'https://api-mtls.sandbox.bankly.com.br/events?branch={{branchNumber}}&account={{accountNumber}}&page={{pageNumber}}&pageSize={{eventsPerPage}}&includeDetails={{true}}&beginDateTime={{AAAA-MM-DD}}&endDateTime={{AAAA-MM-DD}}&cardProxy={{proxyNumber}}'\ 
--header 'Accept: application/json'\
--header 'api-version: 1.0'\
--header 'x-correlation-id: {{Guid}}'

Retorno

O status ACTIVE indicará que o cash-out está em processamento ou foi realizado com sucesso. Caso contrário, o status estará como CANCELED.

{
   "aggregateId": "PIX_TRANSACTION_ID_96000a91-75aa-4989-935f-e94de7608fe4",
   "type": "TRANSACTION",
   "category": "EletronicTransfers",
   "documentNumber": "12345678901",
   "bankBranch": "0001",
   "bankAccount": "111568",
   "amount": 1,
   "index": "cash-in",
   "name": "PIX_CASH_IN_ACCOUNT",
   "timestamp": "2021-10-25T14:36:00+00:00",
   "data": {
      "TotalRefundedAmount": 1,
      "DepositTransactionId": "96000a91-75aa-4989-935f-e94de7608fe4",
      "ControlNumber": null,
      "TransactionAmount": 1,
      "ClearingAmount": 1,
      "OverLimitAmount": 0,
      "AddressKey": null,
      "Description": "DESCRIÇÃO",
      "Channel": "INTERNAL_SPI",
      "EndToEndId": null,
      "PixTransactionId": "00000000-0000-0000-0000-000000000000",
      "SenderAccount": {
         "Agency": "0001",
         "Account": "111470",
         "Document": "12345678902",
         "IspbNumber": "13140088",
         "Name": "Peter Parker"
      },
      "RecipientAccount": {
         "Agency": "0001",
         "Account": "219568",
         "Document": "12345678900",
         "IspbNumber": "13140088",
         "Name": "Carol Denvers"
      },
      "IsPixDeposit": true,
      "CorrelationId": null,
      "Document": "36436846816",
      "CompanyKey": "SDB2_BANKLYDELIVERY",
      "EventDateTime": "2021-10-25T14:36:00.039+00:00"
   },
   "status": "ACTIVE"
}

📘

Nota

O campo name retornará o nome do documento de cadastro, e não o nome social.