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 esacc_ + 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
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
Parachecking 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.
credit_card y line_of_credit:
available: cupo disponible (limit − current).current: lo utilizado, en positivo.limit: cupo total.
loan:
current: deuda vigente, en positivo.
investment:
current: valor del producto hoy (capital + interés devengado, o valor de mercado).available: lo que el titular puede retirar hoy —0en un depósito a plazo y en un APV,= currenten un fondo mutuo, acciones o la caja del corredor.limit:nullsiempre (un producto de captación no tiene cupo).
Estado de cuenta de la tarjeta
Una cuentacredit_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 Z”. Con esto tu app lo muestra sin que la persona
entre al banco.
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ó.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
Unaline_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.
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 cuentastype: "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).
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 vs link_status
status= estado de esta cuenta específica.link_status= estado del link padre (replicado por conveniencia).
Para incluir las
removed: agrega ?include_removed=true.
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.