--- updatedAt: 2026-02-12T17:42:36.000Z agentTools: projectIndex: https://docs.bankly.com.br/llms.txt --- # Consulta de eventos stable Este *endpoint* permite realizar a consulta de eventos de uma conta específica. > 🚧 Importante > > A consulta de eventos retorna no máximo **10.000 eventos** por vez. Quando é gerado um novo evento, para que este seja retornado na consulta, o mais antigo é excluído. Portanto, recomendamos **salvar o retorno** da última consulta realizada no fim do dia em uma base de dados própria, para que o conteúdo não se perca com a atualização dos eventos. ## Requisição (Request) ### Requisição HTTP ```http GET 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}}}&eventName={{eventName}} ``` ```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}}}&eventName={{eventName}}'\ --header 'Accept: application/json'\ --header 'api-version: 1.0'\ --header 'authorization: Bearer {{Token}}' \ --header 'x-correlation-id: {{Guid}}' ``` ### Autorização Para garantir a segurança nas requisições, todos os *endpoints* do Bankly utilizam *[scopes](https://docs.bankly.com.br/docs/scopes)* como parte do seu [fluxo de autorização](https://docs.bankly.com.br/docs/fluxos-autorizacao).\ Esta requisição requer o *scope* descrito a seguir: | Scope | Descrição | | ------------- | -------------------------------------------------------------- | | `events.read` | Concede acesso para consultar eventos de uma conta específica. | ### Cabeçalhos (Headers) | Nome | Descrição | | ------------------ | ----------------------------------------------------------------- | | `api-version` | **Obrigatório**. Versão da API. Atualmente estamos na versão 1.0. | | `Authorization` | **Obrigatório**. Token de autorização do tipo Bearer. | | `x-correlation-id` | **Obrigatório**. Informe um GUID, sendo um novo cada requisição. | ### Parâmetros da rota (Path) No *path* desta requisição envie as seguintes *queries*: | **Nome** | **Tipo** | **Descrição** | **Especificação** | | ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `branch` | `string` | **Obrigatório**. Número da agência. | — | | `account` | `string` | **Obrigatório**. Número da conta. | — | | `page` | `string` | Número da página que deseja visualizar. | — | | `pageSize` | `string` | Número de eventos por página que a consulta deve retornar. | Máximo de 100 itens. | | `includeDetails` | `boolean` | Insira o valor **true** para obter o objeto `data` no corpo da resposta, com os detalhes do evento. | — | | `beginDateTime` | `string` | Data e hora de início dos eventos que deseja consultar. Utilize esse campo em conjunto com o `endDateTime` para filtrar eventos por um range de datas. | Formato AAAA-MM-DD ou ISO 8601 - UTC. | | `endDateTime` | `string` | Data e hora final dos eventos que deseja consultar. | Formato AAAA-MM-DD ou ISO 8601 - UTC. | | `cardProxy` | `array of strings` | Proxy (código identificador com 19 dígitos, gerado na solicitação de emissão de cartões) para pesquisar eventos de cartão. **Observação**: em *sandbox* a consulta por proxy não retornará eventos, visto que nesse ambiente não ocorrem movimentações reais com cartão. | — | | `eventName` | `array of strings` | Nome do evento (ou eventos) sobre o qual se deseja obter informações. | Confira os possíveis nomes na documentação [Eventos](https://docs.bankly.com.br/docs/eventos-events). | > 🚧 Importante > > Caso os parâmetros `beginDateTime` e `endDateTime` não sejam informados, o retorno exibirá o intervalo padrão que se refere aos últimos 30 dias e será considerado o fuso horário UTC -3 (Horário de Brasília). ### Corpo da requisição (Body) Não é necessário enviar campos no *body* desta requisição. ## Resposta (Response) O *status code* 200 indicará que a solicitação foi aceita com sucesso e trará uma lista de eventos e suas informações em formato JSON. ```json PIX_CASH_IN_ACCOUNT [ { "aggregateId": "PIX_TRANSACTION_ID_96000a91-75aa-4989-935f-e94de7608fe4", "type": "TRANSACTION", "category": "EletronicTransfers", "documentNumber": "47742663023", "bankBranch": "0001", "bankAccount": "15164", "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": "15164", "Document": "47742663023", "IspbNumber": "13140088", "Name": "Nísia Floresta" }, "RecipientAccount": { "Agency": "0001", "Account": "540108", "Document": "09992220074", "IspbNumber": "13140088", "Name": "Maria Quitéria de Jesus" }, "IsPixDeposit": true, "CorrelationId": null, "Document": "47742663023", "CompanyKey": "SDB2_BANKLYDELIVERY", "EventDateTime": "2021-10-25T14:36:00.039+00:00" }, "status": "ACTIVE" } ] ``` ```json PIX_CASH_OUT_ACCOUNT { "aggregateId": "PIX_TRANSACTION_ID_316d8a01-0330-5bf0-a695-62b9e5dd5d61", "type": "TRANSACTION", "category": "EletronicTransfers", "description": "teste evento", "documentNumber": "21828625442", "bankBranch": "0001", "bankAccount": "1104609891", "amount": -1.55, "index": "cash-out", "name": "PIX_CASH_OUT_ACCOUNT", "timestamp": "2026-02-12T13:53:45.5070934Z", "data": { "AuthenticationCode": "316d8a01-0330-5bf0-a695-62b9e5dd5d61", "EndToEndId": "E131400882026021213532F8EE35779F", "TransactionDate": "2026-02-12T13:53:45.5070934Z", "InitializationType": "Automatic", "AddressKey": null, "AddressKeyType": "", "Description": "teste evento", "Channel": "INTERNAL", "Amount": -1.55, "Recipient": { "Document": "44838136927", "DocumentType": "CPF", "Name": "Timmy Herzog", "BankBranch": "0001", "BankAccount": "1101508946", "BankAccountType": "CHECKING", "BankIspb": "13140088", "BankName": "Acesso Soluções De Pagamento S.A. - Instituição De Pagamento", "BankCompe": "332" }, "ScheduledPaymentDate": null, "AmountDetails": [], "WithdrawalProviderIspb": null, "WithdrawalAgentType": null }, "status": "ACTIVE" } ``` > 🚧 Importante > > Conheça o detalhamento dos campos retornados consultando a documentação de cada evento específico. > 👍 Dica > > Para simular uma requisição nesse *endpoint*, acesse o [API Reference](https://docs.bankly.com.br/reference/events). ## Erros Este *endpoint* pode retornar erros específicos, conforme a tabela a seguir: | Status Code | Código | Mensagem | Descrição | | ----------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | | 400 | 404 | ‘\{parâmetro}’ must not be empty. | Esse erro se refere à obrigatoriedade do envio de valores nos campos `branch` e `account`. | | 400 | 404 | ‘\{parâmetro}’ must be greater than '\{valor}'. | Esse indica que os valores dos campos `page` e `pageSize` devem ser maiores que zero. | | 404 | 404 | Account does not belong to this company. | A conta informada não pertence a esse parceiro. | | 404 | 404 | Account not find. | A conta informada não foi encontrada. | Recordamos que esta API também poderá retornar erros comuns entre todos os *endpoints*. Portanto, recomendamos a consulta da documentação de [erros](https://docs.bankly.com.br/docs/erros), onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).