Transacciones - Lerian

Una Transacción en Midaz representa un evento financiero completo, a menudo involucrando múltiples cuentas y saldos. En el corazón de Midaz está un poderoso sistema de contabilidad de doble entrada que asegura que cada movimiento financiero sea preciso, confiable y equilibrado. Con la funcionalidad de múltiples saldos, cada operación puede especificar no solo la cuenta sino también la clave de saldo a usar. Esto permite escenarios avanzados donde los fondos se debitan o acreditan a diferentes saldos lógicos de la misma cuenta (por ejemplo, crédito, operacional, garantía).

Si no se proporciona ninguna balanceKey, la transacción utiliza automáticamente el saldo predeterminado.

Contabilidad de doble entrada

El sistema de doble entrada opera sobre un principio simple pero transformador: para cada transacción, hay dos entradas correspondientes, un débito y un crédito. Este marco asegura que todas las actividades financieras se registren holísticamente, proporcionando una vista completa y equilibrada de sus cuentas. Cada transacción impacta dos cuentas, manteniendo el equilibrio en el ecosistema financiero:

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

Midaz asegura que cada débito y crédito se rastree y equilibre automáticamente, simplificando sus procesos financieros.

Ejemplo

Considere este ejemplo: realice una transacción para transferir R$ 1000 de una cuenta a otra. Este proceso tendrá 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.

En Midaz, estas entradas se capturan automáticamente, asegurando precisión y alineación con su estrategia financiera. El diseño intuitivo de nuestra plataforma le permite ver y analizar estos movimientos sin esfuerzo, promoviendo una cultura de autonomía financiera.

Transacciones N:N (Muchos a Muchos)

A diferencia de los sistemas financieros tradicionales que limitan las transacciones a relaciones uno a uno o uno a muchos, Midaz habilita transacciones N:N, permitiendo múltiples cuentas de origen y destino dentro de una sola transacción.

Ejemplos

Pago de marketplace: múltiples vendedores (varias fuentes) reciben pago de una única cuenta de depósito en garantía, 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 estos casos como una sola transacción atómica, acreditando y debitando a todas las partes de una vez.

Atomicidad e integridad

Las transacciones son operaciones atómicas; o todas las operaciones constituyentes tienen éxito, o ninguna lo hace. Esto asegura que no ocurran eventos financieros parciales. Si alguna parte de una transacción falla la validación (por ejemplo, fondos insuficientes en una cuenta), la transacción completa no se aplicará, preservando la integridad del libro contable.

Origen de la transacción

Las transacciones en Midaz pueden iniciarse desde una o múltiples fuentes.

La suma de los valores en source siempre debe ser igual al valor especificado justo después de send e igual a la suma de los valores en distribute.

Origen único

En una transacción de origen único, la cantidad especificada se toma directamente de una cuenta de origen y, opcionalmente, de un saldo específico.

Ejemplo

En este ejemplo (Figura 1):

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

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": [
        {
          "account": "@account1",
          "balanceKey": "credit", // opcional
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "account": "@destinationAccount1",
          "balanceKey": "operational", // opcional
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Múltiples orígenes

En una transacción de múltiples orígenes, los fondos se extraen de múltiples cuentas y/o saldos.

Ejemplo

En este ejemplo (Figura 2):

BRL 30,00 se enviarán a la cuenta de destino (@destinationAccount1).
- BRL 15,00 de @account1 (saldo default).
- BRL 15,00 de @account2 (saldo investment).
La cuenta de destino recibirá el 100% de la cantidad enviada.

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": [
        {
          "account": "@account1",
          "balanceKey": "default",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        },
        {
          "account": "@account2",
          "balanceKey": "investment",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "account": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Destino de la transacción

Similar a los orígenes, los destinos pueden ser únicos o múltiples.

Destino único

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

Ejemplo

En este ejemplo (Figura 3):

BRL 30,00 se toma de una cuenta externa (@external|BRL).
100% se envía a la cuenta de destino (@destinationAccount1).

Figura 3. Ejemplo de una transacción de destino único.

Ejemplos de código

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

Múltiples destinos

En transacciones de múltiples destinos, la cantidad de la transacción se divide entre múltiples cuentas de destino. Los valores pueden distribuirse por acciones, cantidades fijas o saldo restante.

Ejemplo

En este ejemplo (Figura 4):

BRL 100 se toma 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).

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": "10000",
    "source": {
      "from": [
        {
          "account": "@account1",
          "amount": {
            "asset": "BRL",
            "value": "10000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "account": "@account2",
          "share": {
            "percentage": 38
          }
        },
        {
          "account": "@account3",
          "share": {
            "percentage": 50
          }
        },
        {
          "account": "@account4",
          "amount": {
            "asset": "BRL",
            "value": "200"
          }
        },
        {
          "account": "@account5",
          "remaining": "remaining"
        }
      ]
    }
  }
}

