Transacciones y Operaciones

Registrar un movimiento de dinero en Fidi X es siempre un acto de dos partes. Por un lado está la transacción — el evento financiero en sí, que agrupa todo lo que ocurrió. Por otro están las operaciones — los movimientos contables individuales que materializan ese evento sobre cada cuenta.

Esta separación no es arbitraria. Refleja el principio de partida doble: todo lo que sale de un lado tiene que entrar por otro. Una transacción sin al menos dos operaciones balanceadas no puede existir en Fidi X.

La transacción como evento financiero

Una transacción representa un hecho financiero completo — un cash in, una transferencia entre usuarios, un cash out. Tiene un monto total, una moneda, un tipo, y un conjunto de operaciones que deben estar balanceadas antes de que el sistema la acepte.

Fidi X soporta tres tipos de transacción:

CASH_IN — entrada de fondos al ledger desde el exterior. Representa el momento en que dinero externo ingresa al sistema y se acredita en una cuenta. Ejemplo: un usuario carga saldo desde su cuenta bancaria.

TRANSFER — movimiento de fondos entre cuentas dentro del mismo ledger. El dinero no entra ni sale del sistema — se redistribuye internamente. Ejemplo: un usuario envía dinero a otro usuario.

CASH_OUT — salida de fondos del ledger hacia el exterior. Representa el momento en que dinero sale del sistema desde una cuenta. Ejemplo: un usuario retira saldo a su cuenta bancaria.

Una vez que una transacción es registrada y su estado es posted, es inmutable — no puede modificarse ni eliminarse. Si se necesita revertir un movimiento, la forma correcta es crear una nueva transacción con las direcciones invertidas.

Las operaciones como asientos contables

Cada operación es un movimiento individual sobre una cuenta específica — un débito o un crédito, por un monto determinado, en una moneda determinada. Las operaciones son el detalle contable de la transacción.

Una transacción válida en Fidi X requiere siempre al menos dos operaciones, y la suma de todos los débitos debe ser igual a la suma de todos los créditos. Si no se cumple esa condición, la transacción es rechazada.

Las operaciones no se crean de forma independiente — nacen como parte de una transacción. Una vez registradas, también son inmutables.

Cómo se relacionan transacción y operación

La transacción es la unidad de consulta y auditoría — es lo que se busca cuando se quiere saber qué ocurrió. Las operaciones son la unidad contable — son lo que impacta los saldos de las cuentas.

Cuando se crea una transacción, la respuesta confirma que fue registrada exitosamente — pero no incluye el detalle de las operaciones contables asociadas. Las operaciones se consultan de forma independiente a través del endpoint de Listar Operaciones, usando el transaction_id como filtro.

Este diseño es intencional: la transacción es la unidad de negocio, y las operaciones son el detalle contable. Separarlos permite consultar cada uno según la necesidad — el estado de un pago versus el detalle de cómo impactó cada cuenta.

El flujo típico es:

Crear la transacción → obtener el transaction_id de la respuesta

Consultar las operaciones usando ese transaction_id como filtro en Listar Operaciones

Idempotencia

Fidi X soporta idempotencia en la creación de transacciones a través del header idempotency-key. Si una misma transacción se envía más de una vez con la misma clave, el sistema retornará la transacción ya creada sin duplicarla. Esto es especialmente relevante en escenarios de reintentos por timeout o error de red.

La transacción como evento financiero#

Las operaciones como asientos contables#

Cómo se relacionan transacción y operación#

Idempotencia#

La transacción como evento financiero

Las operaciones como asientos contables

Cómo se relacionan transacción y operación

Idempotencia