Transacciones - Lerian

Una Transacción en Midaz registra un evento financiero completo. Una transacción a menudo usa múltiples cuentas y saldos. Midaz funciona sobre un sistema de contabilidad de doble entrada que mantiene cada movimiento financiero equilibrado. Con la funcionalidad de múltiples saldos, cada operación especifica la cuenta y la clave de saldo a usar. Luego puedes debitar o acreditar diferentes saldos lógicos de la misma cuenta (por ejemplo, credit, operational o collateral).

Si no proporcionas una balanceKey, la transacción usa el saldo predeterminado.

Contabilidad de doble entrada

El sistema de doble entrada sigue un principio. Cada transacción tiene dos entradas: un débito y un crédito. Esta estructura registra toda la actividad financiera y mantiene tus cuentas equilibradas. Cada transacción afecta dos cuentas y las mantiene equilibradas:

Los Débitos muestran el valor recibido o los recursos consumidos.
Los Créditos muestran el valor dado o los recursos proporcionados.

Midaz rastrea y equilibra cada débito y crédito automáticamente.

Ejemplo

En este ejemplo, transfieres R$ 1000 de una cuenta a otra. La transacción tiene dos operaciones:

Una operación para debitar R$ 1.000,00 de la cuenta de origen.
Una operación para acreditar R$ 1.000,00 a la cuenta de destino.

Midaz captura ambas entradas automáticamente. Puedes ver y analizar estos movimientos a través de la API o Lerian Console.

Transacciones N:N (Muchos a Muchos)

Los sistemas financieros tradicionales limitan las transacciones a relaciones uno a uno o uno a muchos. Midaz admite transacciones N:N. Una sola transacción puede usar múltiples cuentas de origen y destino.

Ejemplos

Pago de marketplace: una única cuenta de depósito en garantía paga a múltiples vendedores, y cada vendedor paga una comisión a la plataforma.
Peer-to-peer con comisiones: una transacción debita al pagador y acredita tanto al beneficiario como a una cuenta de comisiones.

Midaz procesa cada caso como una sola transacción atómica. Debita y acredita a todas las partes en conjunto.

Atomicidad e integridad

Las transacciones son atómicas. O todas las operaciones tienen éxito, o ninguna lo hace. No ocurren eventos financieros parciales. Si alguna parte de una transacción falla la validación — por ejemplo, una cuenta tiene fondos insuficientes — Midaz no aplica la transacción. El libro contable permanece consistente.

Origen de la transacción

Una transacción en Midaz puede comenzar desde un origen único o desde múltiples orígenes.

La suma de los valores en source debe ser igual al valor después de send. También debe ser igual a la suma de los valores en distribute.

Origen único

En una transacción de origen único, Midaz toma la cantidad de una cuenta de origen. También puedes indicar un saldo específico.

Ejemplo

En este ejemplo (Figura 1):

Midaz toma BRL 30,00 de @account1 (saldo credit).
Envía 100% a @destinationAccount1 (saldo operational)

Transacción de origen único que mueve BRL 30,00 desde una cuenta de origen a una única cuenta de destino — Figura 1. Ejemplo de una transacción de origen único.

Ejemplos de código

