Introdução ao Hosted Widget

Para aplicativos nativos (mobile) e também web-based, criamos uma versão hosted do nosso widget que simplifica significativamente o seu processo de desenvolvimento e integração. Tudo o que é necessário é que você crie uma webview em seu aplicativo e tenha algum conhecimento sobre como lidar com redirecionamentos de deeplink.

Nesta página, forneceremos a você a documentação de referência sobre quais informações passar ao iniciar seu hosted widget, bem como os possíveis eventos que você pode receber do widget.

Neste guia, vamos orientá-lo em:

1. Gerar um token de acesso
2. Iniciar o hosted widget
3. Manipular eventos de callback
4. Recuperar dados

Para que o widget apareça para seus usuários finais, você precisa gerar um access_token no seu servidor e enviá-lo para a Belvo. Assim que recebermos a solicitação, você receberá um objeto com duas chaves: access e refresh. Passe o valor da chave access ao iniciar o hosted widget.

Para gerar um access_token, basta fazer a seguinte chamada do seu servidor para a Belvo:

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'veja exemplos de payloads abaixo'

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"], 
  "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
  }
}

Quando você inicia sua webview, para iniciar o widget corretamente, é necessário passar seu access_token na string da URL.

https://widget.belvo.io/?access_token={access_code}

Você também pode passar os parâmetros de configuração, como o idioma do widget (locale), o tipo de link que você deseja criar (access_mode), ou quais instituições exibir com base nos recursos que você pode extrair delas (resources), na URL.

https://widget.belvo.io/
  ?access_token={access_code}
  &locale=pt
  &institutions=inss_br_employment
  &access_mode=recurrent
  &external_id=HJLSI-897809

Para uma lista completa de parâmetros (junto com detalhes de implementação), consulte nosso artigo Configuração de Inicialização do Widget (Multi-Região).

O hosted widget utiliza redirecionamentos de deep link para passar informações sobre o que acontece no widget. Você precisará ser capaz de lidar com eventos de sucesso, saída e erro. A estrutura do deep link é:

your-url-here://event_name?parameters

Você receberá um evento success quando o seu usuário tiver conectado com sucesso sua conta à instituição usando o widget. Ser capaz de lidar com o evento success é crítico, pois ele contém o id do link do usuário (necessário para posteriormente recuperar dados da API da Belvo).

your-url-here://success
  ?link={id}}
  &institution={institution_name}

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

Você receberá um evento exit quando o seu usuário final sair do widget:

• antes de conectar a conta.
• após selecionar uma instituição.
• devido a um erro.

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

A query string last_encountered_error é enviada apenas se ocorrer um erro. Veja a tabela abaixo para uma lista completa de possíveis códigos de erro e suas mensagens.

A query string meta_data é enviada sempre que um usuário sai do widget. Veja a tabela abaixo para uma lista de possíveis valores.

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

Você receberá um evento error sempre que ocorrer um erro durante o uso do widget.

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

Veja a tabela abaixo para uma lista de possíveis códigos de erro e suas mensagens.

Você receberá um evento warning sempre que um evento não terminante ocorrer durante o uso do widget.

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.

Veja a tabela abaixo para uma lista de possíveis códigos de aviso e suas mensagens.

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:

• Workflows Assíncronos (Links Únicos)
• Workflows Assíncronos (Links Recorrentes)

Para ajudar no seu desenvolvimento, criamos guias sobre como configurar links profundos e escutar eventos para as seguintes plataformas:

• iOS (Swift)
• Android (Kotlin)
• React Native