Este artigo refere-se ao hosted widget multi-região
O conteúdo deste artigo refere-se ao hosted widget multi-região (aplicável para o México). Se você deseja operar no Brasil, por favor veja nosso Connect Widget para OFDA Regulamentado.

Você pode usar o Connect 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 requer um novo token MFA para fazer login.
- O usuário alterou a senha conectada ao Link.


br

# Fluxo de atualização do Connect Widget

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

1. Você recebe um erro de link.
2. Você solicita dentro do seu aplicativo para o seu usuário atualizar suas credenciais ou fornecer um novo token de autenticação. Por exemplo, exibindo um botão de Atualizar para que ele clique.
3. Assim que eles iniciarem o processo de atualização, você faz uma chamada do seu lado do servidor para gerar um `access_token`, fornecendo o `link_id` do usuário. Veja o exemplo de código abaixo.



```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"
  }'
```

1. Inicie o widget e o usuário atualiza seu link
Como você fornece 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 ele fornecer com sucesso suas credenciais ou token de autenticação, definimos o status do link como `valid`.


✳️ Feito! Assim que um link recorrente for atualizado com sucesso, o status do link será `valid` novamente e o `link_id` permanecerá o mesmo. Você receberá uma resposta de callback de Sucesso no widget.

Se o link atualizado com sucesso for recorrente, acionamos automaticamente uma atualização do link. Se encontrarmos dados novos, você receberá webhooks de atualização histórica.

> ❗️ O que acontece se houver um erro ao atualizar o link?
Você continuará recebendo callbacks de sucesso e erro no widget como de costume. O
status do link não será `valid` novamente até que seja atualizado com sucesso.


# Como saber 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?

Usando List all Links e verificando o status do link, você pode ver quais links precisam ser atualizados pelos seus usuários.
Se o status do link for `invalid` ou `token_required`, ele precisa ser atualizado.

Por exemplo:


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


```curl
curl -u SECRET_ID:SECRET_PASSWORD  \
https://sandbox.belvo.com/api/links/[LINK ID]/
```


```curl
curl -u SECRET_ID:SECRET_PASSWORD  \
https://sandbox.belvo.com/api/links/
```

# Como posso testar o widget no modo de atualização?

Use a instituição Heimdall em nosso ambiente sandbox. Após registrar um link com a instituição, qualquer chamada POST adicional feita para a instituição retornará uma resposta 428 Token Required, onde o status do link será alterado para `token_required`.

Então, tudo o que você precisa fazer é passar o `link_id` quando iniciar o widget, e quando você fornecer com sucesso as credenciais necessárias, o status do link será atualizado para `valid` novamente.