{
  "description": "transacción de origen único",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "credit", // opcional
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "balanceKey": "operational", // opcional
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Múltiples orígenes

En una transacción de múltiples orígenes, Midaz extrae fondos de múltiples cuentas o saldos.

Ejemplo

En este ejemplo (Figura 2):

Midaz envía BRL 30,00 a la cuenta de destino (@destinationAccount1).
- BRL 15,00 de @account1 (saldo default).
- BRL 15,00 de @account2 (saldo investment).
La cuenta de destino recibe el 100% de la cantidad.

Transacción de origen múltiple en la que se toman BRL 30,00 de dos cuentas de origen y se envían a una única cuenta de destino — Figura 2. Ejemplo de una transacción de múltiples orígenes.

Ejemplos de código

{
  "description": "transacción de múltiples orígenes",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "default",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        },
        {
          "accountAlias": "@account2",
          "balanceKey": "investment",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Destino de la transacción

Al igual que los orígenes, los destinos pueden ser únicos o múltiples.

Destino único

En una transacción de destino único, Midaz envía la cantidad a solo una cuenta de destino.

Ejemplo

En este ejemplo (Figura 3):

Midaz toma BRL 30,00 de una cuenta externa (@external/BRL).
Envía 100% a la cuenta de destino (@destinationAccount1).

Transacción de destino único que mueve BRL 30,00 desde una cuenta externa a una cuenta de destino — Figura 3. Ejemplo de una transacción de destino único.

Ejemplos de código

{
  "description": "transacción de destino único",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Múltiples destinos

En una transacción de múltiples destinos, Midaz divide la cantidad entre múltiples cuentas de destino. Puedes distribuir los valores por acciones, cantidades fijas o el saldo restante.

Ejemplo

En este ejemplo (Figura 4):

Midaz toma BRL 100 de la cuenta de origen (@account1).
38% de la cantidad va a la cuenta 2 (@account2).
50% va a la cuenta 3 (@account3).
Un BRL 2,00 fijo va a la cuenta 4 (@account4).
La cantidad restante va a la cuenta 5 (@account5).

Transacción de destino múltiple que reparte BRL 100,00 de una cuenta de origen entre cinco cuentas de destino por porcentajes e importes fijos — Figura 4. Ejemplo de una transacción de múltiples destinos.

Ejemplo de código

{
  "description": "transacción de múltiples destinos",
  "send": {
    "asset": "BRL",
    "value": "100.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "amount": {
            "asset": "BRL",
            "value": "100.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account2",
          "share": {
            "percentage": 38
          }
        },
        {
          "accountAlias": "@account3",
          "share": {
            "percentage": 50
          }
        },
        {
          "accountAlias": "@account4",
          "amount": {
            "asset": "BRL",
            "value": "2.00"
          }
        },
        {
          "accountAlias": "@account5",
          "remaining": "remaining"
        }
      ]
    }
  }
}

Múltiples orígenes y múltiples destinos

Estas transacciones usan múltiples orígenes y múltiples destinos. Son útiles para casos como una campaña de crowdfunding. Midaz agrupa las contribuciones y las distribuye entre múltiples destinatarios.

Ejemplo

En este ejemplo (Figura 5):

La donación es BRL 4.000,00. Midaz la toma de cuatro cuentas diferentes.
- 25% proviene de la cuenta 1 (@account1).
- 25% proviene de la cuenta 2 (@account2).
- 40% proviene de la cuenta 3 (@account3)
- 10% proviene de la cuenta 4 (@account4).
Midaz distribuye las donaciones a cuatro cuentas separadas. Cada cuenta recibe una participación del 25% del total.

Transacción de origen y destino múltiples que toma BRL 4.000,00 de cuatro cuentas y lo distribuye de forma equitativa entre cuatro cuentas de destino — Figura 5. Ejemplo de una transacción de múltiples orígenes y múltiples destinos.

Ejemplos de código

{
  "description": "transacción con múltiples fuentes y múltiples destinos",
  "send": {
    "asset": "BRL",
    "value": "4000.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "share": {
            "percentage": 25
          }
        },
        {
          "accountAlias": "@account2",
          "share": {
            "percentage": 25
          }
        },
        {
          "accountAlias": "@account3",
          "share": {
            "percentage": 40
          }
        },
        {
          "accountAlias": "@account4",
          "share": {
            "percentage": 10
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@donation1",
          "share": {
            "percentage": 25
          }
        },
        {
          "accountAlias": "@donation2",
          "share": {
            "percentage": 25
          }
        },
        {
          "accountAlias": "@donation3",
          "share": {
            "percentage": 25
          }
        },
        {
          "accountAlias": "@donation4",
          "share": {
            "percentage": 25
          }
        }
      ]
    }
  }
}

Estados de transacción

Cada transacción en Midaz tiene un estado. El estado refleja su etapa actual en el ciclo de vida. Necesitas estos estados para diseñar flujos de transacciones, configurar consumidores de eventos y leer los datos del libro contable.

