Skip to main content

Qué es una cuenta

Una cuenta representa un producto bancario específico bajo un link. Un link típicamente tiene varias cuentas: CuentaRUT + Vista + tarjeta + ahorro, por ejemplo. Su ID es acc_ + 16 chars hex.
statement sólo viene poblado en credit_card con estado de cuenta disponible (ver Estado de cuenta de la tarjeta más abajo) y investment sólo en type: "investment" (ver Productos de inversión). En el resto de las cuentas van en null.

Tipos

El enum puede crecer cuando sumamos un producto nuevo. Si haces switch (type), deja siempre un default — no asumas que la lista está cerrada para siempre.
other no es un caso raro. Es el fallback explícito del enum y hoy varias instituciones tienen cuentas ahí (Santander, Scotiabank, Itaú, BancoEstado): son productos que todavía no clasificamos, no cuentas vacías. No las descartes — suelen tener saldo; usa name y official_name para mostrar de qué producto se trata.

Balance

Para checking y savings:
  • available: lo que el user puede gastar ya (puede incluir línea de crédito).
  • current: saldo contable (sin líneas).
  • limit: null.
Para credit_card y line_of_credit:
  • available: cupo disponible (limit − current).
  • current: lo utilizado, en positivo.
  • limit: cupo total.
Para loan:
  • current: deuda vigente, en positivo.
Para investment:
  • current: valor del producto hoy (capital + interés devengado, o valor de mercado).
  • available: lo que el titular puede retirar hoy — 0 en un depósito a plazo y en un APV, = current en un fondo mutuo, acciones o la caja del corredor.
  • limit: null siempre (un producto de captación no tiene cupo).
Todos los valores son bigint en minor units. Para CLP eso = pesos sin decimal. Para USD/EUR eso = centavos.

Estado de cuenta de la tarjeta

Una cuenta credit_card puede traer el bloque statement: el estado de cuenta del último período cerrado, o sea lo que al titular le llega como “paga XantesdeldıˊaY,elmıˊnimoesX antes del día Y, el mínimo es Z”. Con esto tu app lo muestra sin que la persona entre al banco.
billing_date y due_date no son lo mismo. En el ejemplo el período cerró el 5 de junio y se paga hasta el 20 de junio: si usas billing_date como fecha de pago, le avisas al usuario 15 días antes de lo que corresponde (y le muestras la cuenta como vencida cuando no lo está).
statement va sólo en type: "credit_card" y sólo cuando hay estado de cuenta del período cerrado. Es null en cuentas vista, ahorro, línea de crédito e inversión, y también en una tarjeta que todavía no facturó.
Una tarjeta bimoneda llega como dos cuentas (una CLP, otra USD) y cada una trae el estado de cuenta de su moneda: el nacional y el internacional se facturan por separado. Cobertura: hoy sólo Banco de Chile (personas) entrega estado de cuenta. En el resto de las instituciones statement viene null, aunque el banco sí lo muestre en su portal.

Tarjetas: agrupar por línea de crédito

Un usuario puede tener varios plásticos sobre la misma línea de crédito (por renovación: un plástico vence o se bloquea y el banco emite otro con distinta numeración). Todos reportan el mismo cupo y el mismo saldo: son la misma deuda. Sumar los plásticos cuenta esa deuda varias veces. credit_line_id es la clave para evitarlo: todos los plásticos —y las dos monedas (CLP/USD)— de la misma línea comparten el mismo valor. Agrupá por (credit_line_id, currency) y tomá un representante: ese es el saldo real de la línea, contado una vez.
credit_line_id es un id opaco y estable (no el número de cuenta). También une las dos monedas de una tarjeta: la CLP y la USD comparten credit_line_id, así no tenés que parsear el name para saber que son la misma. card_lifecycle dice por qué un plástico ya no viene en el sync, para no leer una renovación como una tarjeta duplicada: Se deriva del conjunto de cuentas del link, así que viene sólo en la lista (GET /v1/accounts); en el detalle de una cuenta suelta es null.
credit_line_id se puebla en BCI, Santander y Banco de Chile; en los demás viene null (seguí infiriendo por institution + type + last_4 ahí). card_lifecycle viene en cualquier banco con tarjetas. Los dos son sólo para type: "credit_card".

Línea de crédito

Una line_of_credit no es una tarjeta de crédito, aunque comparta la semántica de balance (current = utilizado, limit = cupo, available = disponible): no tiene plástico ni estado de cuenta con fecha de vencimiento, así que su statement es siempre null. Si la renderizas como una tarjeta, le muestras al usuario un producto que no tiene. Cobertura, y no está pareja: hoy la emiten Banco Falabella, Itaú (personas y empresa), Scotiabank (cuentas de empresa) y Banco de Chile (recién cableado — aparece a partir del próximo sync de cada link). Las demás instituciones no la emiten.
Que Rail no emita la línea de crédito de un banco no significa que ese banco no ofrezca el producto. En Banco de Chile la línea existió siempre y la descartaba un filtro de nuestro parser hasta el 2026-10-13. Si te falta la línea de una institución, escríbenos: suele ser un producto que todavía no leemos, no uno que no exista.
Según el banco, la línea puede no tener movimientos propios: en Banco de Chile y en Scotiabank empresa sus giros salen en la cartola de la cuenta corriente. Banco Falabella sí entrega los giros de sobregiro en la cuenta de la línea.

Productos de inversión

Las cuentas type: "investment" pueden traer un bloque investment con lo invertido, lo ganado, las cuotas, el valor cuota y a qué día corresponde esa valorización (que no es la fecha del sync).
Tres cosas antes de integrarlo: units, unit_price, gain_pct y rate son strings decimales (no números), priced_at no es refreshed_at, y una cuenta de inversión no tiene movimientos. Todo el detalle en Productos de inversión.

Listar

  • status = estado de esta cuenta específica.
  • link_status = estado del link padre (replicado por conveniencia).
Para incluir las removed: agrega ?include_removed=true.
Filtrar por removed_from_link sobre la respuesta normal no hace nada. Las cuentas removidas quedan fuera del result set por default, así que en esa respuesta el campo siempre vale false. Si querés detectar cierres, tenés que pedir ?include_removed=true — si no, lo único que ves es que la cuenta dejó de aparecer.
Con ?include_removed=true llegan todas las removidas del link, sin ventana de tiempo ni paginación: nada las borra ni las archiva. La única forma de que desaparezcan es que se elimine el link completo.

El cierre es reversible

removed no es terminal. Si la cuenta vuelve a aparecer en un sync siguiente, Rail limpia el tombstone y vuelve a active. Pasa cuando el banco tiene un pestañeo, o cuando un producto deja de responder un día y vuelve al otro. Por eso, si usás removed para saltear cuentas en tu propia ingesta, leelo en cada sync en vez de guardarlo como estado final: una cuenta que diste de baja puede revivir, y si la saltás para siempre te vas a perder sus movimientos nuevos.

En cuentas removidas, mirá refreshed_at, no last_sync_at

En una cuenta removida, los campos de frescura del link —last_sync_at, next_sync_at, link_status— siguen el ritmo del link, no del producto: el link sigue sincronizando aunque esta cuenta ya no venga. El campo que dice la verdad por cuenta es refreshed_at: la última vez que Rail vio este producto en el banco. En removidas te lo damos también en last_sync_at (y next_sync_at en null), para que los tres coincidan; aun así, la regla simple es usar refreshed_at por cuenta para saber qué tan fresca es.