Este artículo se refiere al widget multirregión

El contenido de este artículo se refiere al widget multirregión (aplicable para México). Si deseas operar en Brasil, por favor consulta nuestro Connect Widget para OFDA Regulada.

# Introducción

Belvo ofrece una solución de Connect Widget lista para usar, tanto para aplicaciones web como móviles, que proporciona un proceso de autenticación seguro y optimizado para cada institución. El Connect Widget es la forma más fluida para que tus usuarios conecten su cuenta bancaria dentro de tu aplicación. Es compatible con nuestros productos de agregación: Banking, Employment y Fiscal.

Si deseas probar cómo funciona, visita nuestra Demo del Widget.

Aquí tienes una vista previa del Connect widget en un sitio web de demostración:

Flow (Multi Región)

La integración de extremo a extremo involucra tu frontend y backend. A continuación se muestra una descripción general de cómo puedes crear enlaces con el widget de Connect.

Como puedes ver, tu lado cliente y servidor estarán involucrados en el flujo del Connect Widget. Aquí tienes un ejemplo de extremo a extremo para ilustrar la responsabilidad de cada lado:

Tu usuario hace clic en un botón de Agregar una cuenta bancaria dentro de tu aplicación.
Tu frontend llama a tu backend para solicitar un access_token de Belvo.
Tu backend llama a Belvo para obtener un access_token.
Belvo devuelve un access_token válido a tu backend.
Tu servidor devuelve el access_token a tu frontend.
Tu frontend inicia el widget usando el access_token.
El usuario navega a través del Connect Widget y crea un enlace válido a su institución.
Belvo devuelve el nuevo id del enlace creado a través de un callback de evento a tu frontend. Luego, Belvo comenzará a recuperar asincrónicamente los datos históricos para el enlace.
Belvo envía un webhook a tu backend una vez que los datos están disponibles para cada recurso principal.
Tu backend recupera los datos usando una llamada GET, pasando el id del enlace como un parámetro de consulta.
Belvo devuelve la información a tu backend y la reenvía a tu frontend.
Tu usuario ve sus datos financieros dentro de tu servicio.

❗️ Llamadas del lado del servidor
Nuestra API no puede ser utilizada directamente desde el frontend. El token de acceso y cualquier otra solicitud de API que necesites deben ser manejados desde tu backend (lado del servidor).

# Incrustar el fragmento del Connect widget

Para incrustar el código del widget en tu aplicación, añade los siguientes elementos de código a la página donde debería aparecer el Connect Widget (si estás trabajando en Angular, React o Vue, simplemente selecciona la pestaña de código relevante para ti).

<!-- Para incrustar el Connect widget de forma estática, solo usa el siguiente código. -->
<head>
  ...
  <script src="https://cdn.belvo.io/belvo-widget-1-stable.js" async></script>
  ...
<head>
<body>
  ...
  <div id="belvo"></div> <!-- en cualquier lugar dentro del body -->
  ...
</body>
  
 
<!-- Para incrustar el Connect widget de forma dinámica, solo usa el siguiente código en tu <body>. -->
  
<body>
...
  <script type="text/javascript">
     const widget = document.createElement('script');
     widget.setAttribute('src','https://cdn.belvo.io/belvo-widget-1-stable.js');
     document.body.appendChild(widget);
  </script>
...
</body>

import { Component, OnInit } from '@angular/core';

  // Implementa la interfaz OnInit para poder cargar el script
  @Component({
    selector: 'app-root',
   template: `
     <div class="content" role="main">
        <div id="belvo"></div>
     </div>
   `,
    styleUrls: ['./app.component.css']
  })
  export class AppComponent implements OnInit {
    title = 'widget-angular';
    // método implementado
    ngOnInit(): void {
      loadScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
    }
  }

// Por favor, añade el código del Paso 3 aquí.

import './App.css';
import { useEffect } from "react";
function App() {
  useScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
  return (
      <div id="belvo" />
  );
}
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
  )
}

<template>
  <div id="app">
    <div id="belvo" />
  </div>
</template>
<script>
  export default {
	  name: 'App',
	  mounted () {
		// Ejecutar la función para cargar el widget después de montar, ya que necesitamos
		// que la plantilla esté cargada
		this.loadScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
	  },
	  methods: {
		// Por favor, añade el código del Paso 3 aquí.
	  }
  }
</script>

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

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'