Estado	Qué significa	¿Afecta los saldos?	Cómo se crea
`CREATED`	Se inició una transacción de reversión y está siendo procesada. Este es un estado transitorio que progresa automáticamente a `APPROVED` una vez que la reversión se completa.	Sí	Revertir una Transacción
`APPROVED`	La transacción se completó exitosamente. Los fondos se movieron entre las cuentas.	Sí	Transacción directa (sin flag `pending`), commit de una transacción `PENDING`, o progresión automática desde `CREATED`
`PENDING`	Una transacción de dos fases está esperando confirmación. Los fondos están reservados en `on_hold` pero aún no se han transferido.	Sí (reserva)	Crear una Transacción con `"pending": true`
`CANCELED`	Una transacción de dos fases fue cancelada. Los fondos reservados se liberan de vuelta a `available`.	Sí (liberación)	Cancelar una Transacción Pendiente
`NOTED`	Una transacción de anotación registrada en el libro contable sin afectar los saldos. Las operaciones preservan la estructura de partida doble, pero todos los campos de saldo quedan en cero.	No	Crear una Anotación de Transacción

Usa el estado NOTED para importar transacciones heredadas, registrar pistas de auditoría y registrar eventos de cumplimiento. Se adapta a cualquier caso donde la transacción deba existir en el libro contable pero los saldos ya se liquidaron en otro lugar.

Transiciones de estado

Las transacciones siguen caminos predecibles a través de estos estados:

Flujo estándar: → APPROVED (un solo paso)
Flujo de dos fases: → PENDING → APPROVED (commit) o CANCELED (cancelación)
Flujo de reversión: → CREATED → APPROVED (automático)
Flujo de anotación: → NOTED (terminal, sin transiciones)

Una vez que una transacción alcanza NOTED o CANCELED, no puede transicionar más. Ambos son estados terminales.

Flujo de transacciones

Cuando una transacción comienza, Midaz valida:

Las cuentas involucradas.
Los saldos especificados (balanceKey, o default si no se proporciona).
Permisos (allowSending, allowReceiving).
Fondos disponibles suficientes en el saldo seleccionado.

Si la validación pasa y la transacción no es pendiente (flujo de Transacción de Dos Fases), Midaz transfiere la cantidad inmediatamente. Mueve la cantidad de la cuenta de origen a la cuenta de destino, desde el saldo disponible. Este proceso es sincrónico. Al tener éxito, el estado de la transacción pasa a APPROVED.

Inicia este tipo de transacción solo si tienes la intención de confirmarla en el libro contable inmediatamente.

Para transacciones que necesitan validación o aprobación primero, usa la bandera pending para crear una Transacción de dos fases.

Transacción de dos fases

En este flujo, Midaz crea la transacción con estado PENDING. Midaz no mueve los fondos de inmediato. En su lugar, reserva la cantidad en el saldo correcto (balanceKey, o default si no proporcionas uno).

Midaz mueve los fondos reservados de available a on_hold.
Midaz registra una operación, de tipo ON_HOLD, en el saldo de origen. El saldo de destino no se toca: todavía no se registra ningún débito ni crédito.
Debes ejecutar explícitamente commit para ejecutar la transferencia, o cancel para liberar los fondos.

La función de Transacción de Dos Fases es compatible con Flowker. Reservas fondos al comienzo de un flujo de trabajo y ejecutas validaciones más tarde. Midaz garantiza la ejecución si el flujo de trabajo aprueba la transacción.

En la Figura 6, puedes ver un ejemplo de una transacción de dos fases con antifraude.

Transacción en dos fases dentro de un flujo antifraude, que primero reserva los fondos y luego los confirma o cancela tras la validación — Figura 6. Ejemplo de flujo de trabajo antifraude

Flujo de transacción de dos fases

1. Crear una transacción de dos fases

Usa el endpoint Crear una Transacción usando JSON con "pending": true.

Midaz valida cuentas, los saldos especificados (balanceKey), permisos (allowSending, allowReceiving) y fondos disponibles. Si es válido:

Midaz reserva fondos en el saldo correcto.
Midaz establece el estado de la transacción en PENDING.
Midaz almacena los metadatos y registra la operación ON_HOLD de origen; todavía no llega ningún débito ni crédito al destino.

2. Confirmar o cancelar la transacción pendiente

