# Modo de Actualización del Hosted Widget

Puedes usar el Hosted Widget de Belvo para actualizar un link que requiere una nueva contraseña o un nuevo token MFA. Necesitarás actualizar un link si:

- La institución requiere un nuevo token MFA para iniciar sesión.
- El usuario ha cambiado la contraseña conectada con el Link.


## Flujo de Actualización

El flujo general para actualizar un enlace con el widget es:

1. Recibes un error de enlace desde la API o un webhook.
2. Solicitas a tu usuario dentro de tu aplicación que actualice sus credenciales o proporcione un nuevo token de autenticación.
3. Una vez que inician el proceso de actualización, realizas una llamada desde el servidor a nuestro endpoint `/api/token/` para generar un `access_token`, proporcionando el `link_id` del usuario.

```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. Luego inicias el widget con el `access_token` que acabas de generar. Debido a que proporcionaste el `link_id`, detectamos qué tipo de actualización de enlace necesita ser activada (token o credenciales) y guiamos al usuario a través del proceso. Una vez que proporcionan exitosamente sus credenciales o token de autenticación, establecemos el estado del enlace como `valid`.


¡Listo! Una vez que un enlace se actualiza exitosamente, el enlace es `valid` nuevamente y el `link_id` permanece igual.

Si el enlace actualizado exitosamente es recurrente, automáticamente activamos una actualización histórica del enlace, notificándote a través de webhook de cualquier dato nuevo.

## ¿Cómo sé si un enlace necesita ser actualizado?

Un enlace necesitará ser actualizado en los siguientes escenarios:

**Escenario 1: recibes un error de la API**
Al realizar una llamada POST a nuestra API, puedes recibir errores que significan que el enlace necesita ser actualizado:

| Respuesta | Código de error | Razón |
|  --- | --- | --- |
| 400 | `invalid_link` | El enlace ha sido invalidado debido a varios errores de inicio de sesión. |
| 428 | `token_required` | La institución requiere un token MFA para iniciar sesión. |


**Escenario 2: recibes un error de webhook para un enlace recurrente**
Durante la actualización diaria de tus enlaces recurrentes, enviaremos un evento en caso de que uno de tus enlaces necesite ser actualizado para ser refrescado.

| Evento | Razón |
|  --- | --- |
| `invalid_credentials` | Cada vez que no podemos refrescar un enlace recurrente debido a credenciales inválidas. |
| `token_required` | Siempre que necesitemos un nuevo token MFA para refrescar el enlace recurrente. |


# ¿Cómo puedo saber qué enlaces necesitan ser actualizados?

Utiliza la solicitud de API List all Links con el parámetro de consulta `status` configurado en `invalid` o `token_required` (ver el ejemplo a continuación). Si se devuelven enlaces, esos son los que necesitan ser actualizados.


```curl Obtener todos los enlaces que necesitan ser actualizados
# enlaces inválidos
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://sandbox.belvo.com/api/links/?status=invalid

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