Refresh Intents

Por qué existen

Rail corre syncs automáticos cada 4h por cada link. Pero a veces el cliente quiere forzar un sync ya — por ejemplo cuando el user abre la app y quiere ver lo más reciente. Un refresh intent representa ese deseo de sync on-demand. Su ID es ri_ + 16 chars hex.

{
  "object": "refresh_intent",
  "id": "ri_a1b2c3d4e5f6a7b8",
  "link_id": "link_8a2f4c6e1b9d5037",
  "status": "succeeded",
  "refresh_type": "full",
  "requires_mfa": null,
  "created_at": "2026-06-03T15:00:00Z",
  "started_at": "2026-06-03T15:00:01Z",
  "completed_at": "2026-06-03T15:00:45Z",
  "error_code": null
}

Crear

curl https://api.rail.cl/v1/refresh_intents \
  -X POST \
  -H "Authorization: Bearer rail_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "link_id": "link_xxx",
    "refresh_type": "full"
  }'

refresh_type:

full — todas las cuentas, todos los movs (default).
historical — incluye movs viejos (60+ días).
only_last — solo cuentas (skip movs). Más rápido.

Lifecycle

`status`	Significa
`created`	Encolado. Aún no empezó.
`in_progress`	El worker está syncando.
`requires_mfa`	El banco pidió MFA. Ver abajo.
`succeeded`	Sync terminado OK.
`failed`	Sync falló. Ver `error_code`.

MFA async

Algunos bancos (Santander, BCI a veces) piden MFA en cada sync. Cuando eso pasa:

El intent queda en status: requires_mfa.
El campo requires_mfa.widget_token contiene un ri_{intentId}_sec_… listo para abrir el widget.
Tu frontend abre el widget con ese token.
User resuelve el MFA dentro del widget.
El widget cierra, el sync continúa server-side.
El intent pasa a succeeded o failed.

{
  "object": "refresh_intent",
  "id": "ri_xxx",
  "status": "requires_mfa",
  "requires_mfa": {
    "widget_token": "ri_xxx_sec_abc123…",
    "expires_at": "2026-06-03T15:10:00Z"
  }
}

Polling vs Webhooks

Dos formas de saber cuándo termina:

Polling

curl https://api.rail.cl/v1/refresh_intents/ri_xxx \
  -H "Authorization: Bearer rail_sk_live_…"

Cada 5-10 segundos hasta que status sea succeeded, failed o requires_mfa.

Webhooks (recomendado)

Suscríbete a los eventos refresh_intent.succeeded, refresh_intent.failed, refresh_intent.requires_mfa. Ver Guías → Webhooks.

Cooldown y deduplicación

Cooldown 5min: si pediste un intent para un link, no puedes pedir otro full hasta 5min después. Para only_last no hay cooldown.
Unique in-progress: solo puede haber 1 intent activo por link a la vez. Si pides otro, te devolvemos el existente.

# Si ya hay uno in_progress, devuelve ese (no crea otro)
curl https://api.rail.cl/v1/refresh_intents \
  -X POST \
  -d '{"link_id": "link_xxx", "refresh_type": "full"}'
# → 200 con el intent activo, no 201

Error codes comunes

`error_code`	Significa
`bank_unavailable`	El banco está caído o muy lento. Reintentar en 10min.
`rejected_credentials`	Clave o RUT inválido. El user debe re-conectar.
`requires_mfa_user_timeout`	Se emitió `wt_*` pero el user no resolvió en 10min.
`bank_format_change`	El banco cambió su HTML y nuestro parser rompió. Rail está sobre eso.

Empezar

Conceptos

Guías

Refresh Intents

Por qué existen

Crear

Lifecycle

MFA async

Polling vs Webhooks

Polling

Webhooks (recomendado)

Cooldown y deduplicación

Error codes comunes

​Por qué existen

​Crear

​Lifecycle

​MFA async

​Polling vs Webhooks

​Polling

​Webhooks (recomendado)

​Cooldown y deduplicación

​Error codes comunes

Por qué existen

Crear

Lifecycle

MFA async

Polling vs Webhooks

Polling

Webhooks (recomendado)

Cooldown y deduplicación

Error codes comunes