# Introducción al Hosted Widget 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 un webview en tu aplicación y algo de conocimiento sobre el manejo de redirecciones deeplink. En esta página, te proporcionaremos documentación de referencia sobre qué información pasar al iniciar tu hosted widget, así como los posibles eventos que puedes recibir del widget. En esta guía te guiaremos a través de: 1. Generar un token de acceso 2. Iniciar el hosted widget 3. Manejar eventos de callback 4. Recuperar datos br ## Generando un access_token Para que el widget aparezca a tus usuarios finales, necesitas generar un `access_token` en tu servidor y enviarlo 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 `access_token`, simplemente realiza la siguiente llamada desde tu servidor a Belvo: Employments Brazil ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'see example payloads below' ``` Employments Brazil { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": ["EMPLOYMENTS", "OWNERS"], // [!code highlight] "widget": { "callback_urls": { "success": "your_deeplink_here://success", "exit": "your_deeplink_here://exit", "event": "your_deeplink_here://error" }, "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/" }, "theme": [] // See our dedicated widget customization article } } Employment Records Mexico ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'see example payloads below' ``` Employment Records Mexico { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], // [!code highlight] "widget": { "callback_urls": { "success": "your-url-here://success", "exit": "your-url-here://exit", "event": "your-url-here://error" }, "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/" }, "theme": [] // See our dedicated widget customization article } } Fiscal Mexico ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'see example payloads below' ``` Fiscal Mexico { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": [ // [!code highlight] "FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETURNS", "TAX_RETENTIONS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS" ], "widget": { "callback_urls": { "success": "your-url-here://success", "exit": "your-url-here://exit", "event": "your-url-here://error" }, "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/" }, "theme": [] // See our dedicated widget customization article } } br ## Iniciando el widget Cuando inicias tu webview, para comenzar el widget correctamente, necesitas pasar tu `access_token` en la cadena de URL. También puedes pasar los parámetros de configuración, como el idioma del widget (`locale`), 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. Ejemplo de Empleos Brasil ```markup Ejemplo de Configuración de Inicio de Empleos Brasil https://widget.belvo.io/ ?access_token={access_code} &locale=pt &institutions=inss_br_employment &access_mode=recurrent &external_id=HJLSI-897809 ``` Ejemplo de Registros de Empleo México ```markup Ejemplo de Configuración de Inicio de Registros de Empleo México https://widget.belvo.io/ ?access_token={access_code} &locale=es &institutions=imss_mx_employment,issste_mx_employment &access_mode=recurrent &external_id=HJLSI-897809 ``` Ejemplo Fiscal México ```markup Ejemplo de Configuración de Inicio Fiscal México https://widget.belvo.io/ ?access_token={access_code} &locale=es &institutions=sat_mx_fiscal &access_mode=recurrent &external_id=HJLSI-897809 ``` 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 (Multi-Región)**. ## Manejo de eventos de callback Utilizamos redirecciones de deep link para pasar información sobre lo que sucede en el widget. La estructura de nuestros deep links es: Necesitarás poder manejar eventos de **success**, **exit** y **error**. ### 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 (requerido para posteriormente recuperar datos de 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. | ``` your-url-here://success ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5 &institution=erebor_br_retail ``` br ### 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, ocurrió algo inesperado al iniciar 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`. | ```markup 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 ``` br ### 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 | ```markup Ejemplo de Evento de Error your-url-here://exit ?error=ACCESS_TOKEN_NOT_VALID &error_message=El%20access%20token%20no%20fue%20proporcionado%20o%20no%20es%20válido ``` br br ### Evento de advertencia Recibirás un evento de `advertencia` 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. | ```markup Ejemplo de Evento de Advertencia your-url-here://warning ?warning=institution_disabled &warning_message=The%20institution%20is%20temporarily%20unavailable. ``` br ## Recuperando datos Una vez que tu usuario conecte exitosamente su cuenta bancaria, recibirás el `link_id` en el evento de éxito. Belvo luego 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) br ## 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