# Extraer Datos Bancarios en Brasil (Widget)
En esta guía, te guiamos a través de todo lo que necesitas para extraer datos bancarios sobre tus usuarios de la Red de Finanzas Abiertas de Brasil utilizando nuestra API. Esto incluye:
- Una visión general del flujo de datos.
- Configurar el Hosted Widget de Belvo para conectar a tus usuarios.
- Obtener los datos de tus usuarios basados en eventos de webhook enviados por Belvo.
- Proporcionar a tus usuarios una forma de gestionar sus consentimientos.
## Requisitos previos
Antes de proceder con tu integración, asegúrate de haber revisado nuestra guía de inicio. En la guía de inicio, crearás una cuenta de Belvo, generarás algunas claves de API de sandbox y configurarás una URL de webhook. Para propósitos de prueba y desarrollo de tu integración, recomendamos encarecidamente usar el entorno de Sandbox siempre que sea posible.
Además, para propósitos de prueba y desarrollo de tu integración, recomendamos encarecidamente usar el entorno Sandbox junto con la institución Mockbank. Puedes encontrar credenciales de ejemplo para simular diferentes usuarios para la institución Mockbank aquí.
## Descripción general del flujo de datos
Belvo utiliza un *flujo de trabajo asincrónico* para mejorar la extracción de datos y el flujo de integración. Como puedes ver en el diagrama a continuación, una vez que tu usuario ha conectado su cuenta usando el Hosted Widget y el enlace se ha creado, Belvo carga todos los datos de manera asincrónica y luego te notifica usando webhooks que los datos están disponibles para que los recuperes.
```mermaid
sequenceDiagram
participant Application
participant Belvo
participant Institution
Application->>Belvo: Crear un Link usando el widget
Belvo->>Institution: Conectar y confirmar consentimiento con la institución
Belvo-->>Application: 201 - Creado
Institution-->>Belvo: Belvo recupera información histórica para el ID del link.
Note over Application,Belvo: OWNERS
Belvo->>Application: WEBHOOK historical_update (OWNERS)
Application->>Belvo: GET /owners/?link={link.id}
Belvo-->>Application: 200 + Detalles del Propietario
Note over Application,Belvo: ACCOUNTS
Belvo->>Application: WEBHOOK historical_update (ACCOUNTS)
Application->>Belvo: GET /accounts/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Cuenta
Note over Application,Belvo: TRANSACTIONS
Belvo->>Application: WEBHOOK historical_update (TRANSACTIONS)
Application->>Belvo: GET /transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Transacción
Note over Application,Belvo: BILLS
Belvo->>Application: WEBHOOK historical_update (BILLS)
Application->>Belvo: GET /bills/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Factura
Note over Application,Belvo: INVESTMENTS
Belvo->>Application: WEBHOOK historical_update (INVESTMENTS)
Application->>Belvo: GET /br/investments/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Inversión
Note over Application,Belvo: INVESTMENT TRANSACTIONS
Belvo->>Application: WEBHOOK historical_update (INVESTMENT_TRANSACTIONS)
Application->>Belvo: GET /br/investment-transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de las Transacciones de Inversión
```
## Configuración del Hosted Widget
El Hosted Widget de Belvo está diseñado para simplificar tu proceso de desarrollo e integración, cumplir con las regulaciones de Open Finance, y es constantemente monitoreado por un equipo de especialistas para mejorar la experiencia del usuario.
Nuestro Hosted Widget puede ser incrustado en tu aplicación como un *webview* y guiará a tu usuario a través de todos los pasos para otorgar su consentimiento para que accedas a sus datos. Esto incluye redirigir al usuario a su institución para proporcionar el consentimiento y luego de regreso a tu aplicación. Puedes ver un flujo simplificado de lo que sucede durante el proceso de conexión del widget en el diagrama a continuación:
```mermaid
sequenceDiagram
autonumber
participant Application
participant Belvo
participant User
participant Institution
Application->>Belvo: Generar un access_token usando el CPF o CNPJ del usuario
Belvo-->>Application: 200 + access_token
Application->>User: Mostrar el widget a tu usuario
https://widget.belvo.io/?access_token=access...
User->>Institution: Tu usuario es redirigido a su institución
Institution->>Belvo: Una vez que otorgan su consentimiento,
son momentáneamente redirigidos a una pantalla segura en el navegador
Belvo->>Application: Usuario redirigido a tu aplicación
para finalizar el flujo
Application-->>Belvo: Usuario completó el flujo (éxito)
Belvo-->>Application: Recibes el ID del link para el usuario
```
Básicamente, cada vez que quieras que tu usuario conecte su cuenta de una institución financiera en Brasil, necesitarás:
### Generar un token de `access` para el widget
Para poder iniciar el widget, primero necesitarás generar un token de `access` usando el siguiente payload:
Individual (CPF)
```shell Sandbox Request URL
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-d 'ver ejemplo de payload abajo'
```
```json Widget Access Token (Individual - OFDA)
{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "300d",
"fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your-url-here://success",
"exit": "your-url-here://exit",
"event": "your-url-here://error"
},
"consent": {
"terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
"permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
}
]
},
"branding": {
"company_icon": "https://mysite.com/icon.svg",
"company_logo": "https://mysite.com/logo.svg",
"company_name": "ACME",
"company_terms_url": "https://belvo.com/terms-service/",
"overlay_background_color": "#F0F2F4",
"social_proof": true
},
"theme": []
}
}
```
Company (CNPJ)
```shell Sandbox Request URL
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-d 'ver ejemplo de payload abajo'
```
```json Widget Access Token (Company - OFDA)
{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "300d",
"fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your-url-here://success",
"exit": "your-url-here://exit",
"event": "your-url-here://error"
},
"consent": {
"terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
"permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
"identification_info": [
{
"type": "CPF",
"number": "76109277673",
"name": "Ralph Bragg"
},
{
"type": "CNPJ",
"number": "50685362006773",
"name": "Bragg Mechanics"
}
]
},
"branding": {
"company_icon": "https://mysite.com/icon.svg",
"company_logo": "https://mysite.com/logo.svg",
"company_name": "ACME",
"company_terms_url": "https://belvo.com/terms-service/",
"overlay_background_color": "#F0F2F4",
"social_proof": true
},
"theme": []
}
}
```
| Parámetro | Requerido | Descripción |
| --- | --- | --- |
| `id` | true | Reemplaza `YOUR_SECRET_ID` con el ID secreto que generaste en el panel de Belvo. |
| `password` | true | Reemplaza `YOUR_SECRET_PASSWORD` con la contraseña secreta que generaste en el panel de Belvo. |
| `scopes` | true | El parámetro `scopes` contiene una lista de permisos que te permiten crear un enlace para el usuario. Este es un parámetro requerido y debe enviarse exactamente como se muestra. |
| `stale_in` | false | El parámetro `stale_in` te permite controlar por cuánto tiempo Belvo almacena los datos derivados del usuario. Para más información, consulta la sección stale_in de nuestro artículo sobre controles de retención de datos. |
| `fetch_resources` | true | En el parámetro `fetch_resources`, proporcionas una lista de recursos que deseas que Belvo recupere de manera asincrónica para el usuario. Para OFDA, recomendamos: `["ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"]`. |
| `widget.purpose` | true | En el parámetro `purpose`, puedes personalizar el mensaje que se muestra a tu usuario sobre para qué caso de uso estás solicitando sus datos. Para más información, consulta la sección purpose en nuestra guía de Hosted Widget (OFDA). |
| `widget.openfinance_feature` | true | El parámetro `openfinance_feature` indica que el usuario final pasará por el flujo de OFDA. Debe establecerse en `consent_link_creation`. |
| `widget.callback_urls`
| true
| En el objeto `callback_urls`, **debes** agregar enlaces a donde tu usuario debe ser redirigido en los siguientes casos:
- success (tu usuario conectó exitosamente sus cuentas)
- exit (tu usuario salió del widget antes de completar el proceso)
- event (ocurrió un error durante el proceso de conexión).
Para más información, consulta la sección callback_urls en nuestra guía de Hosted Widget (OFDA). Belvo enviará información adicional basada en el evento. Para más información, asegúrate de consultar la sección Handling callback events de la guía de Hosted Widget (OFDA).
|
| `widget.consent` | true | El objeto `consent` es único para el widget OFDA y debe proporcionarse.- En el parámetro `terms_and_conditions_url`, **debes** proporcionar un enlace a los términos y condiciones de tu empresa.
- En el parámetro `permissions`, debes pasar el siguiente array de permisos: `["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"]`.
- En el array `identification_info`, necesitas proporcionar la información de identificación del usuario para el que deseas recuperar información. La información que proporciones aquí debe coincidir con la información que la institución regulada tiene para el usuario (por ejemplo, para empresas, el CPF y el nombre deben ser de un usuario con acceso a la cuenta de la empresa). Para individuos, solo necesitas proporcionar el CPF y el nombre. Para empresas, necesitas proporcionar tanto la información de CPF como de CNPJ. Para más información, consulta la sección identification_info de nuestra guía de Hosted Widget (OFDA).
|
| `widget.branding`
| true
| En el objeto `branding`, **debes** agregar tu:
- company_icon
- company_logo
- company_name
- company_terms_url.
También puedes opcionalmente agregar un color de fondo personalizado para cuando el widget se abra, así como desactivar el mensaje de Belvo sobre cuántas cuentas se han conectado. Para más información sobre las opciones de personalización y branding del widget, consulta nuestra guía dedicada.
|
| `widget.theme` | false | Puedes opcionalmente agregar los colores de tu marca al widget usando el parámetro `theme`. Para más información sobre dónde aparecerán estos colores en el widget, consulta la sección dedicada Add custom colors to the widget de nuestra guía de Branding. |
Además, consulta nuestra sección Generating an access token de nuestra guía de Hosted Widget (OFDA).
```json Access Token Response Example
{
"refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
"access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..." // [!code highlight]
}
```
### Iniciar el widget dentro de una vista web
A continuación, necesitarás redirigir a tu usuario al widget en una vista web dentro de tu aplicación:
```shell Hosted Widget URL
https://widget.belvo.io/
?access_token={access}
&mode=webapp
&locale=pt
&access_mode=single
&external_id=HJLSI-897809
```
| Parámetro | Requerido | Descripción |
| --- | --- | --- |
| `access_token` | si | Reemplaza `access` con el token de acceso que recibiste. |
| `mode` | si | Para que el OFDA Hosted Widget funcione correctamente para tus usuarios, debes establecer el parámetro de consulta mode en `webapp`. |
| `locale` | si | Para que el OFDA Hosted Widget funcione correctamente para tus usuarios, debes establecer el parámetro de consulta locale en `pt`. |
| `access_mode` | no | Puedes usar el parámetro `access_mode` para definir qué tipo de enlace deseas crear (`single` o `recurrent`). Por defecto, Belvo crea enlaces `recurrent`. Para más información sobre los diferentes tipos de enlaces, consulta la sección Links de nuestra guía de Links e Instituciones. |
| `external_id`
| altamente recomendado
| Puedes agregar un identificador adicional para asociarlo con el enlace en la base de datos de Belvo. El `external_id` que proporciones:
- Debe ser un ID único para cada usuario en tu base de datos.
- Debe tener al menos tres caracteres de longitud.
- Solo puede estar compuesto por letras, números, guiones (`-`) y guiones bajos (`_`).
- No puede contener ninguna información personal identificable sobre el usuario (correo electrónico, nombre, número de teléfono, número de tarjeta de crédito, etc.).
Para más detalles, consulta la sección Adding your own identifier de nuestra guía de mejores prácticas para la creación de Links.
|
Además, revisa nuestra sección Starting the widget de nuestra guía de Hosted Widget (OFDA).
### Escuchar el evento de éxito que incluirá el `id` del enlace.
Una vez que tu usuario termine el flujo del widget, te enviaremos un evento de `success` a la URL que proporcionaste cuando generaste el token de `access` del widget. Este evento incluirá el `id` del enlace que necesitarás asociar con tu `external_id` en tu base de datos.
Este paso requiere cierto conocimiento sobre cómo manejar redirecciones y sus parámetros de consulta. Para obtener detalles sobre los eventos que enviamos (y su formato), consulta la sección Manejo de eventos de callback de nuestra guía del Hosted Widget (OFDA).
Para ayudarte en el desarrollo, hemos creado guías sobre cómo configurar enlaces profundos y escuchar eventos para las siguientes plataformas:
- iOS (Swift)
- Android (Kotlin)
- React Native
### Esperar webhooks y recuperar datos
Como Belvo utiliza un flujo de trabajo asincrónico, una vez que se crea el enlace, automáticamente recuperamos los últimos 12 meses de datos históricos para el usuario que acaba de conectar su cuenta. Te notificamos a través de eventos de webhook una vez que los datos son extraídos y puedes recuperarlos. Para más detalles, consulta la sección Obteniendo Datos.
## Obtención de Datos
Independientemente de si utilizas enlaces únicos o recurrentes, una vez que tu usuario completa el flujo del widget con éxito, Belvo recupera de manera asincrónica los últimos 12 meses de datos de propietario, cuenta, transacción, factura e inversión para el enlace (actualizaciones históricas). Una vez que hemos extraído los datos, te notificamos mediante un webhook que la información está lista para ser recuperada.
Si estás utilizando enlaces recurrentes, Belvo recuperará la información actualizada para el enlace de acuerdo con tu frecuencia de actualización (actualizaciones recurrentes). Al igual que con las actualizaciones históricas, te notificamos mediante un webhook que la nueva información está lista para ser recuperada.
Creación de Enlace y Límites de Datos
Al generar el consentimiento y crear el enlace, Belvo ya consume un límite operativo de Propietarios, Cuentas, Transacciones, Facturas e Inversiones (para recuperar los datos históricos de tu usuario). Sin embargo, Belvo ha implementado ciertos mecanismos internos para optimizar los límites de recuperación de datos. Para más información, consulta nuestro artículo dedicado Límites de la Red de Open Finance (Brasil).
La Red de Open Finance de Brasil establece límites mensuales sobre la frecuencia con la que puedes recuperar datos para una persona o empresa específica. Estos límites operativos están vinculados a una combinación de:
- el CPF o CNPJ del usuario
- los datos de la API que deseas obtener (Propietario, Cuenta, Transacción o Factura)
- el certificado de la Red de Open Finance
Una vez que se alcanza el límite operativo mensual de llamadas a la API, no se puede recuperar más información para el CPF/CNPJ hasta el inicio del siguiente mes calendario. Sin embargo, Belvo ha implementado optimizaciones para maximizar la cantidad de datos que puedes recuperar para tus usuarios de acuerdo con tus necesidades de datos. Para más información, consulta nuestro artículo dedicado Límites de la Red de Open Finance (Brasil).
### Actualizaciones históricas
A continuación, puedes ver el flujo de datos para enlaces únicos y recurrentes una vez que se crea un enlace:
```mermaid
sequenceDiagram
participant Application
participant Belvo
participant Institution
Application->>Belvo: Crear un Link usando el widget
Belvo->>Institution: Conectar y confirmar consentimiento con la institución
Belvo-->>Application: 201 - Creado
Institution-->>Belvo: Belvo recupera información histórica para el ID del link.
Note over Application,Belvo: PROPIETARIOS
Belvo->>Application: WEBHOOK historical_update (PROPIETARIOS)
Application->>Belvo: GET /owners/?link={link.id}
Belvo-->>Application: 200 + Detalles del Propietario
Note over Application,Belvo: CUENTAS
Belvo->>Application: WEBHOOK historical_update (CUENTAS)
Application->>Belvo: GET /accounts/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Cuenta
Note over Application,Belvo: TRANSACCIONES
Belvo->>Application: WEBHOOK historical_update (TRANSACCIONES)
Application->>Belvo: GET /transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Transacción
Note over Application,Belvo: FACTURAS
Belvo->>Application: WEBHOOK historical_update (FACTURAS)
Application->>Belvo: GET /bills/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Factura
Note over Application,Belvo: INVERSIONES
Belvo->>Application: WEBHOOK historical_update (INVERSIONES)
Application->>Belvo: GET /br/investments/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Inversión
Note over Application,Belvo: TRANSACCIONES DE INVERSIÓN
Belvo->>Application: WEBHOOK historical_update (TRANSACCIONES DE INVERSIÓN)
Application->>Belvo: GET /br/investment-transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de las Transacciones de Inversión
```
Cada vez que recibas un webhook para un recurso dado (propietarios, cuentas, transacciones, facturas, inversiones o transacciones de inversión), necesitarás hacer una llamada GET a ese endpoint, usando el ID del link, para recuperar la información.
#### Obtener información del propietario
Belvo recuperará de manera asincrónica los datos del **propietario** de los últimos 12 meses para tu enlace y luego te enviará un webhook una vez que la información esté lista para ser recuperada (ver el ejemplo de webhook a continuación):
```json Actualización Histórica de Propietarios
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "OWNERS", // [!code highlight]
"process_type": "historical_update", // [!code highlight]
"webhook_code": "historical_update",
"link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "your_external_id",
"data": {
"total_owners": 2 // Número total de propietarios
}
}
```
Una vez que recibas el webhook, solo necesitas hacer la siguiente solicitud GET de Propietarios para recuperar los datos del enlace dado:
```curl Obtener Información del Propietario
curl --request GET 'https://api.belvo.com/api/owners/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `id` | string | true | El `link_id` que recibes en tu notificación de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |
#### Obtener información de la cuenta
Belvo recuperará de manera asincrónica los últimos 12 meses de datos de **account** para tu enlace y luego te enviará un webhook una vez que la información esté lista para ser recuperada (ver el ejemplo de webhook a continuación):
```json Actualización Histórica de Cuentas
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "ACCOUNTS", // [!code highlight]
"process_type": "historical_update", // [!code highlight]
"webhook_code": "historical_update",
"link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "your_external_id",
"data": {
"total_accounts": 5 // Número total de cuentas encontradas.
}
}
```
Una vez que recibas el webhook, solo necesitas hacer la siguiente solicitud GET Accounts para recuperar los datos del enlace dado:
```curl Obtener Información de la Cuenta
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `id` | string | true | El `link_id` que recibes en tu notificación de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |
#### Obtener información de la Transacción
Belvo recuperará de manera asincrónica los últimos 12 meses de datos de **transacción** para tu enlace y luego te enviará un webhook una vez que la información esté lista para ser recuperada (ver el ejemplo de webhook a continuación):
```json Actualización Histórica de Transacciones
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "TRANSACTIONS", // [!code highlight]
"process_type": "historical_update", // [!code highlight]
"webhook_code": "historical_update",
"link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // [!code warning]
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "your_external_id",
"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
}
}
```
Una vez que recibas el webhook, solo necesitas hacer la siguiente solicitud GET de Transacciones para recuperar los datos del enlace dado:
```curl Obtener Información de la Transacción
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `id` | string | true | El `link_id` que recibes en tu notificación de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |
#### Obtener información de la factura
Belvo recuperará de manera asincrónica los datos de **factura** de los últimos 12 meses para tu enlace y luego te enviará un webhook una vez que la información esté lista para ser recuperada (ver el ejemplo de webhook a continuación):
```json Actualización Histórica de Factura
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "BILLS", // [!code highlight]
"process_type": "historical_update", // [!code highlight]
"webhook_code": "historical_update",
"link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // [!code warning]
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "your_external_id",
"data": {
"total_bills": 2 // Número total de facturas
}
}
```
Una vez que recibas el webhook, solo necesitas hacer la siguiente solicitud GET de Facturas para recuperar los datos del enlace dado:
```curl Obtener Información de la Factura
curl --request GET 'https://api.belvo.com/api/bills/?link={id}' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `id` | string | si | El `link_id` que recibes en tu notificación de `historical_update`. | `2f8ca7a1-c28f-46f2-bb41-21633099a280` |
### Actualizaciones recurrentes
Si estás utilizando enlaces recurrentes, recibirás eventos de webhook de acuerdo con la frecuencia de actualización del enlace que estableciste con Belvo (diaria, semanal, mensual, etc.). Belvo envía los siguientes eventos de webhook para actualizaciones:
- `new_owners_available`
Recibirás un webhook `new_owners_available` cada vez que detectemos que ha habido un cambio en los detalles de los propietarios de la cuenta.
- `new_accounts_available`
Recibirás un webhook `new_accounts_available` cada vez que detectemos que ha habido un cambio en las cuentas que tiene el enlace.
- `new_transactions_available`
Recibirás un webhook `new_transactions_available` cada vez que detectemos que han ocurrido nuevas transacciones para cualquier cuenta que tenga el enlace.
- `new_bills_available`
Recibirás un webhook `new_bills_available` cada vez que se hayan generado nuevos estados de cuenta de tarjeta de crédito para un período de facturación.
- `new_investments_available`
Recibirás un webhook `new_investments_available` cada vez que detectemos que ha habido un cambio en las inversiones que tiene el enlace.
- `new_investment_transactions_available`
Recibirás un webhook `new_investment_transactions_available` cada vez que detectemos que ha habido nuevas transacciones para una inversión.
```mermaid
sequenceDiagram
participant Application
participant Belvo
participant Institution
Belvo->>Institution: Obtener nuevos datos para el enlace dado
Institution-->>Belvo: Información del recurso
Note over Application,Belvo: PROPIETARIOS
Belvo->>Application: WEBHOOK new_owners_available
Application->>Belvo: GET /owners/?link={link.id}
Belvo-->>Application: 200 + Detalles del Propietario
Note over Application,Belvo: CUENTAS
Belvo->>Application: WEBHOOK new_accounts_available
Application->>Belvo: GET /accounts/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Cuenta
Note over Application,Belvo: TRANSACCIONES
Belvo->>Application: WEBHOOK new_transactions_available
Application->>Belvo: GET /transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Transacción
Note over Application,Belvo: FACTURAS
Belvo->>Application: WEBHOOK new_bills_available
Application->>Belvo: GET /bills/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Factura
Note over Application,Belvo: INVERSIONES
Belvo->>Application: WEBHOOK new_investments_available
Application->>Belvo: GET /br/investments/?link={link.id}
Belvo-->>Application: 200 + Detalles de la Inversión
Note over Application,Belvo: TRANSACCIONES DE INVERSIÓN
Belvo->>Application: WEBHOOK new_investment_transactions_available
Application->>Belvo: GET /br/investment-transactions/?link={link.id}
Belvo-->>Application: 200 + Detalles de las Transacciones de Inversión
```
Tan pronto como recibas un webhook sobre información recién actualizada, solo necesitas hacer la misma llamada GET que hiciste para la actualización histórica para recibir la información actualizada.
```shell
# Obtener datos del propietario
curl --request GET 'https://api.belvo.com/api/owners/?link={id}'
# Obtener datos de la cuenta
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}'
# Obtener datos de la transacción
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}'
# Obtener datos de la factura
curl --request GET 'https://api.belvo.com/api/bills/?link={id}'
# Obtener datos de la inversión
curl --request GET 'https://api.belvo.com/api/investments/?link={id}'
# Obtener datos de la transacción de inversión
curl --request GET 'https://api.belvo.com/api/investment-transactions/?link={id}'
```
### Otros eventos de webhook
Belvo también te notifica cuando hay cambios en el consentimiento de tu link. Puedes recibir los siguientes webhooks relacionados con consentimientos:
- `openfinance_consent_expired`
- `openfinance_consent_with_unrecoverable_resources`
- `openfinance_consent_with_temporarily_unavailable_resources`
Para los eventos `openfinance_consent_expired`, puedes solicitar a tu usuario que renueve su consentimiento utilizando el My Belvo Portal. Para más información, consulta nuestro artículo dedicado a webhook de Consentimiento.
## Agregar un enlace a Mi Portal Belvo
Requisito Regulatorio
Según las regulaciones de Open Finance, tus usuarios deben tener una forma de fácil acceso para gestionar sus consentimientos dentro de tu aplicación o sitio web.
Belvo ha creado el Mi Portal Belvo (MBP) que permite a los usuarios gestionar sus consentimientos de manera simple y directa, cumpliendo con todos los requisitos de las regulaciones.
En tu aplicación, debes incluir un enlace claramente visible al MBP para que tus usuarios gestionen sus consentimientos.
El MBP se puede configurar de tres maneras diferentes:
- MBP Público
En el sitio web de Belvo, alojamos una instancia universal del MBP que cualquier usuario puede usar para gestionar sus consentimientos. Esta instancia consolida todos los consentimientos que han otorgado utilizando el producto OFDA de Belvo. Simplemente necesitas redirigir a tu usuario a `https://meuportal.belvo.com/?mode=landing`, donde pueden ingresar sus detalles. Tu usuario podrá ver **todos** los consentimientos que han otorgado usando Belvo (incluyendo otras aplicaciones que usan Belvo para extraer datos de la Red de Open Finance de Brasil).
- MBP Personalizado
Puedes personalizar el MBP para mostrar solo los consentimientos que tu usuario ha otorgado a tu aplicación, facilitando la gestión de los consentimientos.
- Modo de Renovación de Consentimiento
El MBP también se puede usar para renovar un consentimiento expirado. Belvo te enviará un webhook cuando el consentimiento de uno de tus usuarios haya expirado.
Guía Dedicada de Mi Portal Belvo
Para obtener detalles sobre cómo configurar el Mi Portal Belvo en tu aplicación,
consulta nuestra guía dedicada Mi Portal Belvo (OFDA).
## Recursos adicionales
### Lista de verificación de integración
Hemos creado una lista de verificación dedicada a todas las cosas que debes tener en cuenta al desarrollar tu integración OFDA. Revísala aquí: Lista de Verificación de Integración OFDA.
### Errores de la Red de Finanzas Abiertas
Durante el proceso de creación de consentimiento, las instituciones en la Red de Finanzas Abiertas realizan verificaciones para asegurar que la conexión sea estable y segura. Si la institución determina que la conexión no es estable o segura, redirigirá al usuario a una página de error personalizada con el siguiente contenido:
*Ocorreu um error. Por favor, verifique o seu CPF or CNPJ para ter certeza de que está correto, feche o aplicativo e reinicie o processo para conectar sua conta.*
Y en la URL de redirección, verá un fragmento de URL con los siguientes detalles:
```
api.belvo.com/api/consents/callback/#error_description=risk_analysis_denied...
```
Este error puede ocurrir por las siguientes razones:
- Su usuario tiene una conexión VPN activa en su dispositivo. Recomendamos desactivar la VPN e intentar nuevamente.
- Su usuario está accediendo a su institución a través de su aplicación en su dispositivo móvil, sin embargo, no es la última versión de la aplicación. Algunas instituciones requieren que la versión de la aplicación sea la última versión posible para permitir la autorización de consentimiento. Recomendamos actualizar la aplicación de la institución a la última versión disponible e intentar nuevamente.
- [**Itaú** **solamente**] Su usuario está accediendo a su institución en su computadora de escritorio, sin embargo, no tiene la aplicación Guardião 30 horas de Itaú instalada en su computadora. Itaú requiere que los usuarios tengan esta aplicación instalada en su computadora de escritorio para realizar el proceso de consentimiento.