); } export default App; // Hook function useScript(src) { useEffect( () => { // Crear script const node = document.createElement('script'); node.src = src; node.type = 'text/javascript'; node.async = true; node.onload = createWidget // Añadir script al body del documento document.body.appendChild(node); }, [src] // Solo volver a ejecutar el efecto si el src del script cambia ) } ``` ```html ``` > 🚧 Asegúrate de incluir la **referencia** a `https://cdn.belvo.io/belvo-widget-1-stable.js`. De lo contrario, el widget no se cargará en tu aplicación. # Generar un `access_token` > 👍 Personalizando el `access_token` Cuando solicitas tu `access_token`, puedes pasar parámetros adicionales para personalizar la apariencia de tu widget. Para más información, consulta nuestra Guía de personalización y branding. > ❗️ Solicitud del lado del servidor La solicitud del `access_token` **debe** hacerse desde tu lado del servidor para proteger tus claves API (secretId y secretPassword). Así que si estás usando un framework como Vue o React, asegúrate de generar la solicitud desde tu lado del servidor. Para que el widget aparezca a tus usuarios finales, necesitas generar un `access_token` en tu lado del servidor y enviarlo a Belvo. Una vez que recibamos la solicitud, recibirás un objeto con dos elementos: `access` y `refresh`. Pasa el valor del elemento `access` a tu lado del cliente, y podrás iniciar el widget. Los valores devueltos son válidos por **10** minutos y pueden ser enviados a tu frontend para iniciar el Connect Widget. Invalidamos el token tan pronto como tu usuario conecta exitosamente su cuenta. Para generar un `access_token`, simplemente realiza una llamada desde tu lado del servidor a Belvo (ver el ejemplo a continuación): ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'Ver ejemplo de payload a continuación' ``` ```json { "id": "SECRET_ID", "password": "SECRET_PASSWORD", "scopes": "read_institutions,write_links", "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"], "credentials_storage": "store", "stale_in": "300d" } ``` > 📘 Scopes Recuerda pasar el parámetro `scopes` al generar tu access token, de lo contrario, el widget no se iniciará correctamente. Estos scopes son necesarios para otorgar los permisos correctos al token para que el widget funcione. `"scopes": "read_institutions,write_links"` Después de realizar tu llamada, Belvo devuelve un objeto del cual necesitarás el valor de la clave `access`. Enviarás este valor a tu lado del cliente para que el widget pueda realmente iniciarse. ```json { "access": "{access_token_for_widget}", // Necesitarás este valor para enviarlo a tu lado del cliente "refresh": "{refresh_token}" } ``` ✳️ ¡OK! Ahora que puedes generar `access_token`, ¡puedes iniciar el widget! # Iniciar el hosted widget Usando este `access_token` ahora puedes iniciar el hosted widget: ```javascript // Código para ser incluido dentro de tu etiqueta ``` ## Callback de evento Cuando los usuarios encuentran ciertos eventos en el widget, te enviaremos algunos datos para explicar lo que está sucediendo. El objeto de datos contendrá un `eventName`, `request_id` y un objeto `meta_data`. ```json { "data": [ { "eventName": "ERROR", "request_id": "UUID", "meta_data": { "error_code": "login_error", "error_message": "Credenciales inválidas proporcionadas para iniciar sesión en la institución", "institution_name": "bancoazteca_mx_retail", "timestamp": "2020-04-27T19:09:23.918Z" } } ] } ``` ```json { "data": [ { "eventName": "WARNING", "request_id": "UUID", "meta_data": { "warning_code": "institution_disabled", "warning_message": "La institución está temporalmente no disponible.", "institution_name": "bancoazteca_mx_retail", "timestamp": "2020-04-27T19:09:23.918Z" } } ] } ``` ```json { "data": [ { "eventName": "PAGE_LOAD", "meta_data": { "page": "/institutions", // Página a la que el usuario es dirigido "from": "/consent", // Página donde el usuario estaba previamente "institution_name": "" // Nota: Este campo solo aparece DESPUÉS de que hayan seleccionado una institución } } ] } ``` **event_name** Una cadena que representa el nombre del evento que acaba de ocurrir en el widget. | Tipo de evento | Descripción | | --- | --- | | `ERROR` | Cuando ocurrió un error recuperable en el widget, consulta el `error_code` y `error_message` en el `meta_data`. | | `WARNING` | Cuando un usuario intenta conectarse a una institución que actualmente no está disponible. Consulta el `warning_code` y `warning_message` en el `meta_data` para más información. | | `PAGE_LOAD` | Cuando un usuario avanza a la siguiente pantalla en el widget. | **request_id** Una cadena utilizada para identificar de manera única el error. > 🚧 Almacena el request_id Al implementar tu integración con Belvo, asegúrate de considerar el almacenamiento del request_id cuando recibas un error. De esta manera, cuando proporciones a nuestros ingenieros el ID, podrán solucionar el problema rápidamente y volver a poner todo en funcionamiento. **meta_data** Un objeto que contiene más información sobre el evento que acaba de ocurrir en el widget. El objeto `meta_data` puede tener las siguientes propiedades: | Parámetro | Descripción | | --- | --- | | `error_code` | El código de error que el usuario encontró. Consulta el callback de salida para la lista de posibles códigos de error. | | `error_message` | El mensaje de error que el usuario encontró. Consulta el callback de salida para la lista de posibles mensajes de error. | | `institution_name` | La institución seleccionada | | `timestamp` | Una marca de tiempo de cuándo ocurrió el evento | ```html ``` ## Callback de salida Cuando los usuarios deciden cerrar el widget, te enviaremos algunos datos para explicar lo que está sucediendo. El objeto de datos contendrá un objeto `last_encountered_error` y un objeto `meta_data`. > 👍 Caso de uso real Monitorear el callback de salida es útil ya que, basado en el evento, puedes redirigir a tu usuario a una pantalla particular después de que cierren el widget. ```json { "data": [ { "last_encountered_error": { "message": "Credenciales inválidas proporcionadas para iniciar sesión en la institución", "code": "login_error" }, "meta_data": { "institution_name": "erebor_mx_retail", "step": "abandon-survey" } } ] } ``` **last_encountered_error** El objeto `last_encountered_error` solo se envía si ocurrió un error. 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 | | --- | --- | | `institution_down` | La institución financiera está caída, intenta de nuevo 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 de nuevo más tarde. Un token MFA es requerido por la institución, pero aún no es soportado por Belvo. Inicio de sesión no intentado debido a credenciales inválidas Faltan credenciales para iniciar sesión en la institución | | `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** El objeto `meta_data` se envía siempre 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`. | Aquí hay un ejemplo de uso de onExit: ```html ``` # Usa el `link_id` para obtener datos Una vez que tu usuario conecte 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) br # Modo de actualización del widget Connect El widget Connect puede configurarse en "modo de actualización" para restaurar un enlace que ha dejado de funcionar temporalmente porque: - el usuario ha cambiado la contraseña conectada con el Link - se requiere un nuevo token MFA Para más información, consulta nuestra guía para Actualizar un enlace usando el widget Connect.