# Descripción General del Hosted Widget (OFDA) ## Introducción Para aplicaciones móviles nativas, hemos creado una versión hosted de nuestro widget que simplifica significativamente tu proceso de desarrollo e integración. Todo lo que se requiere es que crees una vista web en tu aplicación y algo de conocimiento sobre el manejo de redirecciones deeplink. Esta página proporciona documentación de referencia sobre qué información pasar al iniciar tu hosted widget, así como los posibles eventos que puedes recibir del widget. Esta guía te lleva a través de: 1. Generar un token de acceso 2. Iniciar el hosted widget 3. Manejar eventos de callback 4. Recuperar datos Para aplicaciones móviles nativas, hemos desarrollado un flujo especializado App2App que mejora la experiencia del usuario cuando están conectando su cuenta dentro de tu aplicación. Para más detalles, consulta nuestro Flujo App2App del Hosted Widget para OFDA. ## Generar un token de acceso Para mostrar el widget a tus usuarios finales, genera un token de `access` en tu servidor y envíalo a Belvo. Una vez que recibamos la solicitud, recibirás un objeto con dos claves: `access` y `refresh`. Pasa el valor de la clave `access` al iniciar el hosted widget. Los valores devueltos son válidos por 10 minutos y invalidamos el token tan pronto como un usuario conecta exitosamente su cuenta. Para generar un token de `access`, simplemente realiza una llamada desde tu servidor a Belvo: ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'ver ejemplos de payloads abajo' ``` Individual (OFDA) ```json { "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"], "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_deeplink_here://success", "exit": "your_deeplink_here://exit", "event": "your_deeplink_here://event" }, "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" } ] } } } ``` Business (OFDA) ```json { "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"], "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_deeplink_here://success", "exit": "your_deeplink_here://exit", "event": "your_deeplink_here://event" }, "consent": { "terms_and_conditions_url": "https://www.belvo.com", "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"], "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } } ``` ```json Ejemplo de Respuesta de Token de Acceso { "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...", "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..." // [!code highlight] } ``` ### Parámetros configurables Además de los parámetros configurables a continuación, también puedes agregar personalización y marca adicional a tu widget al generar tu token de `access`. Para más información, consulta nuestra guía dedicada Marca y personalización (OFDA). #### stale_in Puedes indicar cuánto tiempo deben almacenarse los datos en la base de datos de Belvo para el link (tanto único como recurrente). Por ejemplo, si envías `90d`, Belvo eliminará cualquier dato de su base de datos relacionado con el usuario después de 90 días (es decir, 90 días después de la última vez que se recuperó la información para el usuario). Por defecto, Belvo almacena los datos del usuario durante 365 días, a menos que el link sea eliminado. #### fetch_resources Para usar `fetch_resources` para enlaces individuales, debes haber habilitado una URL de webhook en el dashboard. Para enlaces individuales, puedes establecer qué recursos Belvo recuperará de manera asincrónica para obtener información histórica utilizando el parámetro `fetch_resources`. Para más información, consulta nuestra documentación de Flujo de trabajo asincrónico de datos históricos (enlaces individuales). | Recurso | Tipo de Institución | | --- | --- | | `ACCOUNTS` | Banca Brasil | | `OWNERS` | Banca Brasil | | `TRANSACTIONS` | Banca Brasil | | `BILLS` | Banca Brasil | | `INVESTMENTS` | Banca Brasil | | `INVESTMENT_TRANSACTIONS` | Banca Brasil | #### propósito En el objeto `consent`, puedes personalizar el mensaje que se muestra a tu usuario sobre para qué caso de uso estás solicitando sus datos en el campo `purpose`. Por defecto, el widget muestra el siguiente mensaje: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _. Para cambiar el contenido, simplemente agrega tu texto (máximo 600 caracteres) al campo `purpose`: ```json Consent Purpose { "widget": { "consent": { "purpose": "Tu texto personalizado aquí. Máximo 600 caracteres", ... } } } ``` #### callback_urls En el objeto `widget`, necesitas agregar el objeto `callback_urls` con la siguiente información: - `success` es la URL deeplink a la que tu usuario es redirigido cuando el flujo es exitoso. - `exit` es la URL deeplink a la que tu usuario es redirigido cuando sale del widget antes de completar el flujo. - `event` es la URL deeplink a la que tu usuario es redirigido cuando ocurre un error. #### terms_and_conditions_url En el objeto `consent`, necesitas agregar un enlace a los términos y condiciones de tu empresa usando el parámetro `terms_and_conditions_url`. #### permisos En el objeto `consent`, enviamos una lista predeterminada de recursos para recuperar para el usuario utilizando el parámetro `permissions`. El valor de `permissions` debe ser siempre el siguiente array de elementos: `["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"]`. > 🚧 Cambio de Permisos de Consentimiento Si necesitas cambiar los permisos de consentimiento predeterminados, por favor asegúrate de contactar a nuestro [equipo de soporte](https://support.belvo.com/hc/en-us/requests/new). #### identification_info En el objeto `consent`, necesitas proporcionar la información de identificación del usuario para el que deseas recuperar información en el parámetro `identification_info`. 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). Por ejemplo: Individual (OFDA) ```json Individual (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" } ] } } ``` Business (OFDA) ```json Business (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } ``` ¡OK! Ahora que puedes generar un token de `access`, ¡puedes iniciar el widget! ## Iniciar el Widget Cuando inicias tu hosted widget, en la cadena de URL necesitas pasar tu: - token `access` generado - establecer `locale` a `pt` - establecer `mode` a `webapp` Por ejemplo: ```curl Ejemplo de URL del Hosted Widget https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp ``` También puedes pasar parámetros de configuración adicionales, como qué tipo de enlace deseas crear (`access_mode`), o qué instituciones mostrar basadas en los recursos que puedes extraer de ellas (`resources`), en la URL. Para una lista completa de parámetros (junto con detalles de implementación), por favor consulta nuestro artículo de Configuración de Inicio del Widget (OFDA). Por ejemplo: ```text Ejemplo de Cadena de Consulta de Inicio https://widget.belvo.io/ ?access_token={access_code} &locale=pt &mode=webapp &integration_type=openfinance &institution_types=retail &institutions=ofbradesco_br_retail &country_codes=BR &access_mode=recurrent &external_id=HJLSI-897809 &resources=OWNERS,ACCOUNTS ``` ## Manejo de eventos de callback El hosted widget utiliza redirecciones de deep link para pasar información sobre lo que sucede en el widget. Necesitarás poder manejar eventos de **success**, **exit** y **error**. La estructura del deep link es: ### Guías de plataforma Para ayudar en tu desarrollo, hemos creado guías sobre cómo configurar enlaces profundos y escuchar eventos para las siguientes plataformas: - iOS (Swift) - Android (Kotlin) - React Native ### Evento de éxito Recibirás un evento `success` cuando tu usuario haya conectado exitosamente su cuenta a su institución usando el widget. Poder manejar el evento `success` es crítico ya que contiene el `id` del link del usuario (necesario para recuperar datos posteriormente desde la API de Belvo). | Parámetro | Descripción | | --- | --- | | `link` | El ID del link para el usuario. Necesitarás este ID para poder hacer solicitudes adicionales para el usuario. | | `institution` | La institución con la que se creó el link. | ```curl Success Event your-url-here://success ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5 &institution=erebor_br_retail ``` ### Evento de salida Recibirás un evento `exit` cuando tu usuario final salga del widget: - antes de conectar su cuenta. - después de que hayan seleccionado una institución. - debido a un error. br #### last_encountered_error La cadena de consulta `last_encountered_error` solo se envía si ocurrió un error. Consulta la tabla a continuación para ver una lista completa de posibles códigos de error y sus mensajes. | Código de error | Mensaje de error | | --- | --- | | `institution_down` | La institución financiera no está disponible, intenta nuevamente más tarde | | `login_error` | Los posibles mensajes de error para un login_error son: - Credenciales inválidas proporcionadas para iniciar sesión en la institución La cuenta del usuario está bloqueada, el usuario necesita contactar a la institución para desbloquearla El acceso a la cuenta del usuario fue prohibido por la institución Imposible iniciar sesión, algo inesperado ocurrió mientras se iniciaba sesión en la institución. Intenta nuevamente más tarde. | | `too_many_sessions` | Imposible iniciar sesión, ya hay una sesión abierta con la institución para estas credenciales | | `unexpected_error` | Belvo no puede procesar la solicitud debido a un problema interno del sistema o a una respuesta no soportada de una institución | #### meta_data La cadena de consulta `meta_data` se envía cada vez que un usuario sale del widget. Consulta la tabla a continuación para ver una lista de posibles valores. | Parámetro | Descripción | | --- | --- | | `step` | Se envía cuando el usuario sale del widget en la pantalla inicial. El valor del parámetro es siempre `abandon-survey`. | | `institution_name` | Se envía cuando el usuario sale del widget después de seleccionar una institución. El valor será el código de institución de Belvo, por ejemplo `banamex_mx_retail`. | ```text Ejemplo de Evento de Salida your-url-here://exit ?last_encountered_error_code=login_error &last_encountered_error_message=Invalid%20credentials%20provided%20to%20login%20to%20the%20institution &meta_data_institution_name=amex_mx_retail &meta_data_step=abandon-survey ``` ### Evento de error Recibirás un evento `error` cada vez que ocurra un error durante el uso del widget. Consulta la tabla a continuación para ver una lista de posibles códigos de error y sus mensajes. | Código de error | Mensaje de error | | --- | --- | | `ACCESS_TOKEN_NOT_VALID` | El access token no fue proporcionado o no es válido | ```text Ejemplo de Evento de Error your-url-here://error ?error=ACCESS_TOKEN_NOT_VALID &error_message=El%20access%20token%20no%20fue%20proporcionado%20o%20no%20es%20válido ``` br ### Evento de advertencia Recibirás un evento de `warning` cada vez que ocurra un evento no terminal durante el uso del widget. Consulta la tabla a continuación para ver una lista de posibles códigos de advertencia y sus mensajes. | Código de advertencia | Mensaje de advertencia | | --- | --- | | `institution_disabled` | La institución está temporalmente no disponible. | ```text Ejemplo de Evento de Advertencia your-url-here://warning ?warning=institution_disabled &warning_message=La%20institución%20está%20temporalmente%20no%20disponible. ``` br Ahora que puedes manejar enlaces profundos y recuperar el `id` del enlace desde el evento de `success`, puedes comenzar a recuperar datos sobre tu usuario. ## Recuperando datos Una vez que tu usuario conecta exitosamente su cuenta bancaria, recibirás el `link_id` en el evento de éxito. Luego, Belvo te enviará webhooks informándote cuando la información esté lista para el enlace. Para más información, consulta: - Flujos de Trabajo Asíncronos (Enlaces Únicos) - Flujos de Trabajo Asíncronos (Enlaces Recurrentes)