Confirmar: finaliza la transacción. Los fondos se mueven de on_hold al saldo de destino, y Midaz agrega las operaciones DEBIT y CREDIT — así, una transacción de dos fases confirmada tiene tres operaciones en total (ON_HOLD, DEBIT, CREDIT).
- Usa el endpoint Confirmar una Transacción Pendiente.
- Estado: APPROVED.
Cancelar: libera los fondos reservados de vuelta a available en el mismo saldo.
- Usa el endpoint Cancelar una Transacción Pendiente.
- Estado: CANCELED.

Transacciones pasadas

Midaz también admite transacciones pasadas. Las instituciones pueden importar eventos financieros heredados y mantener la precisión histórica.

Usa el campo opcional transactionDate para establecer la fecha original de la transacción.
Las transacciones con impacto financiero recalculan el estado histórico de los saldos como si Midaz las hubiera procesado en esa fecha.
Las transacciones creadas a través del endpoint Crear una Anotación de Transacción validan la estructura pero no afectan los saldos. Sirven para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios.

Ejemplo

{
  "description": "Ejemplo de transacciones pasadas",
  "transactionDate": "2025-01-01T13:38:31.064Z", // opcional
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    }
  }
}

Envía todas las transacciones pasadas antes de comenzar las operaciones en vivo. Midaz entonces recalcula los saldos de manera consistente en todo el libro contable.

Transacciones sin impacto financiero

Midaz puede crear transacciones que registra en el libro contable pero que no afectan los saldos de las cuentas. Estas transacciones mantienen la integridad estructural y dejan los saldos sin cambios. Esta función es útil cuando necesitas:

Importar transacciones heredadas pero mantener los saldos sin cambios.
Registrar eventos de auditoría o cumplimiento.
Agregar operaciones comerciales que el libro contable debe rastrear pero que no mueven fondos.

¿Cómo funciona?

Cuando creas una transacción sin impacto financiero:

Midaz almacena los campos balance y balanceAfter como 0 para preservar la validación de doble entrada.
Cada operación tiene un campo balanceAffected (booleano):
- true → la operación afecta el saldo de la cuenta.
- false → Midaz registra la operación en el libro contable pero no cambia los saldos.

Incluso cuando Midaz no actualiza saldos, aplica reglas de doble entrada. Esto mantiene la consistencia en todas las transacciones del libro contable.

Ejemplo

{
  "description": "ejemplo de anotación",
  "transactionDate": "2025-01-01T13:38:31.064Z",
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    }
  }
}

Endpoint relacionado

Crear una Anotación de Transacción — Registrar una transacción sin impacto financiero en el libro contable.

Publicación de eventos en tiempo real

Midaz admite la publicación de eventos en tiempo real a través de RabbitMQ. Puedes rastrear el estado de tus transacciones a medida que suceden. Después de habilitarlo, cada transacción genera un evento: APPROVED, PENDING, CANCELED, CREATED o NOTED. Los sistemas externos se suscriben a estos eventos a través de enrutamiento basado en temas. Para más información sobre cómo publicar y consumir eventos de transacciones, consulta la página Publicador de eventos.

Entradas, salidas y cuentas externas

Midaz usa un libro contable de doble entrada. Todo el valor que entra o sale del sistema debe pasar por una cuenta especial: la Cuenta Externa. Midaz representa esta cuenta como @external/{{assetCode}}. Actúa como el puente entre Midaz y el mundo financiero externo (bancos, PSP, rieles de pago, etc.).

¿Por qué importa esto?

Cuando inicializas el libro contable por primera vez, todas las cuentas — incluida @external — comienzan con un saldo cero. Para reflejar los saldos del mundo real, como fondos institucionales mantenidos fuera de Midaz, debes iniciar una transacción que inyecte fondos en las cuentas de Midaz y debite la cuenta externa. Esta es la única forma de traer fondos a Midaz.

Entradas – Agregar valor al Ledger

Para acreditar una cuenta interna desde fuera del libro contable:

Origen: @external/{{assetCode}} (por ejemplo, @external/BRL).
Destino: Una o más cuentas internas (por ejemplo, @organization.main).

Ejemplo: Primer depósito en el Libro Contable Tu institución tiene R$10.000 en un banco del mundo real y quiere traerlo a Midaz. Crea una transacción:

Origen	Destino	Cantidad
@external/BRL	@accountA	BRL 10.000

