> ## 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 las Transacciones de partida doble de Midaz: múltiples Saldos, débitos, créditos y trazabilidad completa entre Cuentas. Una **Transacción** en Midaz registra un evento financiero completo. Una transacción suele usar múltiples cuentas y saldos. Midaz funciona con un sistema de contabilidad de partida doble que mantiene equilibrado cada movimiento financiero. Con la función de **múltiples saldos**, cada operación especifica la cuenta y la **clave de saldo** que se usará. Luego puedes debitar o acreditar distintos 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 partida doble *** El sistema de partida doble sigue un solo principio. Cada transacción tiene dos asientos: un débito y un crédito. Esta estructura registra toda la actividad financiera y mantiene tus cuentas equilibradas. Cada transacción afecta a dos cuentas y las mantiene en equilibrio: * Los **débitos** muestran el valor recibido o los recursos consumidos. * Los **créditos** muestran el valor entregado o los recursos proporcionados. Midaz registra y equilibra automáticamente cada débito y crédito. ### 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 en la cuenta de destino. Midaz captura ambos asientos automáticamente. Puedes ver y analizar estos movimientos mediante la API o Lerian Console. ## Transacciones N:N (muchos a muchos) *** Los sistemas financieros tradicionales limitan las transacciones a relaciones de uno a uno o de 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 sola cuenta escrow paga a varios vendedores, y cada vendedor paga una comisión de la plataforma. * **Persona a persona con comisiones**: una transacción debita al pagador y acredita tanto al receptor 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 se ejecutan correctamente, o ninguna lo hace.** No se producen eventos financieros parciales. Si alguna parte de una transacción no pasa la validación (por ejemplo, una cuenta no tiene fondos suficientes), Midaz no aplica la transacción. El ledger permanece consistente. ## Origen de la transacción *** Una transacción en Midaz puede iniciarse desde una sola fuente o desde múltiples fuentes. La suma de los valores en `source` debe ser igual al valor que sigue a `send`. También debe ser igual a la suma de los valores en `distribute`. ### Fuente única En una transacción de fuente única, Midaz toma el monto 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 el 100% a `@destinationAccount1` (saldo `operational`) Transacción de fuente única que mueve BRL 30.00 de una cuenta de origen a una sola cuenta de destino **Ejemplos de código** ```json JSON Example expandable theme={null} { "description": "single source transaction", "send": { "asset": "BRL", "value": "30.00", "source": { "from": [ { "accountAlias": "@account1", "balanceKey": "credit", // optional "amount": { "asset": "BRL", "value": "30.00" } } ] }, "distribute": { "to": [ { "accountAlias": "@destinationAccount1", "balanceKey": "operational", // optional "share": { "percentage": 100 } } ] } } } ``` ### Múltiples fuentes En una transacción de múltiples fuentes, Midaz toma fondos de varias 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% del monto. Transacción de múltiples fuentes en la que se toman BRL 30.00 de dos cuentas de origen y se envían a una sola cuenta de destino **Ejemplos de código** ```json JSON Example theme={null} { "description": "multi-source transaction", "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 las fuentes, los destinos pueden ser únicos o múltiples. ### Destino único En una transacción de destino único, Midaz envía el monto a una sola cuenta de destino. #### Ejemplo En este ejemplo (*Figura 3*): * Midaz toma BRL 30.00 de una cuenta externa (`@external/BRL`). * Envía el 100% a la cuenta de destino (`@destinationAccount1`). Transacción de destino único que mueve BRL 30.00 de una cuenta externa a una cuenta de destino **Ejemplos de código** ```json JSON Example theme={null} { "description":"single destination transaction", "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 el monto entre varias cuentas de destino. Puedes distribuir los valores por porcentajes, montos fijos o el saldo restante. #### Ejemplo En este ejemplo (*Figura 4*): * Midaz toma BRL 100 de la cuenta de origen (`@account1`). * El 38% del monto va a la cuenta 2 (`@account2`). * El 50% va a la cuenta 3 (`@account3`). * Un monto fijo de BRL 2.00 va a la cuenta 4 (`@account4`). * El monto restante va a la cuenta 5 (`@account5`). Transacción de múltiples destinos que divide BRL 100.00 de una cuenta de origen entre cinco cuentas de destino por porcentaje y montos fijos **Ejemplo de código** ```json JSON Example theme={null} { "description":"multi-destination transaction", "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 fuentes y múltiples destinos *** Estas transacciones usan múltiples fuentes y múltiples destinos. Son útiles en casos como una campaña de crowdfunding. Midaz agrupa las contribuciones y las distribuye entre varios destinatarios. #### Ejemplo En este ejemplo (*Figura 5*): * La donación es de BRL 4,000.00. Midaz la toma de cuatro cuentas distintas. * El 25% proviene de la cuenta 1 (`@account1`). * El 25% proviene de la cuenta 2 (`@account2`). * El 40% proviene de la cuenta 3 (`@account3`) * El 10% proviene de la cuenta 4 (`@account4`). * Midaz distribuye las donaciones entre cuatro cuentas independientes. Cada cuenta recibe un porcentaje del 25% del total. Transacción de múltiples fuentes y múltiples destinos 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":"multi-source and multi-destination transaction", "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 la 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 ledger. | Estado | Qué significa | ¿Afecta los saldos? | Cómo se crea | | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------ | :------------------------------------------------------------------------------------------------------------------------------ | | `CREATED` | Se inició una transacción de reversión y se está procesando. Es un estado transitorio que avanza automáticamente a `APPROVED` cuando se completa la reversión. | Sí | [Revierte una transacción](/es/reference/products/midaz/v2/revert-transaction) | | `APPROVED` | La transacción se completó correctamente. Los fondos se movieron entre cuentas. | Sí | Transacción directa (sin el flag `pending`), confirmación de una transacción `PENDING`, o progresión automática desde `CREATED` | | `PENDING` | Una transacción de dos fases está a la espera de confirmación. Los fondos están reservados en `on_hold` pero aún no se transfirieron. | Sí (reserva) | [Crea una transacción](/es/reference/products/midaz/v1/create-transaction-json) con `"pending": true` | | `CANCELED` | Se canceló una transacción de dos fases. Los fondos reservados se liberan de vuelta a `available`. | Sí (liberación) | [Cancela una transacción pendiente](/es/reference/products/midaz/v2/cancel-transaction) | | `NOTED` | Una transacción de anotación registrada en el ledger sin afectar los saldos. Las operaciones conservan la estructura de partida doble, pero todos los campos de saldo quedan en cero. | No | [Crea una anotación de transacción](/es/reference/products/midaz/v1/create-transaction-annotation) | Usa el estado `NOTED` para importar transacciones heredadas, registrar registros de auditoría y dejar constancia de eventos de cumplimiento. Se adapta a cualquier caso en el que la transacción deba existir en el ledger, pero los saldos ya se hayan liquidado en otro lugar. ### Transiciones de estado Las transacciones siguen rutas predecibles a través de estos estados: * **Flujo estándar:** → `APPROVED` (un solo paso) * **Flujo de dos fases:** → `PENDING` → `APPROVED` (confirmación) 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 llega a `NOTED` o `CANCELED`, no puede transicionar más. Ambos son estados terminales. ## Flujo de la transacción *** Cuando una transacción se inicia, Midaz valida: * Las cuentas involucradas. * Los saldos especificados (`balanceKey`, o `default` si no se indica). * Los permisos (`allowSending`, `allowReceiving`). * Fondos disponibles suficientes en el saldo seleccionado. Si la validación se aprueba y la transacción **no** está pendiente (flujo de transacción de dos fases), Midaz transfiere el monto **de inmediato**. Mueve el monto de la cuenta de origen a la cuenta de destino, desde el saldo disponible. Este proceso es síncrono. Si se completa correctamente, 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 ledger de inmediato. Para las transacciones que necesitan validación o aprobación primero, usa el flag `pending` para crear una **transacción de dos fases**. ## Transacción de dos fases *** En este flujo, Midaz crea la transacción con el estado `PENDING`. Midaz no mueve los fondos de inmediato. En cambio, reserva el monto 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, con el tipo `ON_HOLD`, en el saldo de origen. El saldo de destino permanece intacto: aún no se registra ningún débito ni crédito. * Debes ejecutar explícitamente `commit` para hacer la transferencia, o `cancel` para liberar los fondos. La función de transacción de dos fases da soporte a [Flowker](/es/products/flowker/what-is-flowker). Reservas los fondos al inicio de un workflow y ejecutas las validaciones más adelante. Midaz garantiza la ejecución si el workflow aprueba la transacción. En la *Figura 6*, puedes ver un ejemplo de una transacción de dos fases con antifraude. Transacción de dos fases en un workflow antifraude, que reserva los fondos primero y los confirma o cancela después de la validación ### Flujo de la transacción de dos fases #### 1. Crea una transacción de dos fases * Usa el endpoint [Crea una transacción con JSON](/es/reference/products/midaz/v1/create-transaction-json) con `"pending": true`. Midaz valida las cuentas, los saldos especificados (`balanceKey`), los permisos (`allowSending`, `allowReceiving`) y los fondos disponibles. Si es válida: * Midaz reserva los 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. Confirma o cancela 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`. Una transacción de dos fases confirmada tiene un total de tres operaciones (`ON_HOLD`, `DEBIT`, `CREDIT`). * Usa el endpoint [Confirma una transacción pendiente](/es/reference/products/midaz/v2/commit-transaction). * Estado: `APPROVED`. * **Cancelar**: libera los fondos reservados de vuelta a `available` en el mismo saldo. * Usa el endpoint [Cancela una transacción pendiente](/es/reference/products/midaz/v2/cancel-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 del saldo como si Midaz las hubiera procesado en esa fecha. * Las transacciones creadas mediante el endpoint [Crea una anotación de transacción](/es/reference/products/midaz/v1/create-transaction-annotation) validan la estructura, pero **no** afectan los saldos. Son adecuadas para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios. ### Ejemplo ```json theme={null} { "description": "past transaction example", "transactionDate": "2025-01-01T13:38:31.064Z", // optional "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 iniciar las operaciones en vivo. Así, Midaz recalcula los saldos de forma consistente en todo el ledger. ## Transacciones sin impacto financiero *** Midaz puede crear transacciones que registra en el ledger, 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** sin modificar los saldos. * Registrar **eventos de auditoría o cumplimiento**. * Agregar **operaciones de negocio** que el ledger 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 partida doble. * 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 ledger, pero no modifica los saldos. Incluso cuando Midaz no actualiza ningún saldo, aplica las reglas de partida doble. Esto mantiene la consistencia en todas las transacciones del ledger. #### Ejemplo ```json theme={null} { "description": "annotation example", "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 * [Crea una anotación de transacción](/es/reference/products/midaz/v1/create-transaction-annotation): registra una transacción sin impacto financiero en el ledger. ## Publicación de eventos en tiempo real *** Midaz admite la publicación de eventos en tiempo real mediante RabbitMQ. Puedes hacer seguimiento del estado de tus transacciones a medida que ocurren. Después de habilitarlo, cada transacción genera un evento: `APPROVED`, `PENDING`, `CANCELED`, `CREATED` o `NOTED`. Los sistemas externos se suscriben a estos eventos mediante 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/products/midaz/event-publisher). ## Entradas, salidas y cuentas externas *** Midaz usa un ledger de partida doble. 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 ledger por primera vez, todas las cuentas, incluida `@external`, empiezan con saldo cero. Para reflejar los saldos del mundo real, como los fondos institucionales que se mantienen 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 ingresar fondos a Midaz. ### Entradas: agregar valor al ledger Para acreditar una cuenta interna desde fuera del ledger: * **Origen**: `@external/{{assetCode}}` (por ejemplo, `@external/BRL`). * **Destino**: una o más cuentas internas (por ejemplo, `@organization.main`). **Ejemplo: primer depósito en el ledger** Tu institución mantiene R\$10,000 en un banco del mundo real y quiere ingresarlos a Midaz. Creas una transacción: | Origen | Destino | Monto | | :------------ | :-------- | :--------- | | @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 lo esperado: representa el monto total que tu organización ingresó al ledger. ### Salidas: mover valor fuera del ledger Para mover valor del ledger 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 | Monto | | :-------- | :------------ | :-------- | | @accountA | @external/BRL | BRL 1,000 | Esto debita `@accountA` y acredita la cuenta externa. Luego, tu sistema transfiere los fondos al destinatario mediante SPI u otra integración. ### Comportamiento y reglas de saldo * `@external/{{assetCode}}` puede tener un saldo **cero o negativo**, pero nunca **positivo**. * Su saldo siempre es el **inverso** del saldo combinado de todas las cuentas de Midaz que tienen 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 ledger de Midaz debe pasar por la cuenta externa. Nada entra o sale del sistema sin una transacción formal. ## Establecer una fecha de transacción personalizada *** El campo `transactionDate` permite establecer una fecha personalizada para una transacción, independiente del momento en que la envías a la API. * **Opcional.** Si lo omites, Midaz usa la marca de tiempo 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 ocurridas en el pasado (por ejemplo, correcciones del mismo día) * Importar datos financieros históricos a un ledger nuevo * Conciliar con sistemas externos que usan una fecha de registro distinta ## Transaction Routes *** La API de **Transaction Routes** permite el procesamiento estructurado y validado de transacciones en Midaz. Lerian Console y la documentación del producto llaman a este concepto **Accounting Routes**. El recurso y los endpoints de la API mantienen el nombre `transactionRoute` / Transaction Routes. Ambos se refieren a la misma ruta en el nivel de transacción. La API de Transactions ejecuta eventos financieros: débitos y créditos entre cuentas. Transaction Routes define plantillas para **cómo** estructurar y validar estos eventos. Esto los mantiene consistentes y correctos. Piensa en esto como la capa de validación. Hace que las transacciones de negocio sigan **patrones predefinidos** y mantengan una **estructura financiera adecuada**. Por ejemplo, una **comisión**, un **depósito** o un **pago** pueden necesitar distintos tipos de cuenta, reglas de validación y estructuras. No gestionas la validación por separado para cada transacción. En cambio, configuras reglas predefinidas. Estas reglas le indican a Midaz: "*Cuando el usuario envíe este tipo de transacción, valídala contra estos requisitos de cuenta y patrones de estructura.*" Cada Transaction Route combina varias **Operation Routes**. Una Operation Route 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. `routeId` acepta un UUID que hace referencia a una Operation Route creada mediante la API de Operation Routes. Midaz mantiene el campo `route` por compatibilidad con versiones anteriores, pero lo eliminará en una versión futura. ### ¿Por qué importa esto? Con **Transaction Routes**, puedes: * Mantener una estructura de transacción consistente en toda tu aplicación. * Validar eventos financieros contra patrones predefinidos. * Configurar plantillas de transacción sin cambios de código. * Mantener la integridad de los datos mediante validación estructurada. ## Iniciar una transacción *** Cuando creas transacciones mediante la API, implementa siempre la **idempotencia** para evitar el procesamiento duplicado. Midaz ofrece soporte de idempotencia integrado mediante el encabezado `X-Idempotency`. Valida el encabezado de respuesta `X-Idempotency-Replayed` para distinguir las transacciones nuevas de las repeticiones almacenadas en caché. Consulta [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. Usa la API de transacciones JSON para iniciar una transacción. ### Forma 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, y no envíes 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 acepta como máximo 500 elementos. `share.percentage` va de 1 a 100; `share.percentageOfPercentage` va de 0 a 100, donde `0` significa sin restricción adicional. Las solicitudes de creación en v2 tienen un límite de cuerpo de 1 MiB. ### Uso del endpoint JSON * Para crear una transacción con JSON, usa el endpoint [Crea una transacción con JSON](/es/reference/products/midaz/v1/create-transaction-json). Si necesitas reservar fondos **antes** de completar la transferencia, establece el campo `pending` en `true` (flujo de transacción de dos fases). ## Revertir 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 conserva registros de auditoría completos y anula el impacto financiero en los saldos de las cuentas. La reversión crea una **transacción nueva** que compensa la original. La transacción original permanece en el historial del ledger para una trazabilidad completa. La reversión no envía una clave de idempotencia propia, por lo que Midaz deriva una. Lee el encabezado de respuesta `X-Idempotency-Replayed`: `true` significa que recibiste una reversión almacenada en caché en lugar de 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 transacción nueva** con: * El mismo monto y código de activo. * La misma descripción y los mismos metadatos. * Operaciones invertidas (los destinatarios se convierten en remitentes, y los remitentes en destinatarios). * Estado inicial: `CREATED` (no `PENDING`) → luego avanza a `APPROVED`. * `parentTransactionID` que hace referencia a la transacción original. 3. **Procesa la reversión** mediante el flujo estándar de transacciones: validación, actualización de saldos y registro en el historial. ### Ejemplo **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 vuelve a su saldo anterior (recibe de vuelta los -100). * La cuenta B vuelve a su saldo anterior (pierde los +100). * Ambas transacciones permanecen en el historial del ledger con fines de auditoría. * La transacción de reversión incluye un `parentTransactionID` que apunta a la original. ### Restricciones de la reversión Midaz aplica reglas estrictas para mantener la integridad del ledger. 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 evita múltiples reversiones de la misma transacción. #### 2. La transacción ya es una reversión * No puedes revertir una transacción que en sí misma es una reversión. * Esto evita "reversiones de reversiones". #### 3. El estado de la transacción no es APPROVED * Solo puedes revertir transacciones aprobadas. * No puedes revertir una transacción con estado `PENDING`, `CREATED` o `CANCELED`. #### 4. La transacción no se puede revertir * 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 lleve un `routeId` debe hacer referencia a una Operation Route cuyo `operationType` sea `bidirectional`. * Una ruta `source` o `destination` no se puede revertir: Midaz devuelve el error `0150` (Route Not Bidirectional). * Planifica esto al diseñar rutas. Consulta [Accounting Routes](/es/products/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 operativos: #### 1. Reversión de un pago incorrecto Un cliente pagó BRL 500 al proveedor equivocado. * Revierte 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 una compra Una tienda procesó una venta de BRL 1,000, pero el cliente cancela la compra. * Revierte la transacción de venta. * Los fondos regresan a la cuenta del cliente. #### 3. Corrección de un error operativo Un operador creó una transacción con el monto incorrecto. * Revierte la transacción incorrecta. * Crea una transacción nueva con el monto correcto. #### 4. Devolución de un producto Un cliente compró y pagó BRL 200, pero devolvió el producto. * Revierte la transacción de pago. * El cliente recibe una devolución. #### 5. Compensación por fallo de integración Una transacción se aprueba, pero falla en un sistema externo. * Revierte para deshacer la operación contable. * Los saldos regresan a su estado anterior.