Múltiples orígenes y múltiples destinos

Estas transacciones complejas involucran múltiples orígenes y múltiples destinos. Esto es útil para escenarios como una campaña de crowdfunding, donde las contribuciones se agrupan y distribuyen entre múltiples destinatarios.

Ejemplo

En este ejemplo (Figura 5):

BRL 4.000,00 se donarán, y la cantidad se tomará de cuatro cuentas diferentes.
- 25% se tomará de la cuenta 1 (@account1).
- 25% se tomará de la cuenta 2 (@account2).
- 40% se tomará de la cuenta 3 (@account3)
- 10% se tomará de la cuenta 4 (@account4).
Las donaciones se distribuirán a cuatro cuentas de donación separadas, y cada una recibirá una participación del 25% del total.

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": [
        {
          "account": "@account1",
          "share": {
            "percentage": 25
          }
        },
        {
          "account": "@account2",
          "share": {
            "percentage": 25
          }
        },
        {
          "account": "@account3",
          "share": {
            "percentage": 40
          }
        },
        {
          "account": "@account4",
          "share": {
            "percentage": 10
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "account": "@donation1",
          "share": {
            "percentage": 25
          }
        },
        {
          "account": "@donation2",
          "share": {
            "percentage": 25
          }
        },
        {
          "account": "@donation3",
          "share": {
            "percentage": 25
          }
        },
        {
          "account": "@donation4",
          "share": {
            "percentage": 25
          }
        }
      ]
    }
  }
}

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 se cumple esta condición y la transacción no está marcada como pendiente (flujo de Transacción de Dos Fases), la cantidad especificada se transfiere inmediatamente de la cuenta de origen a la cuenta de destino, utilizando el saldo disponible. Este proceso es sincrónico, y al completarse con éxito, el estado de la transacción será APPROVED.

Los usuarios solo deben iniciar este tipo de transacción si tienen la intención de confirmarla en el libro contable inmediatamente.

Para transacciones que requieren validación o aprobación antes de la ejecución, puede usar la bandera pending para crear una Transacción de dos fases.

Transacción de dos fases

En este escenario, la transacción se crea con estado PENDING. En lugar de mover fondos de inmediato, Midaz reserva la cantidad especificada en el saldo correcto (balanceKey, o default si no se proporciona).

Los fondos reservados se mueven de available a on_hold.
Todavía no se registran operaciones (débitos o créditos) en el libro contable.
Debe ejecutar explícitamente commit para ejecutar la transferencia, o cancel para liberar los fondos.

La función de Transacción de Dos Fases juega un papel clave en Flowker, permitiéndole reservar fondos al comienzo de un flujo de trabajo y realizar validaciones más tarde, con ejecución garantizada si se aprueba.

En la Figura 6, puede encontrar un ejemplo de una transacción de dos fases usando antifraude.

Figura 6. Ejemplo de flujo de trabajo antifraude

Flujo de transacción de dos fases

1. Crear una transacción de dos fases

Use 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:

Los fondos se reservan en el saldo correcto.
El estado de la transacción se establece en PENDING.
Se almacenan metadatos, pero aún no se registra ningún débito/crédito.

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 se registran las operaciones de débito/crédito.
- Use el endpoint Confirmar una Transacción Pendiente.
- Estado: APPROVED.
Cancelar: Libera los fondos reservados de vuelta a disponible en el mismo saldo.
- Use el endpoint Cancelar una Transacción Pendiente.
- Estado: CANCELED.

