> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rail.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Estados de banco

> Mostrá en tus conexiones cuándo un banco está en mantención o pausado, sin confundirlo con un link roto.

Un banco puede quedar **temporalmente fuera** (mantención programada) o **pausado** por
Rail (por un incidente operativo). Eso es distinto de que el *link* de un usuario esté
roto. Esta guía es para mostrar el estado del **banco** en tus **conexiones ya
existentes**. El flujo de conexión nueva lo maneja el widget.

## Estado del link ≠ estado del banco

<Warning>
  Durante una mantención o pausa, **`link.status` sigue `active`** — las credenciales
  del usuario están bien, el banco es el que no está disponible. **No dispares un
  reconnect** en estos casos: no es problema del usuario.
</Warning>

| Campo                                                                                    | Qué es                                 | ¿Requiere acción del usuario? |
| ---------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| `link.status` (`active` / `failed` / `credentials_invalid` / `mfa_required` / `expired`) | Salud del **link** (credenciales, MFA) | **Sí**                        |
| `link.institution.status`                                                                | Estado del **banco**                   | **No** — el link sigue sano   |

## Estados del banco

En `link.institution.status`:

| status        | Significa                                       | Campo extra                                                |
| ------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| `available`   | Normal                                          | —                                                          |
| `paused`      | Pausa temporal (mantención de Rail / incidente) | `institution.resumes_at` (ISO, opcional)                   |
| `maintenance` | Ventana de mantención programada del banco      | `institution.maintenance` = `{ starts_at, ends_at, note }` |
| `disabled`    | No disponible (más permanente)                  | —                                                          |

## Dónde consultarlo

Usá las **dos** vías: el recurso como fuente de verdad y los webhooks para tiempo real.

### Pull — al renderizar (fuente de verdad)

`GET /v1/links` o `GET /v1/links/{id}`. Cada link trae el estado del banco embebido:

```json theme={null}
{
  "id": "link_a1b2c3",
  "status": "active",
  "last_sync_at": "2026-07-29T12:00:00Z",
  "institution": {
    "id": "cl_banco_chile",
    "name": "Banco de Chile",
    "status": "maintenance",
    "resumes_at": null,
    "maintenance": {
      "starts_at": "2026-07-29T10:00:00Z",
      "ends_at": "2026-07-29T14:30:00Z",
      "note": "Mantención de canales digitales"
    }
  }
}
```

### Push — tiempo real

Dos webhooks (opt-in). Ambos traen `affected_link_ids` para saber qué links tuyos
tocar. Suscribilos en el [dashboard](https://dashboard.rail.cl/developers/webhooks) →
grupo **Instituciones**, o agregándolos al array `events` del webhook endpoint.

<CodeGroup>
  ```json institution.status_changed theme={null}
  {
    "type": "institution.status_changed",
    "data": {
      "bank_id": "banco_chile",
      "status": "paused",
      "previous_status": "available",
      "reason": "...",
      "resumes_at": null,
      "affected_link_ids": ["link_a1b2c3"]
    }
  }
  ```

  ```json institution.maintenance_scheduled theme={null}
  {
    "type": "institution.maintenance_scheduled",
    "data": {
      "bank_id": "banco_chile",
      "starts_at": "2026-07-29T10:00:00Z",
      "ends_at": "2026-07-29T14:30:00Z",
      "note": "Mantención de canales digitales",
      "affected_link_ids": ["link_a1b2c3"]
    }
  }
  ```
</CodeGroup>

<Note>
  El push es best-effort: puede no llegar (endpoint caído, un link nuevo durante la
  pausa no recibe evento retroactivo, `affected_link_ids` es un snapshot). Por eso:
  al **abrir** la vista mostrá lo que dice `link.institution.status` (pull, siempre
  exacto); mientras está **abierta**, actualizá en vivo con los webhooks (push).
</Note>

## UX sugerida en la tarjeta

| status        | Copy                                                           | CTA |
| ------------- | -------------------------------------------------------------- | --- |
| `paused`      | "Banco en mantención" (+ "vuelve \~HH:MM" si hay `resumes_at`) | —   |
| `maintenance` | "Banco en mantención hasta HH:MM" (`maintenance.ends_at`)      | —   |
| `disabled`    | "Banco no disponible por ahora"                                | —   |

En los tres: **sin botón de reconexión**. El link está sano; los datos se actualizan
solos cuando el banco vuelve.