Introducción

Para mejorar el rendimiento y proporcionar un proceso más fluido, nuestra API admite flujos de trabajo y solicitudes asincrónicas. Nuestra funcionalidad asincrónica se puede dividir en:

• Flujo de trabajo asincrónico de datos históricos (para enlaces únicos)
  Elimina la necesidad de llamadas POST después de la creación del enlace para recuperar información básica sobre el enlace.
• Flujo de trabajo asincrónico de datos históricos (para enlaces recurrentes)
  Elimina la necesidad de llamadas POST después de la creación del enlace para recuperar información básica sobre el enlace y te permite recibir actualizaciones por cualquier cambio en la información.
• Llamadas POST asincrónicas en tiempo real (tanto para enlaces únicos como recurrentes)
  Elimina el riesgo de tiempos de espera y mejora el flujo de tus datos.

Flujo de trabajo asincrónico de datos históricos (enlaces únicos)

Ya sea que crees un enlace único a través de nuestra API o uses el widget para crear tus enlaces, puedes elegir recibir asincrónicamente la información histórica para tu usuario agregando el parámetro fetch_resources a tu solicitud:

curl --request POST \
     --url https://sandbox.belvo.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{see request body below}'

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

Una vez que se crea el enlace, Belvo recuperará todos los datos disponibles para los recursos que especificaste y te notificará a través de webhook una vez que la información esté lista para que la recuperes:

1. Registrar un enlace usando el Connect Widget
   Cuando generes tu access_token, asegúrate de pasar el parámetro fetch_resources. Una vez que tu usuario se conecte a su cuenta usando nuestro Connect Widget, Belvo responderá con el id del enlace y comenzará a cargar asincrónicamente los recursos que listaste en fetch_resources.
2. Espera los webhooks
   Tan pronto como recuperemos datos para cada recurso que listaste, recibirás un webhook historical_update para ese recurso. Por cada webhook que recibas, necesitas hacer una solicitud GET List a Belvo para obtener los datos.
   En el bloque de código a continuación, puedes ver un ejemplo del webhook que recibirás y la solicitud que necesitas enviar para recuperar los datos.
   {
     "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
     "webhook_type": "TRANSACTIONS",
     "webhook_code": "historical_update",
     "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // El enlace al que pertenecen los datos
     "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
     "external_id": "optional_parameter_you_can_provide",
     "data": {
       "total_transactions": 19, // Número total de transacciones encontradas
       "total_inflow_transactions": 10, // Número total de transacciones de entrada
       "total_outflow_transactions": 9, // Número total de transacciones de salida
       "first_transaction_date": "2017-01-03", // Fecha de la primera transacción
       "last_transaction_date": "2020-03-25" // Fecha de la última transacción
     }
   }

   curl --request GET \
        --url 'https://sandbox.belvo.com/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28' \
        --header 'accept: application/json'

Ya sea que crees un enlace recurrente a través de nuestra API o utilices el widget para crear tus enlaces, recibirás de manera asincrónica la información histórica de tu usuario, junto con actualizaciones regulares de cualquier cambio en la información del usuario.

Una vez que se crea el enlace, Belvo recuperará todos los datos disponibles para los recursos que hayas especificado y te notificará a través de webhook una vez que la información esté lista para que la recuperes:

1. Registrar un enlace usando el Connect Widget
   Una vez que tu usuario se conecta a su cuenta usando nuestro Connect Widget, Belvo responderá con el id del enlace y comenzará a cargar asincrónicamente los recursos principales para el tipo de enlace.
2. Esperar los webhooks (histórico)
   Tan pronto como recuperemos datos para cada recurso, recibirás un webhook historical_update para ese recurso. Por cada webhook que recibas, necesitas hacer una solicitud GET List a Belvo para obtener los datos.
   En el bloque de código a continuación, puedes ver un ejemplo del webhook que recibirás y la solicitud que necesitas enviar para recuperar los datos.
3. Esperar los webhooks (nuevo recurso disponible)
   Dependiendo de tu frecuencia de actualización, te enviaremos un webhook new_{resource}_updated, indicando que hemos recuperado nuevos datos para el enlace.

Llamadas POST asincrónicas en tiempo real (tanto enlaces únicos como recurrentes)

Al hacer que tus llamadas POST individuales sean asincrónicas, eliminas el riesgo de recibir errores de tiempo de espera y puedes diseñar tu agregación de información de una manera más esperada.

📘 Por el momento, nuestra llamada POST asincrónica en tiempo real se aplica a las siguientes solicitudes:

• 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 esta función en nuestros métodos POST restantes.

1. Registrar un enlace usando el Connect Widget
   Tu usuario se conecta a su cuenta usando nuestro Connect Widget. Después de que se hayan conectado exitosamente, recibirás un ID de Enlace que necesitarás usar para hacer más solicitudes sobre el usuario.
2. Enviar una solicitud POST con el nuevo encabezado async
   Haz una llamada POST usando X-Belvo-Request-Mode configurado en async.
   Recibirás una respuesta 202 - Accepted con un request_id en el cuerpo. Recomendamos que almacenes este request_id para que más tarde, cuando recibas un webhook, sepas a qué solicitud responde el webhook.
3. Esperar el webhook
   Tan pronto como hagas tu solicitud POST, Belvo comenzará a recuperar datos sobre el usuario. Enviamos un webhook una vez que se ha recuperado toda la información solicitada. Cuando recibas el webhook, puedes hacer una solicitud GET al endpoint apropiado para recuperar la información.

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

Activar manualmente una actualización histórica

También puedes activar manualmente una actualización histórica asincrónica para los datos de un enlace utilizando nuestro método Activar una actualización histórica para un enlace.

El flujo es muy similar a cuando creas un enlace por primera vez:

1. Haces una solicitud POST al endpoint.
2. Belvo devuelve una respuesta 202 Accepted con un request_id.
3. Cuando los datos están listos, Belvo envía un webhook historical_update.
4. Luego puedes hacer una solicitud GET para recuperar los datos actualizados.

Mejores Prácticas

¿Necesito configurar una URL de webhook incluso para enlaces individuales?**

Sí, necesitarás tener webhooks configurados para utilizar nuestra funcionalidad asincrónica.

¿Necesito responder al webhook cuando lo reciba?

Sí, una vez que recibas un webhook, envía un 202 - Accepted webhook a Belvo dentro de cinco segundos para confirmar que has recibido el webhook. De lo contrario, nuestra API volverá a intentar la solicitud.

Si ves algún problema con el JSON, responde a Belvo con un 400 Bad Request, incluyendo el ID de la solicitud.

¿Puedo usar solicitudes POST asíncronas para cualquier tipo de enlace?

¡Sí! Ya sea que el enlace sea único o recurrente, siempre que realices una llamada POST puedes usar el encabezado async.