Esto debita la cuenta externa y acredita tu cuenta interna. La cuenta externa ahora muestra un saldo negativo. Esto es esperado: representa la cantidad total que tu organización trajo al libro contable.

Salidas – Mover valor fuera del Ledger

Para mover valor del libro contable a un destino externo:

Origen: Una o más cuentas de Midaz.
Destino: @external/{{assetCode}}.

Ejemplo: Una transferencia Pix del Ledger a un banco externo

Origen	Destino	Cantidad
@accountA	@external/BRL	BRL 1.000

Esto debita @accountA y acredita la cuenta externa. Tu sistema entonces transfiere los fondos al destinatario a través de SPI u otra integración.

Comportamiento y reglas de saldo

@external/{{assetCode}} puede tener un saldo cero o negativo, pero nunca positivo.
Su saldo es siempre el inverso del saldo combinado de todas las cuentas de Midaz que mantienen ese activo.
Cada entrada aumenta la liquidez interna y reduce el saldo de la cuenta externa (es decir, simula un depósito).
Cada salida hace lo contrario.

Todo el valor que se mueve entre el mundo exterior y el libro contable de Midaz debe pasar por la cuenta externa.Nada entra o sale del sistema sin una transacción formal. Esto te da trazabilidad completa, integridad del saldo y cumplimiento con los principios de doble entrada.

Configurar una fecha personalizada para la transacción

El campo transactionDate te permite establecer una fecha personalizada para una transacción, independientemente de cuándo la envías a la API.

Opcional. Si lo omites, Midaz usa el timestamp actual.
Formatos aceptados:
- ISO 8601 con zona horaria: 2026-01-15T10:30:00Z
- ISO 8601 sin zona horaria: 2026-01-15T10:30:00
- Solo fecha: 2026-01-15
Restricción: no puedes usar una fecha futura. Una fecha futura devuelve el error 0121.
Restricción: no puedes usarlo en transacciones PENDING. Un transactionDate con "pending": true devuelve el error 0122.

Casos de uso

Registrar transacciones que ocurrieron en el pasado (por ejemplo, correcciones del mismo día)
Importar datos financieros históricos a un nuevo libro contable
Reconciliar con sistemas externos que usan una fecha de contabilización diferente

Rutas de transacción

La API de Rutas de transacción habilita el procesamiento estructurado y validado de transacciones en Midaz.

La Lerian Console y la documentación del producto llaman a este concepto Rutas Contables (Accounting Routes). El recurso y los endpoints de la API mantienen el nombre transactionRoute / Rutas de transacción. Ambos se refieren a la misma ruta a nivel de transacción.

La API de Transacciones ejecuta eventos financieros: débitos y créditos entre cuentas. Las Rutas de Transacción definen plantillas para cómo estructurar y validar estos eventos. Esto los mantiene consistentes y correctos. Piensa en ello como la capa de validación. Hace que las transacciones comerciales sigan patrones predefinidos y mantengan una estructura financiera adecuada. Por ejemplo, una comisión, un depósito o un pago puede necesitar diferentes tipos de cuenta, reglas de validación y estructuras. No manejas la validación por separado para cada transacción. En su lugar, configuras reglas predefinidas. Estas reglas le dicen a Midaz: “Cuando el usuario envíe este tipo de transacción, valídala contra estos requisitos de cuenta y patrones de estructura.” Cada Ruta de Transacción combina múltiples Rutas de operación. Una Ruta de operación define un componente de una transacción. Establece los requisitos de cuenta, la dirección (origen o destino) y las reglas de validación para cada “tramo” del evento financiero.

No uses el campo route en las entradas FromTo — usa routeId en su lugar. El campo routeId acepta un UUID que referencia una Ruta de operación creada a través de la API de Rutas de operación. Midaz mantiene el campo route por compatibilidad retroactiva, pero eliminará el campo en una versión futura.

¿Por qué importa?

Con Rutas de transacción, tú:

Mantienes una estructura de transacción consistente en toda tu aplicación.
Haces que tu libro contable sea más mantenible, predecible y confiable.
Validas eventos financieros contra patrones predefinidos.
Configuras plantillas de transacción sin cambios de código.
Mantienes la integridad de datos a través de la validación estructurada.

