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 como lidar com redirecionamentos 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:
- Gerar um token de acesso
- Iniciar o hosted widget
- Lidar com eventos de callback
- Recuperar dados
## Gerando um access_token
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.
Os valores retornados são válidos por 10 minutos e invalidamos o token assim que um usuário conecta sua conta com sucesso.
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/"
},
"theme": [] // See our dedicated widget customization article
}
}## Iniciando o widget
Quando você inicia seu webview, para iniciar o widget corretamente, é necessário passar seu access_token na string da URL.
Você também pode passar os parâmetros de configuração, como o idioma do widget (locale), que tipo de link 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-897809Para uma lista completa de parâmetros (junto com detalhes de implementação), por favor veja nosso artigo Startup Configuration (Multi-Region) do widget.
Utilizamos redirecionamentos de deep link para passar informações sobre o que acontece no widget. A estrutura dos nossos deep links é:
Você precisará ser capaz de lidar com eventos de success, exit e error.
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).
| Parâmetro | Descrição |
|---|---|
link | O ID do link para o usuário. Você precisará deste ID para poder fazer solicitações adicionais para o usuário. |
institution | A instituição com a qual o link foi criado. |
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.
- depois de ter selecionado uma instituição.
- devido a um erro.
#### last_encountered_error
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.
| 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 tentar acessar a instituição. Tente novamente mais tarde. |
too_many_sessions | Impossível fazer login, uma sessão já está aberta com a instituição para essas credenciais |
unexpected_error | 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 |
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.
| 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. |
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.
| Código de erro | Mensagem de erro |
|---|---|
ACCESS_TOKEN_NOT_VALID | O token de acesso não foi fornecido ou não é válido |
your-url-here://exit
?error=ACCESS_TOKEN_NOT_VALID
&error_message=O%20token%20de%20acesso%20não%20foi%20fornecido%20ou%20não%20é%20válido### Evento de aviso
Você receberá um evento warning sempre que ocorrer um evento não terminal durante o uso do widget.
Veja a tabela abaixo para uma lista de possíveis códigos de aviso e suas mensagens.
| Código de aviso | Mensagem de aviso |
|---|---|
institution_disabled | A instituição está temporariamente indisponível. |
your-url-here://warning
?warning=institution_disabled
&warning_message=A%20institui%C3%A7%C3%A3o%20est%C3%A1%20temporariamente%20indispon%C3%ADvel.## 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:
## Guias da Plataforma
Para ajudar no seu desenvolvimento, criamos guias sobre como configurar links profundos e escutar eventos para as seguintes plataformas: