# Introducción al Hosted Widget

Para aplicaciones nativas móviles y basadas en la web, hemos creado una versión hosted de nuestro widget que simplifica significativamente tu proceso de desarrollo e integración. Todo lo que necesitas es crear un webview en tu aplicación y tener 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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "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.

```text Ejemplo de URL del Hosted Widget
https://widget.belvo.io/?access_token={access_code}
```

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

El hosted widget utiliza redirecciones de deep link para pasar información sobre lo que ocurre en el widget. Necesitarás poder manejar eventos de **success**, **exit** y **error**. La estructura del deep link es:

```text Ejemplo de Estructura de Deeplink
your-url-here://event_name?parameters
```

| Parámetro | Descripción |
|  --- | --- |
| `your-url-here` | Tu manejador de deeplink (esquema) |
| `event_name` | El nombre del evento (host) |
| `parameters` | Los parámetros del evento (enviados como query strings) |


### 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 enlace del usuario (necesario para posteriormente recuperar datos de la API de Belvo).

```text Ejemplo de Evento de Éxito
your-url-here://success
  ?link={id}}
  &institution={institution_name}

your-url-here://success
  ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5
  &institution=erebor_br_retail
```

| Parámetro  | Descripción | Ejemplo  |
|  --- | --- | --- |
| `link` | El ID del enlace (UUID) para el usuario. Necesitarás este ID para poder realizar solicitudes adicionales para el usuario. | `cb65f82c-dc93-4d3e-8270-9a27528397f5` |
| `institution` | La institución con la que se creó el enlace. | `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 haber seleccionado una institución.
- debido a un error.


```text Ejemplo de Evento de Salida
your-url-here://exit
  ?last_encountered_error_code={error_code}
  &last_encountered_error_message={error_message}
  &meta_data_institution_name={institution_name}
  &meta_data_step=abandon-{step_name}


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
```

#### last_encountered_error

El parámetro 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 intentar 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 | Ejemplo  |
|  --- | --- | --- |
| `step` | Se envía cuando el usuario sale del widget en la pantalla inicial. El valor del parámetro siempre es `abandon-survey`. | `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. | `ofmockbank_br_retail`. |


```markup Exit Event Example
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.

```text Ejemplo de Evento de Error
your-url-here://error
  ?error={error_name}
  &error_message={error_message}


your-url-here://error
  ?error=ACCESS_TOKEN_NOT_VALID
  &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid
```

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 (Codificado en URL) |
|  --- | --- |
| `ACCESS_TOKEN_NOT_VALID` | The access token was not provided or is not valid |


### Evento de advertencia

Recibirás un evento `warning` cada vez que ocurra un evento no terminante durante el uso del widget.

```text Ejemplo de Evento de Advertencia
your-url-here://warning
  ?warning={warning_code}
  &warning_message={warning_message}

your-url-here://warning
  ?warning=institution_disabled
  &warning_message=The%20institution%20is%20temporarily%20unavailable.
```

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 (Codificado en URL) |
|  --- | --- |
| `institution_disabled` | The institution is temporarily unavailable. |


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