Transacciones pasadas

Midaz también admite transacciones pasadas, permitiendo a las instituciones importar eventos financieros heredados mientras preservan la precisión histórica.

Use el campo opcional createdAt para establecer la fecha original de la transacción.
Las transacciones con impacto financiero recalculan el estado histórico de los saldos como si se hubieran procesado en esa fecha.
Las transacciones creadas a través de Crear una Anotación de Transacción validan la estructura pero no impactan los saldos. Son útiles para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios.

Ejemplo

{
  "description": "Ejemplo de transacciones pasadas",
  "createdAt": "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"
          }
        }
      ]
    }
  }
}

Al importar datos heredados, envíe todas las transacciones pasadas antes de comenzar las operaciones en vivo. Esto asegura que los saldos se recalculen de manera consistente en todo el libro contable.

Transacciones sin impacto financiero

Midaz admite la creación de transacciones que se registran en el libro contable, pero no afectan los saldos de las cuentas. Estas transacciones aseguran la integridad estructural mientras mantienen los saldos sin cambios. Esta función es útil cuando necesita:

Importar transacciones heredadas sin alterar los saldos.
Registrar eventos de auditoría o cumplimiento.
Agregar operaciones comerciales que deben rastrearse en el Ledger pero no requieren movimiento de fondos.

¿Cómo funciona?

Cuando se crea una transacción sin impacto financiero:

Los campos balance y balanceAfter se almacenan como 0 para preservar la validación de doble entrada.
El campo balanceAffected (booleano) se ha introducido en cada operación:
- true → la operación afecta el saldo de la cuenta.
- false → la operación se registra en el libro contable sin impactar los saldos.

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

Ejemplo

