# Introdução ao Hosted Widget 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: 1. Gerar um token de acesso 2. Iniciar o hosted widget 3. Lidar com eventos de callback 4. Recuperar dados br ## 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: Employments Brazil ```shell 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' ``` Employments Brazil { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": ["EMPLOYMENTS", "OWNERS"], // [!code highlight] "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 } } Employment Records Mexico ```shell 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' ``` Employment Records Mexico { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], // [!code highlight] "widget": { "callback_urls": { "success": "your-url-here://success", "exit": "your-url-here://exit", "event": "your-url-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 } } Fiscal Mexico ```shell 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' ``` Fiscal Mexico { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links", "stale_in": "365d", "credentials_storage": "store", "fetch_resources": [ // [!code highlight] "FINANCIAL_STATEMENTS", "INVOICES", "TAX_RETURNS", "TAX_RETENTIONS", "TAX_STATUS", "TAX_COMPLIANCE_STATUS" ], "widget": { "callback_urls": { "success": "your-url-here://success", "exit": "your-url-here://exit", "event": "your-url-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 } } br ## 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. Exemplo de Empregos Brasil ```markup Exemplo de Configuração de Inicialização de Empregos Brasil https://widget.belvo.io/ ?access_token={access_code} &locale=pt &institutions=inss_br_employment &access_mode=recurrent &external_id=HJLSI-897809 ``` Exemplo de Registros de Emprego México ```markup Exemplo de Configuração de Inicialização de Registros de Emprego México https://widget.belvo.io/ ?access_token={access_code} &locale=es &institutions=imss_mx_employment,issste_mx_employment &access_mode=recurrent &external_id=HJLSI-897809 ``` Exemplo Fiscal México ```markup Exemplo de Configuração de Inicialização Fiscal México https://widget.belvo.io/ ?access_token={access_code} &locale=es &institutions=sat_mx_fiscal &access_mode=recurrent &external_id=HJLSI-897809 ``` Para uma lista completa de parâmetros (junto com detalhes de implementação), por favor veja nosso artigo **Startup Configuration (Multi-Region) do widget**. ## Lidando com eventos de callback 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**. ### 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). | 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 ``` br ### 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. br #### 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 | #### 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. | 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`. | ```markup Exemplo de Evento de Saída 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 ``` br ### 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 | ```markup Exemplo de Evento de Erro 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 ``` br br ### 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. | ```markup Exemplo de Evento de Aviso your-url-here://warning ?warning=institution_disabled &warning_message=A%20institui%C3%A7%C3%A3o%20est%C3%A1%20temporariamente%20indispon%C3%ADvel. ``` br ## 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) br ## Guias da Plataforma 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