Este artigo refere-se ao hosted widget multi-região

O conteúdo deste artigo refere-se ao hosted widget multi-região (aplicável para o México). Se você deseja operar no Brasil, por favor veja nosso Connect Widget para OFDA Regulamentado.

# Introdução

A Belvo oferece uma solução de Connect Widget plug-and-play, tanto para aplicações web quanto móveis, que proporciona um processo de autenticação seguro e otimizado para cada instituição. O Connect Widget é a maneira mais suave para seus usuários conectarem sua conta bancária dentro de sua aplicação. É compatível com nossos produtos de agregação: Banking, Employment e Fiscal.

Se você gostaria de testar como funciona, confira nossa Demonstração do Widget.

Aqui está uma prévia do Connect widget em um site de demonstração:

Fluxo (Multi Região)

A integração de ponta a ponta envolve seu frontend e backend. Abaixo está uma visão geral de como você pode criar links com o hosted widget.

Como você pode ver, seu lado cliente e servidor estarão envolvidos no fluxo do Connect Widget. Aqui está um exemplo de ponta a ponta para ilustrar a responsabilidade de cada lado:

Seu usuário clica em um botão Adicionar uma conta bancária dentro do seu aplicativo.
Seu frontend chama seu backend para solicitar um access_token da Belvo.
Seu backend chama a Belvo para obter um access_token.
A Belvo retorna um access_token válido para seu backend.
Seu servidor retorna o access_token para seu frontend.
Seu frontend inicia o widget usando o access_token.
O usuário navega pelo Connect Widget e cria um link válido para sua instituição.
A Belvo retorna o id do link recém-criado via um callback de evento para seu frontend. A Belvo então começará a recuperar assincronamente os dados históricos para o link.
A Belvo envia um webhook para seu backend assim que os dados estiverem disponíveis para cada recurso principal.
Seu backend recupera os dados usando uma chamada GET, passando o id do link como um parâmetro de consulta.
A Belvo retorna as informações para seu backend e as encaminha para seu frontend.
Seu usuário vê seus dados financeiros dentro do seu serviço.

❗️ Chamadas do lado do servidor
Nossa API não pode ser usada diretamente do frontend. O token de acesso e qualquer outra solicitação de API que você precisar devem ser tratados a partir do seu backend (lado do servidor).

# Incorporar o snippet do Connect widget

Para incorporar o código do widget em sua aplicação, adicione os seguintes elementos de código na página onde o Connect Widget deve aparecer (se você estiver trabalhando com Angular, React ou Vue, basta selecionar a aba de código relevante para você).

<!-- Para incorporar o Connect widget estaticamente, basta usar o seguinte código. -->
<head>
  ...
  <script src="https://cdn.belvo.io/belvo-widget-1-stable.js" async></script>
  ...
<head>
<body>
  ...
  <div id="belvo"></div> <!-- em qualquer lugar dentro do body -->
  ...
</body>
  
 
<!-- Para incorporar o Connect widget dinamicamente, basta usar o seguinte código no seu <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';

  // Implemente a interface OnInit para poder carregar o 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, adicione o código do Passo 3 aqui.

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(
      () => {
        // Criar script
        const node = document.createElement('script');
        node.src = src;
        node.type = 'text/javascript';
        node.async = true;
        node.onload = createWidget
        // Adicionar script ao corpo do documento
        document.body.appendChild(node);
      },
      [src] // Reexecutar o efeito apenas se o src do script mudar
  )
}

<template>
  <div id="app">
    <div id="belvo" />
  </div>
</template>
<script>
  export default {
	  name: 'App',
	  mounted () {
		// Executando a função para carregar o widget após o mount, já que precisamos
		// que o template esteja carregado
		this.loadScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
	  },
	  methods: {
		// Por favor, adicione o código do Passo 3 aqui.
	  }
  }
</script>

🚧 Certifique-se de incluir a referência para https://cdn.belvo.io/belvo-widget-1-stable.js. Caso contrário, o widget não será carregado em seu app!

Gerar um `access_token`

👍 Personalizando o access_token
Quando você solicita seu access_token, pode passar parâmetros adicionais para personalizar a aparência do seu widget. Para mais informações, consulte nosso Guia de branding e personalização.

❗️ Solicitação do lado do servidor
A solicitação do access_token deve ser feita do lado do servidor para proteger suas chaves de API (secretId e secretPassword). Portanto, se você estiver usando um framework como Vue ou React, certifique-se de que a solicitação seja gerada do lado do servidor.

Para que o widget apareça para seus usuários finais, você precisa gerar um access_token no seu lado do servidor e enviá-lo para a Belvo. Assim que recebermos a solicitação, você receberá um objeto com dois elementos: access e refresh. Passe o valor do elemento access para o seu lado do cliente, e você poderá iniciar o widget.

Os valores retornados são válidos por 10 minutos e podem ser enviados para o seu frontend para iniciar o Connect Widget. Invalidamos o token assim que seu usuário conecta sua conta com sucesso.

Para gerar um access_token, basta fazer uma chamada do seu lado do servidor para a Belvo (veja o exemplo abaixo):

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'Veja o exemplo de payload abaixo'

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "credentials_storage": "store",
  "stale_in": "300d"
}

📘 Escopos
Lembre-se de passar o parâmetro scopes ao gerar seu access token, caso contrário, o widget não iniciará corretamente. Esses escopos são necessários para dar as permissões corretas ao token para que o widget funcione.
"scopes": "read_institutions,write_links"

Após fazer sua chamada, a Belvo retorna um objeto do qual você precisará do valor da chave access. Você enviará esse valor para o seu lado do cliente para que o widget possa realmente iniciar.

{
  "access": "{access_token_for_widget}", // Você precisará deste valor para enviar para o seu lado do cliente
  "refresh": "{refresh_token}"
}

✳️ OK! Agora que você pode gerar access_token, você pode iniciar o widget!

Usando este access_token você pode agora iniciar o hosted widget:

// Código a ser incluído dentro da sua tag <script type="text/javascript">

function successCallbackFunction(link, institution) {
	// Faça algo com o link e a instituição,
	// como associá-los ao seu usuário registrado no seu banco de dados.
}

function onExitCallbackFunction(data) {
	// Faça algo com os dados de saída.
}

function onEventCallbackFunction(data) {
	// Faça algo com os dados do evento.
}

// Função para chamar seu servidor para gerar o access_token e recuperar seu access token
function getAccessToken () { 
  // Certifique-se de mudar /get-access-token para apontar para o seu servidor.
  return fetch('/get-access-token', { method: 'GET' }) 
    .then(response => response.json())
    .then((data) => data.access)
    .catch(error => console.error('Erro:', error))
}

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

		// Adicione sua configuração de inicialização aqui.

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

	}).build();
}

getAccessToken().then(openBelvoWidget) // Uma vez que o access token é recuperado, o widget é iniciado.