Iniciar una transacción

Cuando creas transacciones a través de la API, siempre implementa idempotencia para evitar procesamiento duplicado. Midaz ofrece soporte de idempotencia integrado a través del header X-Idempotency. Valida el header de respuesta X-Idempotency-Replayed para distinguir transacciones nuevas de reproducciones en caché. Consulta Reintentos e idempotencia para más detalles.

Usa la API JSON de transacciones para iniciar una transacción.

Estructura de la solicitud JSON en v2

Cada lado de la transacción usa una representación: from o sources, e independientemente to o destinations. No envíes ambas representaciones para el mismo lado ni un null explícito para un campo escalar sin usar. Cada elemento de sources o destinations requiere account y exactamente una expresión de valor: amount o share. La expresión remaining no se acepta en v2. Cada arreglo admite como máximo 500 elementos. share.percentage debe estar entre 1 y 100; share.percentageOfPercentage, entre 0 y 100, donde 0 no aplica reducción. Las solicitudes de creación v2 tienen un límite de cuerpo de 1 MiB.

Usar el endpoint JSON

Los endpoints JSON proporcionan un estándar flexible y amigable para desarrolladores para el intercambio de datos. Te dan control preciso sobre las estructuras de solicitud para flujos de trabajo personalizados y casos de uso específicos. Funcionan con muchos lenguajes de programación, lo que facilita la integración y la depuración.

Para crear una transacción con JSON, usa el endpoint Crear una Transacción usando JSON.

Si necesitas reservar fondos antes de completar la transferencia, establece el campo pending en true (flujo de Transacción de Dos Fases).

Reversión de una transacción

Midaz admite la reversión de transacciones. Puedes deshacer una transacción aprobada. Midaz crea una transacción espejo que invierte los débitos y créditos originales. Este mecanismo mantiene pistas de auditoría completas y cancela el impacto financiero en los saldos de las cuentas.

La reversión crea una nueva transacción que compensa la original. La transacción original permanece en el historial del libro contable para completa trazabilidad.

La reversión no envía una clave de idempotencia propia, así que Midaz deriva una. Lee el encabezado de respuesta X-Idempotency-Replayed: true significa que recibiste una reversión en caché y no una recién creada. Trata una repetición como una señal para verificar el estado del origen antes de reintentar.

¿Cómo funciona?

Cuando reviertes una transacción, Midaz automáticamente:

Invierte las operaciones:
- Las operaciones CREDIT se convierten en operaciones de origen (from).
- Las operaciones DEBIT se convierten en operaciones de destino (to).
Crea una nueva transacción con:
- Mismo monto y código de activo.
- Misma descripción y metadatos.
- Operaciones invertidas (los receptores se convierten en emisores, los emisores en receptores).
- Estado inicial: CREATED (no PENDING) → luego progresa a APPROVED.
- parentTransactionID que referencia la transacción original.
Procesa la reversión a través del flujo estándar de transacciones: validación, actualización de saldos y registro de historial.

Ejemplo

Considera este escenario: Transacción original:

Cuenta A (débito -100) → Cuenta B (crédito +100)

Transacción de reversión creada:

Cuenta B (débito -100) → Cuenta A (crédito +100)

Resultado:

La Cuenta A regresa a su saldo anterior (recibe de vuelta los -100).
La Cuenta B regresa a su saldo anterior (pierde los +100).
Ambas transacciones permanecen en el historial del libro contable para propósitos de auditoría.
La transacción de reversión incluye un parentTransactionID que apunta a la original.

Restricciones de reversión

Midaz aplica reglas estrictas para mantener la integridad del libro contable. Una reversión falla en estos casos:

1. La transacción ya tiene una reversión

Midaz permite solo una reversión por transacción.
Esto previene múltiples reversiones de la misma transacción.

2. La transacción ya es una reversión

No puedes revertir una transacción que ya es una reversión.
Esto previene “reversiones de reversiones.”

3. El estado de la transacción no es APPROVED

Puedes revertir solo transacciones aprobadas.
No puedes revertir una transacción con estado PENDING, CREATED o CANCELED.

4. La transacción no puede ser revertida

