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:

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}'

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"
  ]
}

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.

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.

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.

{
  "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 --request GET \
     --url 'https://sandbox.belvo.com/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28' \
     --header 'accept: application/json'

## 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:

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.
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.
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.

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.
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.
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 --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 --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"
}

{
  "request_id": "3f58b8a6f025402f8de4a4cc55d38705"
}

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, por favor, 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, pode usar o cabeçalho async.