Fidi X - APIS Core Wallet
✨ Introducción#
Bienvenido a la documentación técnica de FIDI X, la plataforma de ledger y procesamiento contable diseñada para soportar productos financieros modernos de forma consistente, trazable e idempotente.FIDI X provee un conjunto de APIs que permiten a los sistemas integradores configurar su modelo contable y registrar transacciones financieras, todo de manera segura, auditable y escalable, actuando como el núcleo contable sobre el cual se construyen distintos flujos de negocio y productos financieros.Esta documentación tiene como objetivo entregar a los equipos técnicos una visión clara de la lógica de uso, las dependencias entre los distintos componentes del dominio, y las reglas operativas y técnicas que deben considerarse para una correcta integración con la plataforma.
⚙️ Lógica General de Uso#
La integración con FIDI X sigue una lógica secuencial basada en principios contables y de consistencia de dominio.
Antes de ejecutar operaciones financieras, es necesario configurar correctamente el contexto contable sobre el cual se procesarán las transacciones.De forma general, el flujo de uso de la plataforma se compone de las siguientes etapas:
🔐 1. Autenticación y trazabilidad#
Toda interacción con las APIs de FIDI X requiere un contexto de autenticación válido, basado en OAuth 2.0 y el uso de Access Tokens JWT emitidos por el proveedor de identidad.Para cada request es obligatorio:🔑 Incluir un Access Token JWT válido en el header Authorization
🧵 Enviar el header traceparent para habilitar trazabilidad distribuida
traceparent garantiza 🔎 trazabilidad end-to-end y observabilidad completa del flujo transaccional a lo largo de la plataforma.📌 En esta versión, la autenticación valida únicamente la identidad del consumidor de la API.
Las reglas de autorización y control de permisos serán incorporadas en versiones posteriores.
🏗️ 2. Configuración del dominio contable#
Antes de poder procesar cualquier transacción, es necesario preparar el dominio contable definiendo sus componentes fundamentales y sus responsables.En una primera etapa, Fidi establece el marco contable sobre el cual operará el sistema, proveyendo los servicios necesarios para su administración:Crea la organización, que actúa como contenedor lógico del dominio, y entrega su identificador al cliente para que pueda operar sobre ella.
Crea y configura el ledger, que define el libro contable principal y el límite de consistencia.
El identificador del ledger es proporcionado al cliente, quien lo utiliza como referencia en sus transacciones.
Crea los assets, que representan los instrumentos de valor (monedas, criptoactivos, puntos).
Registra personas o entidades que participarán en las operaciones.
Crea las cuentas, donde se mantienen y operan los saldos asociados a cada asset y persona.
💸 3. Ejecución de transacciones#
Una vez configurado el dominio, se pueden registrar Transactions, las cuales representan la instrucción contable inmutable que origina los movimientos de saldo dentro de las cuentas del ledger.El procesamiento de transacciones en FIDI X garantiza:Idempotencia ante reintentos.
Consistencia mediante partida doble.
Atomicidad en la actualización de balances.
Trazabilidad completa para auditoría y conciliación.
Publicación de eventos de dominio para procesamiento asíncrono posterior.
⚠️ Consideraciones Importantes#
Todos los servicios de FIDI X requieren autenticación previa y trazabilidad obligatoria.
La secuencia de uso de los servicios debe respetar la lógica del dominio contable.
No es posible crear transacciones sin un ledger, assets y cuentas previamente configurados.
FIDI X prioriza la consistencia y la integridad contable por sobre la ejecución parcial de operaciones.
Las reglas de negocio están desacopladas de los detalles técnicos, siguiendo principios de Arquitectura Hexagonal.
📘 En las siguientes secciones de esta documentación encontrarás el detalle técnico de cada API disponible, incluyendo:Ejemplos de request y response
Buenas prácticas para una integración segura y consistente con FIDI X
Modificado en 2025-12-24 02:37:45