Esto ocurre cuando la transacción no tiene operaciones válidas para invertir.
Por ejemplo, una transacción sin operaciones estándar CREDIT o DEBIT.

5. Una ruta de operación de la transacción no es bidireccional

Cada operación que lleva un routeId debe referenciar una Ruta de operación cuyo operationType sea bidirectional.
Una ruta source o destination no puede revertirse: Midaz devuelve el error 0150 (Route Not Bidirectional).
Tenlo en cuenta al diseñar tus rutas — consulta Rutas Contables.

Midaz revierte las operaciones CREDIT y DEBIT. No revierte las operaciones ON_HOLD ni RELEASE.

Casos de uso

La reversión de transacciones ayuda en varios escenarios operacionales:

1. Reversión de pago incorrecto

Un cliente pagó BRL 500 al proveedor equivocado.

Revertir la transacción.
Los fondos regresan a la cuenta del cliente.
El cliente puede iniciar un nuevo pago al proveedor correcto.

2. Cancelación de compra

Una tienda procesó una venta de BRL 1,000, pero el cliente cancela la compra.

Revertir la transacción de venta.
Los fondos regresan a la cuenta del cliente.

3. Corrección de error operacional

Un operador creó una transacción con el monto incorrecto.

Revertir la transacción incorrecta.
Crear una nueva transacción con el monto correcto.

4. Devolución de producto

Un cliente compró y pagó BRL 200, pero devolvió el producto.

Revertir la transacción de pago.
El cliente recibe un reembolso.

5. Compensación por falla en integración

Una transacción se aprueba pero falla en un sistema externo.

Revertir para deshacer la operación contable.
Los saldos regresan a su estado anterior.

Bloqueo y desbloqueo de fondos

Algunos escenarios requieren marcar fondos como bloqueados — una retención por cumplimiento, una orden judicial, una investigación de fraude — y luego liberarlos. Midaz admite esto con dos endpoints dedicados. Estos endpoints crean transacciones cuyas operaciones son del tipo BLOCK y UNBLOCK. Estas transacciones aceptan el mismo cuerpo que el endpoint Crear una Transacción usando JSON, con dos diferencias clave:

Siempre se registran de inmediato. Midaz ignora el campo pending del cuerpo de la solicitud y lo sobrescribe a false. Las transacciones de bloqueo y desbloqueo nunca son de dos fases. Pasan directamente a APPROVED.
Las operaciones son del tipo BLOCK o UNBLOCK. Esta clasificación las distingue en el ledger y en las consultas de operaciones. Puedes auditar los movimientos de fondos bloqueados sin mirar el metadata.

Midaz es agnóstico respecto al motivo de negocio para bloquear o desbloquear fondos. Registra el motivo en el campo metadata.

Una transacción de bloqueo registra un movimiento en el ledger con operaciones del tipo BLOCK. Esto difiere de los controles a nivel de saldo en Saldos: las permission flags (allowSending / allowReceiving) y los saldos de garantía. Esos controles restringen el movimiento pero no registran una transacción. Usa un saldo de garantía para una restricción operacional permanente. Usa una transacción de bloqueo cuando necesites una entrada auditable en el ledger.

Usa el endpoint Crear una Transacción de Bloqueo para bloquear fondos.
Usa el endpoint Crear una Transacción de Desbloqueo para liberar fondos previamente bloqueados.

Gestión de transacciones

Puedes gestionar tus transacciones a través de la API o Lerian Console.

Vía API

Crear una Transacción usando JSON — Enviar una transacción directamente usando un payload JSON.
Confirmar una transacción pendiente — Finalizar una transacción reservada.
Cancelar una transacción pendiente — Liberar fondos reservados sin ejecutar.
Revert a Transaction — Crea una transacción de reversión para deshacer una transacción aprobada.
Crear una Transacción de Entrada — Registrar fondos entrantes de fuentes externas al Libro Contable.
Crear una Transacción de Salida — Mover fondos de cuentas internas al mundo externo.
Crear una Transacción de Bloqueo — Marcar fondos como bloqueados con operaciones del tipo BLOCK.
Crear una Transacción de Desbloqueo — Liberar fondos previamente bloqueados con operaciones del tipo UNBLOCK.
Listar Transacciones — Ver todas las Transacciones en tu espacio de trabajo.
Recuperar una Transacción — Obtener detalles de una Transacción específica.
Actualizar una Transacción — Editar los metadatos de una Transacción existente.
Crear una Anotación de Transacción — Registrar una transacción sin impacto financiero en el libro contable.