{
  "description": "ejemplo de anotación",
  "createdAt": "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

¿Quiere rastrear el estado de sus transacciones a medida que suceden? Midaz admite la publicación de eventos en tiempo real a través de RabbitMQ. Una vez habilitado, cada transacción genera un evento, como APPROVED, PENDING o CANCELED, al que los sistemas externos pueden suscribirse utilizando enrutamiento basado en temas. Para obtener más información sobre cómo publicar y consumir eventos de transacciones, consulte la página Publicador de eventos.

Entradas, salidas y cuentas externas

Midaz usa un sistema de libro contable de doble entrada en el que todo el valor que entra o sale del sistema debe pasar por una cuenta especial: la Cuenta Externa. Esta cuenta—representada 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 el libro contable se inicializa por primera vez, todas las cuentas—incluida @external—comienzan con un saldo cero. Para reflejar los saldos del mundo real (por ejemplo, fondos institucionales mantenidos externamente), debe iniciar una transacción que inyecte fondos en las cuentas de Midaz debitando 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 Su 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 su cuenta interna. La cuenta externa ahora mostrará un saldo negativo, lo cual es esperado y representa la cantidad total que su organización ha traído al libro contable.

Salidas – Mover valor fuera del Ledger

Para simular que el valor sale 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. En la vida real, su sistema (a través de SPI u otras integraciones) transferirá los fondos al destinatario previsto.

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.

Todos los movimientos de valor entre el mundo exterior y el libro contable de Midaz deben pasar por la cuenta externa.Nada entra o sale del sistema sin una transacción formal, asegurando trazabilidad completa, integridad del saldo y cumplimiento con los principios de doble entrada.

Iniciar una transacción

Hay dos formas principales de iniciar una transacción:

Usando DSL

Esta función está obsoleta y se eliminará en la próxima versión.Actualice sus flujos de trabajo lo antes posible para evitar errores o tiempo de inactividad.

Un Lenguaje Específico de Dominio (DSL) simplifica la interacción del usuario al enfocarse en conceptos de dominio específicos, permitiendo a los no desarrolladores realizar tareas complejas sin habilidades técnicas. Los DSL reducen el código repetitivo e incorporan restricciones en su sintaxis, haciendo cumplir las reglas comerciales y minimizando errores. Sin embargo, sus patrones predefinidos pueden limitar la flexibilidad, dificultando la creación de analizadores personalizados o la adaptación a nuevos requisitos. El DSL de Transacciones en Midaz, llamado Gold, simplifica el procesamiento de transacciones con una sintaxis contable intuitiva. Almacena información de transacciones en archivos .gold, permitiendo a los equipos de negocio definir transacciones fácilmente y fomentando la colaboración entre flujos de trabajo técnicos y comerciales. Para usar el DSL, siga estos pasos:

Cree el archivo .gold según la estructura del DSL de Transacciones.

Envíe el archivo usando el endpoint Crear una Transacción usando DSL.

¿Quiere profundizar en la estructura del DSL? Consulte la página DSL de Transacciones para más detalles.

Usando endpoint JSON

Los endpoints JSON proporcionan un estándar flexible y amigable para desarrolladores para el intercambio de datos, permitiendo un control preciso sobre las estructuras de solicitud adaptadas para flujos de trabajo personalizados y casos de uso específicos. Su amplia compatibilidad con varios lenguajes de programación facilita la integración y la depuración. Sin embargo, esta flexibilidad puede resultar en verbosidad y errores del usuario, ya que se requiere que los desarrolladores manejen la validación manualmente. Para los no desarrolladores, la complejidad de JSON puede presentar desafíos, haciéndolo menos intuitivo que un Lenguaje Específico de Dominio (DSL) para tareas cotidianas.

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

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

Rutas de transacción

La API de Rutas de transacción habilita el procesamiento estructurado y validado de transacciones en Midaz. Mientras que la API de Transacciones maneja la ejecución de eventos financieros (débitos y créditos entre cuentas), las Rutas de Transacción definen plantillas para cómo estos eventos deben estructurarse y validarse, asegurando consistencia e integridad. Piense en ello como la capa de validación que asegura que las transacciones comerciales sigan patrones predefinidos y mantengan la estructura financiera adecuada. Por ejemplo, una transacción para una comisión, un depósito o un pago puede requerir diferentes tipos de cuenta, reglas de validación y estructuras. En lugar de manejar la validación por separado para cada transacción, configura reglas predefinidas que le dicen a Midaz: “Cuando el usuario envíe este tipo de transacción, valídela contra estos requisitos de cuenta y patrones de estructura.” Cada Ruta de Transacción combina múltiples Rutas de operación, que definen los componentes individuales de una transacción, especificando requisitos de cuenta, direcciones (origen/destino) y reglas de validación para cada “tramo” del evento financiero.

¿Por qué importa?

Al usar Rutas de transacción, usted:

Asegura una estructura de transacción consistente en toda su aplicación.
Hace que su libro contable sea más mantenible, predecible y confiable.
Valida eventos financieros contra patrones predefinidos.
Habilita la configuración de plantillas de transacción sin cambios de código.
Mantiene la integridad de datos a través de la validación estructurada.

Gestión de transacciones

Puede gestionar sus transacciones a través de API o mediante Midaz Console.

Vía API

Crear una Transacción usando DSL (obsoleto) — Enviar un archivo de transacción usando el DSL de Midaz.
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.
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.
Listar Transacciones — Ver todas las Transacciones en su 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 Console

Todas las acciones de gestión de Transacciones, incluidas ver, crear, editar y eliminar, se pueden realizar a través de la página de Organizaciones en Midaz Console. Obtenga más información en la guía Gestión de Transacciones.

Empezando

Entendiendo Midaz

Instalación e implementación

Casos de uso

Entidades centrales

Mejores prácticas

Midaz SDKs & libs

​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

​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

​Iniciar una transacción

​Usando DSL

​Usando endpoint JSON

​Rutas de transacción

​¿Por qué importa?

​Gestión de transacciones

​Vía API

​Vía 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

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

Iniciar una transacción

Usando DSL

Usando endpoint JSON

Rutas de transacción

¿Por qué importa?

Gestión de transacciones

Vía API

Vía Console