cursor en las listas, page_token en las lecturas de transacciones).
Los importes son cadenas decimales con un campo currency ISO 4217 independiente, las fechas siguen ISO 8601 y los países usan ISO alpha-3.
Las lecturas nunca se facturan.
Cuentas
GET /v3/bank/connections/{id}/accounts/ lista las cuentas de una conexión, y GET /v3/bank/accounts/{account_id}/ devuelve una.
Usa
account_ref para reconocer una cuenta bancaria cuando una persona la conecta de nuevo, e id para todo lo que esté dentro de una misma conexión.
Saldos
GET /v3/bank/accounts/{account_id}/balances/ devuelve los saldos clasificados por tipo, con sus fechas de referencia.
type toma uno de los valores booked, available o expected, y iso_type contiene el código ISO 20022 del banco cuando este lo proporciona.
Transacciones
GET /v3/bank/accounts/{account_id}/transactions/ lee un rango de fechas.
Acepta date_from y date_to (fechas de calendario tal como las informa el banco, ambas incluidas), status (booked o pending, ambos por defecto), limit (hasta 500) y page_token.
Ordena por effective_date descendente y, después, por id.
ides de Didit y se almacena en el primer momento en que aparece. El mismo movimiento conserva su id entre lecturas, sincronizaciones y renovaciones.identity_qualityindica la solidez de esa garantía.bank_referenceyroute_idson estables.derivedsignifica que el movimiento se emparejó por su contenido, de modo que una corrección del banco puede aparecer como unremovedy unadded.statusesbookedopending. Una transacción pendiente tiene su propio id. Cuando el banco la contabiliza, la transacción contabilizada llega comoaddedy la pendiente comoremovedconreason: pending_booked;pending_idsolo se informa cuando el banco vincula ambas.amountlleva signo: un valor negativo es dinero que sale.directionrepite el signo.bank_referencees la referencia inmutable del asiento que asigna el banco, y esnullcuando el banco no la proporciona. Didit nunca la inventa.categoryes la categorización propia de Didit, cuando corresponde.- Una corrección del banco sobre una transacción contabilizada aparece como
modified. Una anulación es una transacción nueva, conreverses_idcuando el banco la vincula.
Los campos que un banco no envía son null
Todo campo que un banco no envía se devuelve comonull.
La entidad enumera los campos que sabe que envía en transaction_fields, junto con pending_transactions, pending_linkage, balance_types e history_days_max, para que nadie descubra huecos en producción.
Usa el cliente de prueba sparse_fields del sandbox para probar tu código con un banco que envía pocos datos.
Paginar un rango de fechas
Sigue leyendo conpage_token mientras has_more sea true.
El token fija la instantánea de la lectura durante una hora: las adiciones posteriores a la primera página no están incluidas, cada fila se sirve en su estado actual, y una fila eliminada durante la paginación deja de aparecer en las páginas siguientes y sí aparece en el feed de cambios.
Un token expirado responde 410 page_expired: reinicia la lectura desde su consulta original.
El flujo de cambios
GET /v3/bank/connections/{id}/transactions/sync/ devuelve lo que ha cambiado en todas las cuentas de una conexión desde un cursor.
- Un cursor vacío devuelve todas las transacciones actuales como
addedconreset: true. Sustituye tu copia por esos datos en lugar de añadirlos a ella. - Sigue paginando con
page_tokenmientrashas_moresea verdadero. Guardanext_cursorsolo después de una respuesta conhas_more: false, y si la paginación falla a mitad de camino, reinicia desde el cursor que guardaste. - Un cursor es opaco y está vinculado a la conexión y al entorno. El registro de cambios se puede reproducir durante 90 días. Un cursor más antiguo devuelve
410 cursor_expiredconbootstrap: true: vuelve a empezar desde un cursor vacío y sustituye tu copia. removed[].reasonespending_booked,pending_expired,bank_removedoaccess_removed.
Encabezados
Ambas lecturas de transacciones devuelven los encabezadosX-RateLimit-* (600 lecturas y 300 escrituras por minuto y por aplicación, y 429 con Retry-After cuando se superan esos límites) y X-Bank-Last-Synced-At.
Los límites de la API y los límites propios del banco para la obtención de datos son cosas distintas: consulta Actualizar datos bancarios bajo demanda.