> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Transacciones > Registra eventos financieros con Transacciones de partida doble en Midaz — múltiples Saldos, débitos, créditos y trazabilidad total entre Cuentas. 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 **Ejemplos de código** ```json JSON Example expandable theme={null} { "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 **Ejemplos de código** ```json JSON Example theme={null} { "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 **Ejemplos de código** ```json JSON Example theme={null} { "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 **Ejemplo de código** ```json JSON Example theme={null} { "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 **Ejemplos de código** ```json JSON Example theme={null} { "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](/es/reference/midaz/revert-a-transaction) | | `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](/es/reference/midaz/create-a-transaction-using-json) 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](/es/reference/midaz/cancel-a-pending-transaction) | | `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](/es/reference/midaz/create-a-transaction-annotation) | 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](/es/flowker/what-is-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 ### Flujo de transacción de dos fases #### 1. Crear una transacción de dos fases * Usa el endpoint [Crear una Transacción usando JSON](/es/reference/midaz/create-a-transaction-using-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](/es/reference/midaz/commit-a-pending-transaction). * Estado: `APPROVED`. * **Cancelar**: libera los fondos reservados de vuelta a `available` en el mismo saldo. * Usa el endpoint [Cancelar una Transacción Pendiente](/es/reference/midaz/cancel-a-pending-transaction). * 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](/es/reference/midaz/create-a-transaction-annotation) validan la estructura pero **no** afectan los saldos. Sirven para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios. ### Ejemplo ```json theme={null} { "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 ```json theme={null} { "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](/es/reference/midaz/create-a-transaction-annotation) — 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](/es/midaz/event-publisher). ## 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](/es/reference/retries-idempotency) 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](/es/reference/midaz/create-a-transaction-using-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: 1. **Invierte las operaciones**: * Las operaciones CREDIT se convierten en operaciones de origen (`from`). * Las operaciones DEBIT se convierten en operaciones de destino (`to`). 2. **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. 3. **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](/es/midaz/transaction-routing-entities). 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](/es/reference/midaz/create-a-transaction-using-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](/es/midaz/balances): 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](/es/reference/midaz/create-a-block-transaction) para bloquear fondos. * Usa el endpoint [Crear una Transacción de Desbloqueo](/es/reference/midaz/create-an-unblock-transaction) 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](/es/reference/midaz/create-a-transaction-using-json) — Enviar una transacción directamente usando un payload JSON. * [Confirmar una transacción pendiente](/es/reference/midaz/commit-a-pending-transaction) — Finalizar una transacción reservada. * [Cancelar una transacción pendiente](/es/reference/midaz/cancel-a-pending-transaction) — Liberar fondos reservados sin ejecutar. * [Revert a Transaction](/es/reference/midaz/revert-a-transaction) — Crea una transacción de reversión para deshacer una transacción aprobada. * [Crear una Transacción de Entrada](/es/reference/midaz/create-an-inflow-transaction) — Registrar fondos entrantes de fuentes externas al Libro Contable. * [Crear una Transacción de Salida](/es/reference/midaz/create-an-outflow-transaction) — Mover fondos de cuentas internas al mundo externo. * [Crear una Transacción de Bloqueo](/es/reference/midaz/create-a-block-transaction) — Marcar fondos como bloqueados con operaciones del tipo `BLOCK`. * [Crear una Transacción de Desbloqueo](/es/reference/midaz/create-an-unblock-transaction) — Liberar fondos previamente bloqueados con operaciones del tipo `UNBLOCK`. * [Listar Transacciones](/es/reference/midaz/list-transactions) — Ver todas las Transacciones en tu espacio de trabajo. * [Recuperar una Transacción](/es/reference/midaz/retrieve-a-transaction) — Obtener detalles de una Transacción específica. * [Actualizar una Transacción](/es/reference/midaz/update-a-transaction) — Editar los metadatos de una Transacción existente. * [Crear una Anotación de Transacción](/es/reference/midaz/create-a-transaction-annotation) — 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](/es/midaz/console/managing-transactions).