# Modo de Atualização do Hosted Widget

Você pode usar o Hosted Widget da Belvo para atualizar um link que requer uma nova senha ou um novo token MFA. Você precisará atualizar um link se:

- A instituição exigir um novo token MFA para fazer login.
- O usuário tiver alterado a senha conectada ao Link.


## Fluxo de Atualização

O fluxo geral de atualização de um link com o widget é:

1. Você recebe um erro de link da API ou de um webhook.
2. Você solicita ao seu usuário dentro do seu aplicativo que atualize suas credenciais ou forneça um novo token de autenticação.
3. Assim que eles iniciarem o processo de atualização, você faz uma chamada do lado do servidor para nosso endpoint `/api/token/` para gerar um `access_token`, fornecendo o `link_id` do usuário.

```curl
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d '{
    "id": "SECRET_ID",
    "password": "SECRET_PASSWORD",
    "link_id": "LINK_ID",
    "scopes": "read_institutions,write_links,read_links"
  }'
```
4. Você então inicia o widget com o `access_token` que acabou de gerar. Como você forneceu o `link_id`, detectamos qual tipo de atualização de link precisa ser acionada (token ou credenciais) e guiamos o usuário pelo processo. Assim que eles fornecerem com sucesso suas credenciais ou token de autenticação, definimos o status do link como `valid`.


Pronto! Assim que um link é atualizado com sucesso, o Link é `valid` novamente e o `link_id` permanece o mesmo.

Se o Link atualizado com sucesso for recorrente, acionamos automaticamente uma atualização histórica do link, notificando você via webhook sobre quaisquer novos dados.

## Como sei se um link precisa ser atualizado?

Um link precisará ser atualizado nos seguintes cenários:

**Cenário 1: você recebe um erro da API**
Ao fazer uma chamada POST para nossa API, você pode receber erros indicando que o link precisa ser atualizado:

| Resposta | Código de erro | Motivo |
|  --- | --- | --- |
| 400 | `invalid_link` | O link foi invalidado devido a vários erros de login. |
| 428 | `token_required` | Um token MFA é necessário pela instituição para fazer login. |


**Cenário 2: você recebe um erro de webhook para um link recorrente**
Durante a atualização diária dos seus links recorrentes, enviaremos um evento caso um dos seus links precise ser atualizado para ser atualizado.

| Evento | Motivo |
|  --- | --- |
| `invalid_credentials` | Toda vez que não pudermos atualizar um link recorrente devido a credenciais inválidas. |
| `token_required` | Sempre que precisarmos de um novo token MFA para atualizar o link recorrente. |


# Como posso saber quais links precisam ser atualizados?

Use a solicitação da API Listar todos os Links com o parâmetro de consulta `status` definido como `invalid` ou `token_required` (veja o exemplo abaixo). Se algum link for retornado, esses são os que precisam ser atualizados.


```curl Obter todos os links que precisam ser atualizados
# links inválidos
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://sandbox.belvo.com/api/links/?status=invalid

# links que requerem token
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://sandbox.belvo.com/api/links/?status=token_required
```