# 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: 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 '{see request body below}' ``` ```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 '{see request body below}' ``` ```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" ] } ``` 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: Para más detalles sobre qué recursos puedes enviar, consulta nuestra referencia de API Registrar una nueva solicitud de enlace. 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. ```json { "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 curl --request GET \ --url 'https://sandbox.belvo.com/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28' \ --header 'accept: application/json' ``` br ## Flujo de trabajo asincrónico de datos históricos (enlaces recurrentes) 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: br 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 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" } ``` ## Activar manualmente una **actualización** histórica En Beta El método **Activar una actualización histórica para un enlace** está actualmente en Beta Abierta para que todos los clientes lo utilicen. Te animamos a probarlo y proporcionar comentarios. 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. Periodo de Enfriamiento Para prevenir solicitudes duplicadas, el endpoint **Actualizar datos históricos para un enlace** tiene un periodo de enfriamiento de 10 minutos para cada enlace. Si haces una solicitud para el mismo enlace dentro de este periodo, recibirás un error sincrónico `409 Conflict`. ## 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`.