// Insira o seguinte código após a classe AppComponent() do Passo 1.
async function createWidget() {
	// Função para chamar seu servidor para gerar o access_token e recuperar seu access token
	function getAccessToken() {
		// Certifique-se de mudar /get-access-token para apontar para o seu servidor.
		return fetch('http://localhost:3001/auth/token', {
				method: 'GET'
			})
			.then(response => response.json())
			.then((data) => data)
			.catch(error => console.error('Erro:', error))
	}
	const successCallbackFunction = (link, institution) => {
		// Faça algo com o link e a instituição,
		// como associá-los ao seu usuário registrado no seu banco de dados.
	}
	const onExitCallbackFunction = (data) => {
		// Faça algo com os dados de saída.
	}
	const onEventCallbackFunction = (data) => {
		// Faça algo com os dados do evento.
	}

	const config = {

		// Adicione sua configuração de inicialização aqui.

		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;
	// Atribua o callback que criará o Widget
	node.onload = createWidget;
	document.getElementsByTagName('head')[0].appendChild(node);
}

// Insira o seguinte código após a função useScript() do Passo 1.
async function createWidget() {
  // Função para chamar seu servidor para gerar o access_token e recuperar seu access token
	function getAccessToken() { 
    // Certifique-se de mudar /get-access-token para apontar para o seu servidor.
		return fetch('http://localhost:3001/auth/token', {
				method: 'GET'
			}) 
			.then(response => response.json())
			.then((data) => data)
			.catch(error => console.error('Erro:', error))
	}
	const callback = () => {}
	const successCallbackFunction = (link, institution) => {
		// Faça algo com o link e a instituição,
		// como associá-los ao seu usuário registrado no seu banco de dados.
	}
	const onExitCallbackFunction = (data) => {
		// Faça algo com os dados de saída.
	}
	const onEventCallbackFunction = (data) => {
		// Faça algo com os dados do evento.
	}
	const config = {

		// Adicione sua configuração de inicialização aqui.

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

// Insira o seguinte código após a função mounted() do Passo 1.
async createWidget() {
		// Função para chamar seu servidor para gerar o access_token e recuperar seu access token
		function getAccessToken() {
			// Certifique-se de mudar /get-access-token para apontar para o seu servidor.
			return fetch('/get-access-token', {
					method: 'GET'
				})
				.then(response => response.json())
				.then((data) => data)
				.catch(error => console.error('Erro:', error))
		}
		const successCallbackFunction = (link, institution) => {
			// Faça algo com o link e a instituição,
			// como associá-los ao seu usuário registrado no seu banco de dados.
		}
		const onExitCallbackFunction = (data) => {
			// Faça algo com os dados de saída.
		}
		const onEventCallbackFunction = (data) => {
			// Faça algo com os dados do evento.
		}

		const config = {

			// Adicione sua configuração de inicialização aqui.

			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 = sim;
		// Atribua o callback que criará o Widget
		node.onload = this.createWidget;
		// Adicione o script ao corpo do documento
		document.body.appendChild(node);
	}
}

👍 Personalize a marca e a configuração de inicialização
Você pode adicionar personalização de marca, bem como configurar quais informações (países, instituições) o widget deve exibir quando for iniciado.
Consulte nossos guias dedicados para mais informações:
Configuração de inicialização
Marca e personalização

Você precisa implementar funções de callback para lidar com os dados de sucesso, erro e saída que a Belvo envia.

A API da Belvo pode enviar para você:

Dados de sucesso, que contêm o link_id e a instituição à qual um usuário se conectou.
Dados de evento, que contêm informações sobre diferentes eventos, como erros, que ocorrem durante o uso do widget.
Dados de saída, que contêm informações sobre quando um usuário sai do widget, se encontrou algum erro e qual instituição ele havia selecionado.

👍 Casos de uso reais de eventos e saídas
Recomendamos fortemente que você implemente funções de registro de eventos para lidar com os dados de eventos e erros da Belvo para fins de diagnóstico.
Regularmente vemos nossos clientes usarem essas funções para criar logs. O que eles fazem é capturar toda a resposta e, em seguida, armazená-la para fins de solução de problemas.

Callback de sucesso

Uma vez que um usuário conecta sua conta com sucesso, a Belvo envia um objeto de dados com a instituição e o ID do link (que você precisará em suas futuras requisições de dados).

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

Parâmetro	Descrição
`link` String	O link_id criado no widget
`institution` String	O nome da instituição para este link criado

Para lidar com esses dados, você precisa criar uma função de callback.

🚧 Obrigatório
Você deve criar uma função de callback para lidar com o objeto que a Belvo envia de volta. Caso contrário, o widget não iniciará e você receberá uma mensagem de erro.

Aqui está um exemplo de uso de callback de sucesso:

<script type="text/javascript">
  function successCallbackFunction(link, institution) {
      // Faça algo com o link e a instituição,
      // como associá-los ao seu usuário registrado no seu banco de dados.
	}

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

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

Retorno de chamada de evento

Quando os usuários encontram certos eventos no widget, enviaremos alguns dados para explicar o que está acontecendo. O objeto de dados conterá um eventName, request_id e um objeto meta_data.

{
  "data": [
    {
      "eventName": "ERROR",
      "request_id": "UUID",
      "meta_data": {
        "error_code": "login_error",
        "error_message": "Invalid credentials provided to login to the institution",
        "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": "The institution is temporarily unavailable.",
        "institution_name": "bancoazteca_mx_retail",
        "timestamp": "2020-04-27T19:09:23.918Z"
      }
    }
  ]
}

{
  "data": [
    {
      "eventName": "PAGE_LOAD",
      "meta_data": {
        "page": "/institutions", // Página para a qual o usuário é direcionado
        "from": "/consent", // Página onde o usuário estava anteriormente
        "institution_name": "" // Nota: Este campo só aparece DEPOIS que eles selecionaram uma instituição
      }
    }
  ]
}

event_name
Uma string que representa o nome do evento que acabou de ocorrer no widget.

Tipo de evento	Descrição
`ERROR`	Quando um erro recuperável ocorreu no widget, veja o `error_code` e `error_message` no `meta_data`.
`WARNING`	Quando um usuário tenta se conectar a uma instituição que está atualmente indisponível. Veja o `warning_code` e `warning_message` no `meta_data` para mais informações.
`PAGE_LOAD`	Quando um usuário avança para a próxima tela no widget.

request_id

Uma string usada para identificar exclusivamente o erro.

🚧 Armazene o request_id
Ao implementar sua integração Belvo, certifique-se de considerar o armazenamento do request_id quando você receber um erro. Desta forma, quando você fornecer o ID aos nossos engenheiros, eles poderão solucionar o problema rapidamente e fazer com que você volte a funcionar.

meta_data
Um objeto contendo mais informações sobre o evento que acabou de ocorrer no widget.
O objeto meta_data pode ter as seguintes propriedades:

Parâmetro	Descrição
`error_code`	O código de erro que o usuário encontrou. Veja o retorno de chamada de saída para a lista de possíveis códigos de erro.
`error_message`	A mensagem de erro que o usuário encontrou. Veja o retorno de chamada de saída para a lista de possíveis mensagens de erro.
`institution_name`	A instituição selecionada
`timestamp`	Um timestamp de quando o evento ocorreu

<script type="text/javascript">
  function onEventCallbackFunction (data) {
    
    // Faça algo com os dados do evento
  }
  
  function openBelvoWidget() {
    ...
    belvoSDK.createWidget(access_token, {
      ...
      onEvent: (data) => this.onEventCallbackFunction(data),
      ...
    }).build();
  }    
</script>

Callback de saída

Quando os usuários decidirem fechar o widget, enviaremos alguns dados para explicar o que está acontecendo. O objeto de dados conterá um objeto last_encountered_error e um objeto meta_data.

👍 Caso de uso no mundo real
Monitorar o callback de saída é útil, pois com base no evento, você pode redirecionar seu usuário para uma tela específica após eles fecharem o widget.

{
  "data": [
    {
      "last_encountered_error": {
        "message": "Invalid credentials provided to login to the institution",
        "code": "login_error"
      },
      "meta_data": {
        "institution_name": "erebor_mx_retail",
        "step": "abandon-survey"
      }
    }
  ]
}

last_encountered_error

O objeto last_encountered_error é enviado apenas se ocorrer um erro. Veja a tabela abaixo para uma lista de possíveis códigos de erro e suas mensagens.

Código de erro	Mensagem de erro
`institution_down`	A instituição financeira está fora do ar, tente novamente mais tarde
`login_error`	As possíveis mensagens de erro para um login_error são: - Credenciais inválidas fornecidas para login na instituição A conta do usuário está bloqueada, o usuário precisa contatar a instituição para desbloqueá-la O acesso à conta do usuário foi proibido pela instituição Impossível fazer login, algo inesperado aconteceu ao fazer login na instituição. Tente novamente mais tarde. Um token MFA é necessário pela instituição, mas ainda não é suportado pela Belvo. Login não tentado devido a credenciais inválidas Credenciais ausentes para login na instituição
`too_many_sessions`	Impossível fazer login, uma sessão já está aberta com a instituição para essas credenciais
`unexpected_error`	A Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição

meta_data

O objeto meta_data é enviado sempre que um usuário sai do widget. Veja a tabela abaixo para uma lista de possíveis valores.

Parâmetro	Descrição
`step`	Enviado quando o usuário sai do widget na tela inicial. O valor do parâmetro é sempre `abandon-survey`.
`institution_name`	Enviado quando o usuário sai do widget após selecionar uma instituição. O valor será o código da instituição da Belvo, por exemplo, `banamex_mx_retail`.

Aqui está um exemplo de uso do onExit:

<script type="text/javascript">
  function onExitCallbackFunction (data) {
    
    // Faça algo com os dados de saída
  }
  
  function openBelvoWidget() {
    ...
    belvoSDK.createWidget(access_token, {
      ...
      onExit: (data) => this.onExitCallbackFunction(data),
      ...
    }).build();
  }    
</script>

Use o `link_id` para obter dados

Uma vez que seu usuário conecta com sucesso sua conta bancária, você receberá o link_id no evento de sucesso. A Belvo então enviará webhooks informando quando a informação estiver pronta para o link. Para mais informações, veja:

# Modo de atualização do widget Connect

O widget Connect pode ser configurado no “modo de atualização” para restaurar um link que parou de funcionar temporariamente porque:

a senha conectada com o Link foi alterada pelo usuário
um novo token MFA é necessário

Para mais informações, consulte nosso guia para Atualizar um link usando o widget Connect.

Fluxo (Multi Região)

Gerar um `access_token`

Iniciar o hosted widget

Implementar callbacks do widget

Callback de sucesso

Retorno de chamada de evento

Callback de saída

Use o `link_id` para obter dados

Quão útil foi esta página?

Fluxo (Multi Região)

Gerar um access_token

Iniciar o hosted widget

Implementar callbacks do widget

Callback de sucesso

Retorno de chamada de evento

Callback de saída

Use o link_id para obter dados

Quão útil foi esta página?

Gerar um `access_token`

Use o `link_id` para obter dados