Visão Geral do Hosted Widget (OFDA)

Introdução

Para aplicativos nativos móveis, 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 o manuseio de redirecionamentos deeplink.

Nesta página, forneceremos a você 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

Gerar um token de acesso

Para o widget aparecer para seus usuários finais, você precisa gerar um token de access 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 token de access, basta fazer uma 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,read_consents,write_consents,write_consent_callback,delete_consents",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "widget": {
    "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
    "openfinance_feature": "consent_link_creation",
    "callback_urls": {
      "success": "your_deeplink_here://success",
      "exit": "your_deeplink_here://exit",
      "event": "your_deeplink_here://error"
    },
    "consent": {
      "terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        }
      ]
    }
  }
}

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..."
}

Parâmetros configuráveis

Além dos parâmetros configuráveis obrigatórios abaixo, você também pode adicionar personalização e branding adicionais ao seu widget ao gerar seu token de access. Para mais informações, consulte nosso guia dedicado de Branding e personalização (OFDA).

stale_in

Você pode indicar por quanto tempo qualquer dado deve ser armazenado no banco de dados da Belvo para o link (tanto único quanto recorrente). Por exemplo, se você enviar 90d, a Belvo removerá qualquer dado de seu banco de dados relacionado ao usuário após 90 dias (ou seja, 90 dias após a última vez que a informação foi recuperada para o usuário). Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja excluído.

fetch_resources

Para links únicos, você pode definir quais recursos a Belvo irá recuperar de forma assíncrona informações históricas usando o parâmetro fetch_resources. Para mais informações, veja nossa documentação de Fluxo de trabalho assíncrono de dados históricos (links únicos).

purpose

No objeto consent, você pode personalizar a mensagem que é exibida ao seu usuário sobre para qual caso de uso você está solicitando os dados deles no campo purpose. Por padrão, o widget exibe a seguinte mensagem: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _.

Para alterar o conteúdo, basta adicionar seu texto (máximo de 600 caracteres) ao campo purpose:

{
  "widget": {
    "consent": {
       "purpose": "Seu texto personalizado aqui. Máximo de 600 caracteres",
       ...
    }
  }   
}

callback_urls

No objeto widget, você precisa adicionar o objeto callback_urls com as seguintes informações:

• success é o URL deeplink para o qual seu usuário é redirecionado quando o fluxo é bem-sucedido.
• exit é o URL deeplink para o qual seu usuário é redirecionado quando sai do widget antes de completar o fluxo.
• event é o URL deeplink para o qual seu usuário é redirecionado quando ocorre um erro.

terms_and_conditions_url

No objeto consent, você precisa adicionar um link para os termos e condições da sua empresa usando o parâmetro terms_and_conditions_url.

permissions

No novo objeto consent, enviamos uma lista padrão de recursos usados para recuperar para o usuário usando o parâmetro permissions. O valor de permissions deve ser sempre o seguinte array de itens: ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"].

🚧 Alterando Permissões de Consentimento

Se você precisar alterar as permissões de consentimento padrão, por favor, entre em contato com nossa equipe de suporte.

identification_info

No objeto consent, você precisa fornecer as informações de identificação do usuário para o qual deseja recuperar informações no parâmetro identification_info. As informações que você fornecer aqui devem corresponder às informações que a instituição regulamentada possui para o usuário (por exemplo, para empresas, o CPF e o nome devem ser de um usuário com acesso à conta empresarial). Por exemplo:

{
  "consent": {
    "identification_info": [
      {
        "type": "CPF",
        "number": "76109277673",
        "name": "Ralph Bragg"
      }
    ]
  }
}

Iniciar o Widget

Quando você iniciar seu hosted widget, na string da URL você precisa passar seu:

• token de access gerado
• definir locale como pt
• definir mode como webapp

Por exemplo:

https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp

Você também pode passar parâmetros de configuração adicionais, como o tipo de link que deseja criar (access_mode), ou quais instituições exibir com base nos recursos que você pode extrair delas (resources), na URL. Para uma lista completa de parâmetros (junto com detalhes de implementação), por favor veja nosso artigo de Configuração de Inicialização (OFDA) do widget. Por exemplo:

https://widget.belvo.io/
	?access_token={access_code}
	&locale=pt
	&mode=webapp
	&integration_type=openfinance
	&institution_types=retail
	&institutions=ofbradesco_br_retail
	&country_codes=BR
	&access_mode=recurrent
	&external_id=HJLSI-897809
	&resources=OWNERS,ACCOUNTS

Lidando com eventos de callback

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 success, exit e error. A estrutura do deep link é:

Guias da plataforma

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

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

Evento de sucesso

Você receberá um evento success quando seu usuário tiver conectado com sucesso sua conta à sua 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 Belvo).

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

Evento de saída

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

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

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

meta_data

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

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 erro

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

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

your-url-here://exit
	?error=ACCESS_TOKEN_NOT_VALID
	&error_message=O%20access%20token%20não%20foi%20fornecido%20ou%20não%20é%20válido

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

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

your-url-here://warning
	?warning=institution_disabled
  &warning_message=A%20instituição%20está%20temporariamente%20indisponível.

Agora que você pode lidar com deep links (mais importante para recuperar o id do link do evento success), você poderá começar a recuperar dados sobre seu usuário.

Recuperando 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:

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