# 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


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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "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
```json 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/",
      "company_terms_version": "2024-03-15"
    },
    "theme": [] // See our dedicated widget customization article
  }
}
```

br
## Iniciando o widget

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

```text Exemplo de URL do Hosted Widget
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.

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), consulte nosso artigo **Configuração de Inicialização do Widget (Multi-Região)**.

## 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 **sucesso**, **saída** e **erro**. A estrutura do deep link é:

```text Exemplo de Estrutura de Deeplink
your-url-here://event_name?parameters
```

| Parâmetro | Descrição |
|  --- | --- |
| `your-url-here` | Seu manipulador de deeplink (esquema) |
| `event_name` | O nome do evento (host) |
| `parameters` | Os parâmetros do evento (enviados como query strings) |


### Evento de sucesso

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).

```text Exemplo de Evento de Sucesso
your-url-here://success
  ?link={id}}
  &institution={institution_name}

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

| Parâmetro  | Descrição | Exemplo  |
|  --- | --- | --- |
| `link` | O ID do link (UUID) para o usuário. Você precisará deste ID para poder fazer solicitações adicionais para o usuário. | `cb65f82c-dc93-4d3e-8270-9a27528397f5` |
| `institution` | A instituição com a qual o link foi criado. | `erebor_br_retail` |


### Evento de saída

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.


```text Exemplo de Evento de Saída
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
```

#### last_encountered_error

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.

| 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` | 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

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.

| Parâmetro  | Descrição | Exemplo  |
|  --- | --- | --- |
| `step` | Enviado quando o usuário sai do widget na tela inicial. O valor do parâmetro é sempre `abandon-survey`. | `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. | `ofmockbank_br_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
```

### Evento de erro

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

```text Exemplo de Evento de Erro
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.

| Código de erro | Mensagem de erro (URL-Encoded) |
|  --- | --- |
| `ACCESS_TOKEN_NOT_VALID` | The access token was not provided or is not valid |


### Evento de aviso

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

```text Exemplo de Evento de Aviso
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.

| Código de aviso | Mensagem de aviso (URL-Encoded) |
|  --- | --- |
| `institution_disabled` | The institution is temporarily unavailable. |


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