Estados de banco

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

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.

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:

{
  "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 → grupo Instituciones, o agregándolos al array events del webhook endpoint.

{
  "type": "institution.status_changed",
  "data": {
    "bank_id": "banco_chile",
    "status": "paused",
    "previous_status": "available",
    "reason": "...",
    "resumes_at": null,
    "affected_link_ids": ["link_a1b2c3"]
  }
}

{
  "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"]
  }
}

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).

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.

Empezar

Conceptos

Guías

Estados de banco

Estado del link ≠ estado del banco

Estados del banco

Dónde consultarlo

Pull — al renderizar (fuente de verdad)

Push — tiempo real

UX sugerida en la tarjeta

​Estado del link ≠ estado del banco

​Estados del banco

​Dónde consultarlo

​Pull — al renderizar (fuente de verdad)

​Push — tiempo real

​UX sugerida en la tarjeta

Estado del link ≠ estado del banco

Estados del banco

Dónde consultarlo

Pull — al renderizar (fuente de verdad)

Push — tiempo real

UX sugerida en la tarjeta