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
• Configuración del 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 tu flujo. 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.

Configuración del Hosted Widget

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:

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:

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'ver ejemplo de payload abajo'

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

Además, consulta nuestra sección Generando un access_token de nuestra guía de Hosted Widget (OFDA).

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..."
}

Iniciar el widget dentro de una webview

A continuación, necesitarás redirigir a tu usuario al widget en una webview dentro de tu aplicación:

https://widget.belvo.io/
	?access_token={access}
  &mode=webapp
  &locale=pt
  &access_mode=single
  &external_id=HJLSI-897809

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

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 link, 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 Obtener Datos.

Obtención de Datos

Independientemente de si utilizas enlaces únicos o recurrentes, una vez que tu usuario completa el flujo del widget exitosamente, 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.

La Red de Open Finance de Brasil establece límites mensuales sobre la frecuencia con la que puedes recuperar datos para una persona o negocio específico. 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 tanto únicos como recurrentes una vez que se crea un enlace:

Cada vez que recibas un webhook para un recurso dado (owners, accounts, transactions, o bills), necesitarás hacer una llamada GET a ese endpoint, usando el ID del enlace, 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 link 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):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "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 Owners para recuperar los datos del link dado:

curl --request GET 'https://api.belvo.com/api/owners/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Obtener información de la cuenta

Belvo recuperará de manera asincrónica los últimos 12 meses de datos de account para tu link 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):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "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 link dado:

curl --request GET 'https://api.belvo.com/api/accounts/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Obtener información de la Transacción

Belvo recuperará de manera asincrónica los últimos 12 meses de datos de transacción para tu link 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):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "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 Transactions para recuperar los datos del link dado:

curl --request GET 'https://api.belvo.com/api/transactions/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

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

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", 
  "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 --request GET 'https://api.belvo.com/api/bills/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Actualizaciones recurrentes

Si estás utilizando enlaces recurrentes, recibirás eventos de webhook de acuerdo con la frecuencia 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. Para más información, consulta nuestro artículo dedicado al webhook de Propietarios (Agregación).
• 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. Para más información, consulta nuestro artículo dedicado al webhook de Cuentas (Agregación).
• 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. Para más información, consulta nuestro artículo dedicado al webhook de Transacciones (Agregación).
• new_bills_available
  Recibirás un webhook new_bills_available cada vez que se haya generado un nuevo estado de cuenta de tarjeta de crédito para un período de facturación. Para más información, consulta nuestro artículo dedicado al webhook de Facturas (Agregació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.

# Recuperar datos del propietario
curl --request GET 'https://api.belvo.com/api/owners/?link={id}'

# Recuperar datos de la cuenta
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}'

# Recuperar datos de transacciones
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}'

# Recuperar datos de facturas
curl --request GET 'https://api.belvo.com/api/bills/?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

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.

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ú only] Su usuario está accediendo a su institución en su computadora de escritorio, sin embargo, no tiene instalada la aplicación Guardião 30 horas de Itaú en su computadora. Itaú requiere que los usuarios tengan esta aplicación instalada en su computadora de escritorio para realizar el proceso de consentimiento.