{
  "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.

{
  "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!

Usando este access_token ahora puedes iniciar el hosted widget:

// Código para ser incluido dentro de tu etiqueta <script type="text/javascript">

function successCallbackFunction(link, institution) {
	// Haz algo con el link y la institución,
	// como asociarlo con tu usuario registrado en tu base de datos.
}

function onExitCallbackFunction(data) {
	// Haz algo con los datos de salida.
}

function onEventCallbackFunction(data) {
	// Haz algo con los datos del evento.
}

// Función para llamar a tu servidor para generar el access_token y recuperar tu token de acceso
function getAccessToken () { 
  // Asegúrate de cambiar /get-access-token para apuntar a tu servidor.
  return fetch('/get-access-token', { method: 'GET' }) 
    .then(response => response.json())
    .then((data) => data.access)
    .catch(error => console.error('Error:', error))
}

function openBelvoWidget(accessToken) {
	belvoSDK.createWidget(accessToken, {

		// Añade tu configuración de inicio aquí.

		callback: (link, institution) => successCallbackFunction(link, institution),

	}).build();
}

getAccessToken().then(openBelvoWidget) // Una vez que se recupera el token de acceso, se inicia el widget.

// Inserta el siguiente código después de la clase AppComponent() del Paso 1.
async function createWidget() {
	// Función para llamar a tu servidor para generar el access_token y recuperar tu token de acceso
	function getAccessToken() {
		// Asegúrate de cambiar /get-access-token para apuntar a tu servidor.
		return fetch('http://localhost:3001/auth/token', {
				method: 'GET'
			})
			.then(response => response.json())
			.then((data) => data)
			.catch(error => console.error('Error:', error))
	}
	const successCallbackFunction = (link, institution) => {
		// Haz algo con el link y la institución,
		// como asociarlo con tu usuario registrado en tu base de datos.
	}
	const onExitCallbackFunction = (data) => {
		// Haz algo con los datos de salida.
	}
	const onEventCallbackFunction = (data) => {
		// Haz algo con los datos del evento.
	}

	const config = {

		// Añade tu configuración de inicio aquí.

		callback: (link, institution) => successCallbackFunction(link, institution),
		onExit: (data) => onExitCallbackFunction(),
		onEvent: (data) => onEventCallbackFunction()
	}
	const { access } = await getAccessToken();
	// @ts-ignore
	window.belvoSDK.createWidget(access, config).build();
}

function loadScript(src: string) {
	let node = document.createElement('script');
	node.src = src;
	node.type = 'text/javascript';
	node.async = true;
	// Asigna el callback que creará el Widget
	node.onload = createWidget;
	document.getElementsByTagName('head')[0].appendChild(node);
}

// Inserta el siguiente código después de la función useScript() del Paso 1.
async function createWidget() {
  // Función para llamar a tu servidor para generar el access_token y recuperar tu token de acceso
	function getAccessToken() { 
    // Asegúrate de cambiar /get-access-token para apuntar a tu servidor.
		return fetch('http://localhost:3001/auth/token', {
				method: 'GET'
			}) 
			.then(response => response.json())
			.then((data) => data)
			.catch(error => console.error('Error:', error))
	}
	const callback = () => {}
	const successCallbackFunction = (link, institution) => {
		// Haz algo con el link y la institución,
		// como asociarlo con tu usuario registrado en tu base de datos.
	}
	const onExitCallbackFunction = (data) => {
		// Haz algo con los datos de salida.
	}
	const onEventCallbackFunction = (data) => {
		// Haz algo con los datos del evento.
	}
	const config = {

		// Añade tu configuración de inicio aquí.

		callback: (link, institution) => successCallbackFunction(link, institution),
		onExit: (data) => onExitCallbackFunction(),
		onEvent: (data) => onEventCallbackFunction()
	}
	const { access } = await getAccessToken();
	window.belvoSDK.createWidget(access, config).build()
}

// Inserta el siguiente código después de la función mounted() del Paso 1.
async createWidget() {
		// Función para llamar a tu servidor para generar el access_token y recuperar tu token de acceso
		function getAccessToken() {
			// Asegúrate de cambiar /get-access-token para apuntar a tu servidor.
			return fetch('/get-access-token', {
					method: 'GET'
				})
				.then(response => response.json())
				.then((data) => data)
				.catch(error => console.error('Error:', error))
		}
		const successCallbackFunction = (link, institution) => {
			// Haz algo con el link y la institución,
			// como asociarlo con tu usuario registrado en tu base de datos.
		}
		const onExitCallbackFunction = (data) => {
			// Haz algo con los datos de salida.
		}
		const onEventCallbackFunction = (data) => {
			// Haz algo con los datos del evento.
		}

		const config = {

			// Añade tu configuración de inicio aquí.

			callback: (link, institution) => successCallbackFunction(link, institution),
			onExit: (data) => onExitCallbackFunction(),
			onEvent: (data) => onEventCallbackFunction()
		}
		const { access } = await getAccessToken();
		window.belvoSDK.createWidget(access, config).build()
	},
	loadScript(src) {
		const node = document.createElement('script');
		node.src = src;
		node.type = 'text/javascript';
		node.async = true;
		// Asigna el callback que creará el Widget
		node.onload = this.createWidget;
		// Añadir script al cuerpo del documento
		document.body.appendChild(node);
	}
}

👍 Personaliza la marca y la configuración de inicio
Puedes añadir personalización de marca así como configurar qué información (países, instituciones) el widget debe mostrar cuando se inicia.
Por favor, consulta nuestras guías dedicadas para más información:
Configuración de inicio
Marca y personalización

Necesitas implementar funciones de callback para manejar los datos de éxito, error y salida que Belvo envía.

La API de Belvo puede enviarte:

Datos de éxito, que contienen el link_id y la institución a la que un usuario se conectó.
Datos de evento, que contienen información sobre diferentes eventos, como errores, que ocurren durante el uso del widget.
Datos de salida, que contienen información sobre cuándo un usuario sale del widget, si encontraron algún error y qué institución habían seleccionado.

👍 Casos de uso reales de eventos y salidas
Recomendamos encarecidamente que implementes funciones de registro de eventos para manejar los datos de eventos y errores de Belvo con fines de diagnóstico.
Regularmente vemos que nuestros clientes utilizan estas funciones para crear registros. Lo que hacen es capturar la totalidad de la respuesta y luego almacenarla para fines de resolución de problemas.

Callback de éxito

Una vez que un usuario conecta exitosamente su cuenta, Belvo envía un objeto de datos con la institución y el ID del link (que necesitarás en tus futuras solicitudes de datos).

{
	"link": "link_id",
	"institution": "the_institution_that_the_user_connected_to"
}

Parámetro	Descripción
`link` String	El link_id creado en el widget
`institution` String	El nombre de la institución para este link creado

Para manejar estos datos, necesitas crear una función de callback.

🚧 Obligatorio
Debes crear una función de callback para manejar el objeto que Belvo envía de vuelta. De lo contrario, el widget no se iniciará y recibirás un mensaje de error.

Aquí tienes un ejemplo de uso de callback de éxito:

<script type="text/javascript">
  function successCallbackFunction(link, institution) {
      // Haz algo con el link y la institución, 
      // como asociarlo con tu usuario registrado en tu base de datos. 
	}

function openBelvoWidget(accessToken) {
  ...
    belvoSDK.createWidget(accessToken, {
    ...
      callback: (link, institution) => successCallbackFunction(link, institution),
    ...

    }).build();
}   
</script>

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.

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

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

{
  "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

<script type="text/javascript">
  function onEventCallbackFunction (data) {
    
    // Haz algo con los datos del evento
  }
  
  function openBelvoWidget() {
    ...
    belvoSDK.createWidget(access_token, {
      ...
      onEvent: (data) => this.onEventCallbackFunction(data),
      ...
    }).build();
  }    
</script>

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.

{
  "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:

<script type="text/javascript">
  function onExitCallbackFunction (data) {
    
    // Haz algo con los datos de salida
  }
  
  function openBelvoWidget() {
    ...
    belvoSDK.createWidget(access_token, {
      ...
      onExit: (data) => this.onExitCallbackFunction(data),
      ...
    }).build();
  }    
</script>

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:

# 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.

Flow (Multi Región)

Generar un `access_token`

Iniciar el hosted widget

Implementar callbacks del widget

Callback de éxito

Callback de evento

Callback de salida

Usa el `link_id` para obtener datos

¿Qué tan útil fue esta página?

Flow (Multi Región)

Generar un access_token

Iniciar el hosted widget

Implementar callbacks del widget

Callback de éxito

Callback de evento

Callback de salida

Usa el link_id para obtener datos

¿Qué tan útil fue esta página?

Generar un `access_token`

Usa el `link_id` para obtener datos