# Introdução Para melhorar o desempenho e proporcionar um processo mais suave, nossa API suporta fluxos de trabalho e solicitações assíncronas. Nossa funcionalidade assíncrona pode ser dividida em: - **Fluxo de trabalho assíncrono de dados históricos (para links únicos)** Elimina a necessidade de chamadas POST após a criação do link para recuperar informações principais sobre o link. - **Fluxo de trabalho assíncrono de dados históricos (para links recorrentes)** Elimina a necessidade de chamadas POST após a criação do link para recuperar informações principais sobre o link e permite que você receba atualizações para quaisquer alterações nas informações. - **Chamadas POST assíncronas em tempo real (tanto para links únicos quanto recorrentes)** Elimina o risco de timeouts e melhora o fluxo de dados. ## Fluxo de dados históricos assíncronos (links únicos) Seja criando um link único via nossa API ou usando o widget para criar seus links, você pode optar por receber assincronamente as informações históricas para seu usuário adicionando o parâmetro `fetch_resources` à sua solicitação: Widget ```shell Generate Widget Token URL curl --request POST \ --url https://sandbox.belvo.com/api/token/ \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{veja o corpo da solicitação abaixo}' ``` ```json Widget Token Request Body { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "external_id": "asynchronous-historical-request", "scopes": "read_institutions,write_links", "fetch_historical": true, "fetch_resources": [ "FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETURNS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS", "TAX_RETENTIONS" ] } ``` API ```shell Create Link URL curl --request POST \ --url https://sandbox.belvo.com/api/links/ \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{veja o corpo da solicitação abaixo}' ``` ```json Link Request Body { "institution": "erebor_mx_retail", "username": "bnk100", "password": "full", "external_id": "asynchronous-historical-request", "access_mode": "single", "fetch_resources": [ "ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS" ] } ``` Uma vez que o link é criado, a Belvo irá recuperar todos os dados disponíveis para os recursos que você especificou e notificá-lo via webhook assim que a informação estiver pronta para você recuperar: Para mais detalhes sobre quais recursos você pode enviar, veja nossa referência de API Registrar uma nova solicitação de link. 1. **Registrar um link usando o Connect Widget** Quando você gerar seu access_token, certifique-se de passar o parâmetro `fetch_resources`. Assim que seu usuário se conectar à sua conta usando nosso Connect Widget, a Belvo responderá com o `id` do link e começará a carregar assincronamente os recursos que você listou em `fetch_resources`. 2. **Aguarde pelos webhooks** Assim que recuperarmos os dados para cada recurso que você listou, você receberá um webhook `historical_update` para esse recurso. Para cada webhook que você receber, você precisará fazer uma solicitação GET List para a Belvo para obter os dados. No bloco de código abaixo, você pode ver um exemplo do webhook que você receberá e a solicitação que você precisa enviar para recuperar os dados. ```json { "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999", "webhook_type": "TRANSACTIONS", "webhook_code": "historical_update", "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // O link ao qual os dados pertencem "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6", "external_id": "optional_parameter_you_can_provide", "data": { "total_transactions": 19, // Número total de transações encontradas "total_inflow_transactions": 10, // Número total de transações de entrada "total_outflow_transactions": 9, // Número total de transações de saída "first_transaction_date": "2017-01-03", // Data da primeira transação "last_transaction_date": "2020-03-25" // Data da última transação } } ``` ```curl curl --request GET \ --url 'https://sandbox.belvo.com/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28' \ --header 'accept: application/json' ``` br ## Fluxo de dados históricos assíncronos (links recorrentes) Seja criando um link recorrente via nossa API ou usando o widget para criar seus links, você receberá de forma assíncrona as informações históricas para seu usuário, juntamente com atualizações regulares sobre quaisquer alterações nas informações do usuário. Uma vez que o link é criado, a Belvo recuperará todos os dados disponíveis para os recursos que você especificou e notificará você via webhook assim que a informação estiver pronta para ser recuperada: br 1. **Registrar um link usando o Connect Widget** Assim que seu usuário se conecta à sua conta usando nosso Connect Widget, a Belvo responderá com o `id` do link e começará a carregar assíncronamente os recursos principais para o tipo de link. 2. **Aguardar por webhooks (histórico)** Assim que recuperarmos dados para cada recurso, você receberá um webhook `historical_update` para esse recurso. Para cada webhook que você receber, você precisa fazer uma solicitação GET List para a Belvo para obter os dados. No bloco de código abaixo, você pode ver um exemplo do webhook que você receberá e a solicitação que precisa enviar para recuperar os dados. 3. **Aguardar por webhooks (novo recurso disponível)** Dependendo da sua frequência de atualização, enviaremos um webhook `new_{resource}_updated`, indicando que recuperamos novos dados para o link. ## Chamadas POST assíncronas em tempo real (tanto para links únicos quanto recorrentes) Ao tornar suas chamadas POST individuais assíncronas, você elimina o risco de receber erros de timeout e pode projetar sua agregação de informações de uma maneira mais esperada. > 📘 No momento, nossa chamada POST assíncrona em tempo real se aplica às seguintes solicitações: - POST Retrieve Transactions - POST Retrieve Invoices - POST Retrieve Employments in Brazil - POST Retrieve Employment Records in Mexico - POST Retrieve Financial Statements in Mexico Estamos implementando continuamente esse recurso em nossos métodos POST restantes. 1. **Registre um link usando o Connect Widget** Seu usuário se conecta à sua conta usando nosso Connect Widget. Após a conexão bem-sucedida, você receberá um Link ID que precisará usar para fazer solicitações adicionais sobre o usuário. 2. **Envie uma solicitação POST com o novo cabeçalho `async`** Faça uma chamada POST usando `X-Belvo-Request-Mode` definido como `async`. Você receberá uma resposta `202 - Accepted` com um `request_id` no corpo. Recomendamos que você armazene esse `request_id` para que, quando receber um webhook, saiba a qual solicitação o webhook está respondendo. 3. **Aguarde o webhook** Assim que você fizer sua solicitação POST, a Belvo começará a recuperar dados sobre o usuário. Enviamos um webhook assim que todas as informações solicitadas forem recuperadas. Quando você receber o webhook, poderá fazer uma solicitação GET para o endpoint apropriado para recuperar as informações. ```curl curl --location --request POST 'https://sandbox.belvo.com/api/transactions/' \ --header 'X-Belvo-Request-Mode: async' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "link": "bcca0da9-a4c6-4830-9676-1d54682851d9", "date_from": "2022-12-17", "date_to": "2023-01-16" } ``` ```curl curl --location --request POST 'https://sandbox.belvo.com/api/invoices/' \ --header 'X-Belvo-Request-Mode: async' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "link": "bcca0da9-a4c6-4830-9676-1d54682851d9", "date_from": "2022-12-17", "date_to": "2023-01-16", "type": "OUTFLOW" } ``` ```json { "request_id": "3f58b8a6f025402f8de4a4cc55d38705" } ``` ## Acionando manualmente uma **atualização** histórica Em Beta O método **Acionar uma atualização histórica para um link** está atualmente em Beta Aberto para todos os clientes usarem. Incentivamos você a experimentá-lo e fornecer feedback. Você também pode acionar manualmente uma atualização histórica assíncrona para os dados de um link usando nosso método Acionar uma atualização histórica para um link. O fluxo é muito semelhante ao de quando você cria um link pela primeira vez: 1. Você faz uma solicitação `POST` para o endpoint. 2. A Belvo retorna uma resposta `202 Accepted` com um `request_id`. 3. Quando os dados estiverem prontos, a Belvo envia um webhook `historical_update`. 4. Você pode então fazer uma solicitação `GET` para recuperar os dados atualizados. Período de Resfriamento Para evitar solicitações duplicadas, o endpoint **Atualizar dados históricos para um link** tem um período de resfriamento de 10 minutos para cada link. Se você fizer uma solicitação para o mesmo link dentro deste período, receberá um erro síncrono `409 Conflict`. ## Melhores Práticas #### Preciso configurar uma URL de webhook mesmo para links únicos?** Sim, você precisará ter webhooks configurados para utilizar nossa funcionalidade assíncrona. #### Preciso responder ao webhook quando o receber? Sim, assim que você receber um webhook, envie um `202 - Accepted webhook` para a Belvo dentro de cinco segundos para confirmar que você recebeu o webhook. Caso contrário, nossa API tentará novamente a solicitação. Se você encontrar algum problema com o JSON, responda à Belvo com um `400 Bad Request`, incluindo o ID da solicitação. #### Posso usar requisições POST assíncronas para qualquer tipo de link? Sim! Seja o link único ou recorrente, sempre que você fizer uma chamada POST, você pode usar o cabeçalho `async`.