# 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 utilices el widget para crear tus enlaces, puedes optar por recibir de manera asincrónica la información histórica de 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 el enlace se crea, Belvo recuperará todos los datos disponibles para los recursos que especificaste y te notificará a través de un 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. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a single Link using the widget Note over App,Belvo: fetch_resources = [OWNERS, ACCOUNTS, TRANSACTIONS] Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (OWNERS) App->>Belvo: GET /owners/?link={link.id} Belvo-->>App: 200 + Owner Details Belvo-->>App: WEBHOOK historical_update (ACCOUNTS) App->>Belvo: GET /accounts/?link={link.id} Belvo-->>App: 200 + Account Details Belvo-->>App: WEBHOOK historical_update (TRANSACTIONS) App->>Belvo: GET /transactions/?link={link.id} Belvo-->>App: 200 + Transaction Details ``` 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 sobre cualquier cambio en la información del usuario. Una vez que el enlace se crea, Belvo recuperará todos los datos disponibles para los recursos que hayas especificado y te notificará a través de un webhook una vez que la información esté lista para que la recuperes: ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a recurrent Link using the widget Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (per resource) App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details Note over App,Inst: At your scheduled Link update frequency, Belvo checks for new information for each link per resource Belvo-->>App: WEBHOOK new_{resource}_available App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details ``` 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óricos)** 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 para enlaces individuales 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 predecible. > 📘 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. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution rect rgba(0, 100, 255, .05) Note over App,Inst: Link creation App->>Belvo: Create a Recurrent Link using the Widget Belvo->>Inst: Connect Belvo-->>App: 201 OK + Link ID end rect rgba(0, 200, 100, .05) Note over App,Inst: Async transactions request App->>Belvo: POST /transactions/{Link ID, date from, date to}/ Note over App,Belvo: X-Belvo-Request-Mode: async Belvo-->>App: 202 Accepted Note over App,Belvo: request_id Belvo->>Inst: Retrieve transaction information for the period indicated Belvo-->>App: new_transactions_available webhook App->>Belvo: GET /transactions/{link_id}/ end ``` 1. **Registrar un enlace usando el Connect Widget** Tu usuario se conecta a su cuenta usando nuestro Connect Widget. Después de que se haya conectado exitosamente, recibirás un Link ID que necesitarás usar para hacer solicitudes adicionales sobre el usuario. 2. **Enviar una solicitud POST con el nuevo encabezado `async`** Realiza una llamada POST usando `X-Belvo-Request-Mode` configurado como `async`. Recibirás una respuesta `202 - Accepted` con un `request_id` en el cuerpo. Recomendamos almacenar este `request_id` para que, cuando recibas un webhook, sepas a qué solicitud responde el webhook. 3. **Esperar el webhook** Tan pronto como realices 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 correspondiente 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`.