# 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. Gerenciar 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 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