Vía Lerian Console

Puedes realizar todas las acciones de gestión de Transacciones — ver, crear y cancelar — a través de Lerian Console. Obtén más información en la guía Gestión de Transacciones.

⌘I

​Contabilidad de doble entrada

​Ejemplo

​Transacciones N:N (Muchos a Muchos)

​Ejemplos

​Atomicidad e integridad

​Origen de la transacción

​Origen único

​Ejemplo

​Múltiples orígenes

​Ejemplo

​Destino de la transacción

​Destino único

​Ejemplo

​Múltiples destinos

​Ejemplo

​Múltiples orígenes y múltiples destinos

​Ejemplo

​Estados de transacción

​Transiciones de estado

​Flujo de transacciones

​Transacción de dos fases

​Flujo de transacción de dos fases

​1. Crear una transacción de dos fases

​2. Confirmar o cancelar la transacción pendiente

​Transacciones pasadas

​Ejemplo

​Transacciones sin impacto financiero

​¿Cómo funciona?

​Ejemplo

​Endpoint relacionado

​Publicación de eventos en tiempo real

​Entradas, salidas y cuentas externas

​¿Por qué importa esto?

​Entradas – Agregar valor al Ledger

​Salidas – Mover valor fuera del Ledger

​Comportamiento y reglas de saldo

​Configurar una fecha personalizada para la transacción

​Casos de uso

​Rutas de transacción

​¿Por qué importa?

​Iniciar una transacción

​Estructura de la solicitud JSON en v2

​Usar el endpoint JSON

​Reversión de una transacción

​¿Cómo funciona?

​Ejemplo

​Restricciones de reversión

​1. La transacción ya tiene una reversión

​2. La transacción ya es una reversión

​3. El estado de la transacción no es APPROVED

​4. La transacción no puede ser revertida

​5. Una ruta de operación de la transacción no es bidireccional

​Casos de uso

​1. Reversión de pago incorrecto

​2. Cancelación de compra

​3. Corrección de error operacional

​4. Devolución de producto

​5. Compensación por falla en integración

​Bloqueo y desbloqueo de fondos

​Gestión de transacciones

​Vía API

​Vía Lerian Console

Contabilidad de doble entrada

Ejemplo

Transacciones N:N (Muchos a Muchos)

Ejemplos

Atomicidad e integridad

Origen de la transacción

Origen único

Ejemplo

Múltiples orígenes

Ejemplo

Destino de la transacción

Destino único

Ejemplo

Múltiples destinos

Ejemplo

Múltiples orígenes y múltiples destinos

Ejemplo

Estados de transacción

Transiciones de estado

Flujo de transacciones

Transacción de dos fases

Flujo de transacción de dos fases

1. Crear una transacción de dos fases

2. Confirmar o cancelar la transacción pendiente

Transacciones pasadas

Ejemplo

Transacciones sin impacto financiero

¿Cómo funciona?

Ejemplo

Endpoint relacionado

Publicación de eventos en tiempo real

Entradas, salidas y cuentas externas

¿Por qué importa esto?

Entradas – Agregar valor al Ledger

Salidas – Mover valor fuera del Ledger

Comportamiento y reglas de saldo

Configurar una fecha personalizada para la transacción

Casos de uso

Rutas de transacción

¿Por qué importa?

Iniciar una transacción

Estructura de la solicitud JSON en v2

Usar el endpoint JSON

Reversión de una transacción

¿Cómo funciona?

Ejemplo

Restricciones de reversión

1. La transacción ya tiene una reversión

2. La transacción ya es una reversión

3. El estado de la transacción no es APPROVED

4. La transacción no puede ser revertida

5. Una ruta de operación de la transacción no es bidireccional

Casos de uso

1. Reversión de pago incorrecto

2. Cancelación de compra

3. Corrección de error operacional

4. Devolución de producto

5. Compensación por falla en integración

Bloqueo y desbloqueo de fondos

Gestión de transacciones

Vía API

Vía Lerian Console