Bloqueo y desbloqueo de fondos

*** Algunos escenarios requieren marcar los fondos como **bloqueados** (una retención de cumplimiento, una orden judicial, una investigación por fraude) y **liberarlos** más adelante. Midaz admite esto con dos endpoints dedicados. Estos endpoints crean transacciones cuyas operaciones tienen el tipo `BLOCK` y `UNBLOCK`. Estas transacciones aceptan el **mismo cuerpo** que el endpoint [Crea una transacción con JSON](/es/reference/products/midaz/v1/create-transaction-json), con dos diferencias clave: * **Siempre se registran de inmediato.** Midaz ignora el campo `pending` en el cuerpo de la solicitud y lo reemplaza por `false`. Las transacciones de bloqueo y desbloqueo nunca son de dos fases. Pasan directamente a `APPROVED`. * **Las operaciones tienen el 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 revisar los metadatos. Midaz es **independiente del 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 en el nivel de saldo en [Saldos](/es/products/midaz/balances): los flags de permisos (`allowSending` / `allowReceiving`) y los saldos de garantía. Esos controles restringen el movimiento, pero no registran ninguna transacción. Usa un saldo de garantía para una restricción operativa permanente. Usa una transacción de bloqueo cuando necesites un asiento auditable en el ledger. * Usa el endpoint [Crea una transacción de bloqueo](/es/reference/products/midaz/v1/create-transaction-block) para bloquear fondos. * Usa el endpoint [Crea una transacción de desbloqueo](/es/reference/products/midaz/v1/create-transaction-unblock) para liberar fondos previamente bloqueados. ## Gestión de transacciones *** Puedes gestionar tus Transacciones mediante la API o Lerian Console. ### Mediante la API * [Crea una transacción con JSON](/es/reference/products/midaz/v1/create-transaction-json): envía una transacción directamente mediante un payload JSON. * [Confirma una transacción pendiente](/es/reference/products/midaz/v2/commit-transaction): finaliza una transacción reservada. * [Cancela una transacción pendiente](/es/reference/products/midaz/v2/cancel-transaction): libera los fondos reservados sin ejecutar. * [Revierte una transacción](/es/reference/products/midaz/v2/revert-transaction): crea una transacción de reversión para deshacer una transacción aprobada. * [Crea una transacción de entrada](/es/reference/products/midaz/v1/create-transaction-inflow): registra fondos entrantes de fuentes externas en el ledger. * [Crea una transacción de salida](/es/reference/products/midaz/v1/create-transaction-outflow): mueve fondos de cuentas internas al mundo externo. * [Crea una transacción de bloqueo](/es/reference/products/midaz/v1/create-transaction-block): marca fondos como bloqueados con operaciones del tipo `BLOCK`. * [Crea una transacción de desbloqueo](/es/reference/products/midaz/v1/create-transaction-unblock): libera fondos previamente bloqueados con operaciones del tipo `UNBLOCK`. * [Enumera las transacciones](/es/reference/products/midaz/v2/get-all-transactions): consulta todas las Transacciones de tu espacio de trabajo. * [Obtén una transacción](/es/reference/products/midaz/v2/get-transaction): obtén los detalles de una Transacción específica. * [Actualiza una transacción](/es/reference/products/midaz/v2/update-transaction): edita los metadatos de una Transacción existente. * [Crea una anotación de transacción](/es/reference/products/midaz/v1/create-transaction-annotation): registra una transacción sin impacto financiero en el ledger. ### Mediante Lerian Console Puedes hacer todas las acciones de gestión de Transacciones (ver, crear y cancelar) mediante Lerian Console. Obtén más información en la guía [Gestión de transacciones](/es/products/midaz/console/managing-transactions).