Saltar al contenido principal
El Enrutamiento de Transacciones es el sistema de validación de dos capas de Midaz para transacciones financieras, construido a partir de Rutas de Transacción (que definen el patrón completo de la transacción) y Rutas de Operación (que validan cada operación individual dentro de ese patrón). Juntas, aseguran que cada transacción sea estructuralmente correcta y cumpla con sus reglas de negocio.
  • Las Rutas de Transacción definen la estructura completa de una transacción — la secuencia requerida de operaciones y cómo encajan para formar un evento financiero válido.
  • Las Rutas de Operación definen las reglas para cada operación individual (o “tramo”) de esa transacción, incluyendo el tipo de cuenta esperado o cuenta específica, la anotación contable y si es un débito o crédito.
Cuando se envía una transacción, Midaz la valida en dos capas: Las Rutas de Transacción aseguran que la estructura general coincida con el patrón predefinido, mientras que las Rutas de Operación confirman que cada componente cumpla con los requisitos de cuenta y reglas de negocio. Si alguna parte de la transacción falla estas verificaciones, se rechaza antes de que pueda ser registrada — protegiendo la integridad de su libro contable sin limitar su flexibilidad.
Usted define los patrones de validación a través de las Rutas de Operación y Rutas de Transacción. Midaz asegura que sus transacciones cumplan con estas reglas antes de procesarlas.

​
¿Para qué sirve el Enrutamiento de Transacciones?

El Enrutamiento de Transacciones proporciona control estructurado sobre sus operaciones financieras al separar la lógica de transacción del código de negocio. En lugar de codificar reglas de validación en su aplicación, usted configura patrones reutilizables que aseguran que cada movimiento financiero siga los requisitos de su organización. Estas entidades están dedicadas a vincular Transacciones y Operaciones del libro contable de Midaz con abstracciones de nivel superior que facilitan la integración con plugins especializados y sistemas externos, especialmente para abstracciones de contabilidad y tesorería. Las anotaciones estructuradas y clasificaciones crean un vocabulario estandarizado que otros componentes pueden entender y aprovechar. Este enfoque ofrece:
  • Consistencia: Todas las transacciones siguen estructuras predefinidas independientemente de dónde se originen.
  • Flexibilidad: Adapte el diseño de su libro contable para que coincida con las necesidades de su negocio sin cambios de código.
  • Integridad: La validación automática previene que transacciones mal formadas afecten su libro contable.
  • Mantenibilidad: La configuración centralizada facilita la actualización de reglas financieras a medida que su negocio evoluciona.
  • Interoperabilidad: Los campos con semántica de negocio permiten una integración perfecta con plugins contables y sistemas financieros externos.
Ya sea que esté procesando transferencias simples o transacciones complejas de múltiples partes, el Enrutamiento de Transacciones asegura que sus datos financieros permanezcan estructurados, validados y confiables a escala, mientras proporciona la base semántica para integraciones avanzadas.

​
Trabajando con el Enrutamiento de Transacciones

Para usar el Enrutamiento de Transacciones, debe completar la configuración inicial seguida de la ejecución continua de transacciones. Aquí está su proceso paso a paso:

​
Configuración Inicial

​
1. Configurar Ledger para validación de ruta de transacción

Para activar la validación de ruta de transacción para un Ledger específico, habilite las configuraciones de validación a través de la API de Configuraciones del Ledger. Esto controla si las transacciones en ese Ledger deben cumplir con sus rutas configuradas. 
{
  "accounting": {
    "validateRoutes": true,
    "validateAccountType": true
  }
}
  • validateRoutes: Cuando está habilitada, cada transacción debe hacer referencia a una ruta de transacción válida.
  • validateAccountType: Cuando está habilitada, los tipos de cuenta se validan contra las reglas de las rutas de operación.
Los cambios en las configuraciones surten efecto inmediatamente — no se requiere redespliegue. Puede actualizarlas en cualquier momento a través de la API.

​
2. Crear Rutas de Operación

Cree rutas de operación que definan reglas de validación y comportamiento para componentes individuales de transacción. Campos clave:
  • title: Etiqueta breve que identifica la ruta de operación.
  • description: Explicación detallada opcional.
  • metadata: Pares clave-valor para contexto de negocio y categorización personalizada.
  • operationType: La dirección contable para esta ruta — source, destination o bidirectional.
    • source — Identifica cuentas donde se originan los fondos (lado débito).
    • destination — Identifica cuentas donde se envían los fondos (lado crédito).
    • bidirectional — Se aplica a ambos lados de la transacción, actuando como origen y destino.
  • account: Reglas de validación opcionales que especifican el tipo de cuenta requerido o cuenta específica.
    • ruleType: Tipo de regla de validación de cuenta (account_type, alias).
    • validIf: El valor esperado que debe coincidir para que la validación pase.
  • accountingEntries: Asientos contables opcionales para cada tipo de acción. Consulte Asientos Contables a continuación.
Configure las reglas de cuenta según sus necesidades: Opción A: Sin Regla de Cuenta Si no necesita validación de cuenta para la ruta de operación, omita el objeto account: 
{
    "title": "Cobro de tarifas",
    "description": "Ruta de operación para cobrar tarifas de servicio de las transacciones de los usuarios",
    "metadata": {
        "businessUnit": "pagos",
        "category": "ingresos"
    },
    "operationType": "source"
}
Opción B: Regla de Validación de Cuenta Si necesita validación de cuenta para la operación, configure reglas de cuenta basadas en la configuración de su libro contable:
  • Apuntar a Cuenta Específica
Valide contra una cuenta específica usando su alias. 
{
    "title": "Cobro de ingresos por tarifas",
    "description": "Ruta de operación para acreditar las tarifas cobradas en la cuenta de ingresos",
    "metadata": {
        "businessUnit": "pagos",
        "category": "ingresos"
    },
    "operationType": "destination",
    "account": {
        "ruleType": "alias",
        "validIf": "@external/BRL"
    }
}
  • Apuntar a Tipo de Cuenta
Valide contra tipos de cuenta específicos. 
{
    "title": "Tarifa de retiro del usuario",
    "description": "Ruta de operación para cobrar tarifas de las transacciones de retiro de los usuarios",
    "metadata": {
        "businessUnit": "pagos",
        "category": "tarifa"
    },
    "operationType": "source",
    "account": {
        "ruleType": "account_type",
        "validIf": ["user_wallet", "asset"]
    }
}
Opción C: Con asientos contables Cada etapa del ciclo de vida de una transacción — ejecución, liquidación, cancelación, reversión — puede requerir sus propias anotaciones contables. El campo accountingEntries mapea cada etapa a los códigos contables de partida doble correctos automáticamente. Configure los asientos contables para cada tipo de acción: 
{
    "title": "PIX Cash-in - Current Account",
    "description": "Operation route for receiving PIX payments into current account",
    "code": "PIX-CASHIN-001",
    "operationType": "source",
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.001",
                "description": "Cash - Available funds"
            },
            "credit": {
                "code": "3.1.001",
                "description": "Service Revenue"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.002",
                "description": "Clearing Values"
            },
            "credit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            }
        }
    },
    "account": {
        "ruleType": "alias",
        "validIf": "@current_account"
    },
    "metadata": {
        "channel": "pix"
    }
}
Cada tipo de acción (direct, hold, commit, cancel, revert) se mapea a un par contable de partida doble — permitiendo que su ledger anote automáticamente las operaciones con los códigos contables correctos según la etapa del ciclo de vida de la transacción.
El campo operationType ahora también admite bidirectional, lo que permite que la ruta opere en ambas direcciones — útil para rutas que manejan tanto envío como recepción, o para operaciones que pueden necesitar ser revertidas.

​
Matriz de validación de entradas contables

No toda combinación de operationType y acción es válida. Midaz aplica una matriz de validación estricta cuando creas o actualizas una Ruta de Operación — si las reglas no se cumplen, la solicitud se rechaza antes de persistirse. Comprender esta matriz es crítico para los integradores: enviar una combinación inválida devuelve el error 0166 (campo requerido) o 0162/0165 (escenario no permitido para la dirección). source
AcciónDébitoCréditoNotas
directRequeridoOpcionalTransacción estándar de un paso en el origen
holdRequeridoRequeridoReserva fondos — mueve available → on_hold
commitRequeridoOpcionalFinaliza una transacción de dos fases
cancelRequeridoRequeridoLibera los fondos reservados — mueve on_hold → available
revert——No permitido (error 0165). Usa bidirectional en su lugar
destination
AcciónDébitoCréditoNotas
directOpcionalRequeridoTransacción estándar de un paso en el destino
hold——No permitido (error 0162)
commitOpcionalRequeridoFinaliza una transacción de dos fases
cancel——No permitido (error 0162)
revert——No permitido (error 0165). Usa bidirectional en su lugar
bidirectional
AcciónDébitoCréditoNotas
directRequeridoRequeridoAmbos lados de la partida doble
holdRequeridoRequeridoAmbos lados de la partida doble
commitRequeridoRequeridoAmbos lados de la partida doble
cancelRequeridoRequeridoAmbos lados de la partida doble
revertRequeridoRequeridoÚnica dirección que admite revert
Una entrada sin debit ni credit siempre es rechazada, independientemente del tipo de operación o acción.
Reglas adicionales:
  • Atomicidad del grupo de reserva: Si defines hold, también debes definir commit y cancel (y viceversa). Estas tres acciones forman un grupo atómico — no puedes configurar una sin las otras.
  • direct es obligatorio: Si se define cualquier otra acción (hold, commit, cancel, revert), direct también debe estar presente. Sirve como la entrada base para la ruta de operación.
Al diseñar tus rutas de operación, comienza con la acción direct y agrega hold/commit/cancel solo si necesitas soporte para transacciones de dos fases. Agrega revert solo en rutas bidirectional.

​
3. Construir Rutas de Transacción

Complete su configuración combinando Rutas de Operación en Rutas de Transacción. Estas definen sus patrones de transacción completos, mapeando cómo diferentes operaciones trabajan juntas para formar eventos financieros equilibrados que coinciden con sus procesos de negocio.
El campo operationRoutes ahora utiliza un array de objetos con operationRouteId en lugar de un array simple de UUIDs. Si tiene integraciones existentes, actualícelas para usar el nuevo formato.
{
    "title": "Transacción de tarifa",
    "description": "Transacción completa para cobrar tarifas de operaciones de retiro de usuarios",
    "metadata": {
        "transactionType": "cashout_fee",
        "businessFlow": "withdrawal_processing"
    },
    "operationRoutes": [
        {
            "operationRouteId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
        },
        {
            "operationRouteId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
        }
    ]
}

​
4. Configurar Asientos Contables (Acciones)

Cada Ruta de Operación puede incluir Asientos Contables — rúbricas estructuradas que definen cómo se registran los asientos de débito y crédito para cada tipo de evento transaccional. Cuando un Ledger está configurado para validar rutas, solo se permiten los eventos con asientos registrados. Esto garantiza consistencia en sus reportes contables.
Tipos de acción
Cada acción representa un evento transaccional. Usted configura asientos contables por acción en cada Ruta de Operación:
AcciónIdentificadorDescripción
Transacción DirectadirectTransacción estándar de un solo paso entre dos cuentas, sin etapas intermedias.
Hold (Reserva de Valor)holdPrimer paso de una Transacción en Dos Fases: mueve el valor del saldo available al on_hold en la cuenta de origen.
Commit (Confirmación)commitConfirma una Transacción en Dos Fases pendiente, transfiriendo el valor on_hold de la cuenta de origen al saldo available en la cuenta de destino.
CancelcancelCancela una Transacción en Dos Fases pendiente, devolviendo el valor on_hold al saldo available en la cuenta de origen.
RevertrevertCrea una transacción inversa que deshace la operación original.
Estructura del asiento contable
Cada entrada de acción contiene una rúbrica de débito y/o crédito, dependiendo del tipo de operación:
  • Las rutas Source requieren la rúbrica de débito.
  • Las rutas Destination requieren la rúbrica de crédito.
  • Las rutas Bidirectional requieren ambas rúbricas de débito y crédito.
Cada rúbrica tiene:
  • code — El código del plan de cuentas (ej., 1.1.1.001).
  • description — Una descripción legible del asiento (ej., Customer checking — outbound).
{
    "title": "Pix Transfer",
    "description": "Bidirectional route for Pix transfers between checking accounts",
    "operationType": "bidirectional",
    "account": {
        "ruleType": "account_type",
        "validIf": ["checking"]
    },
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — reserve"
            },
            "credit": {
                "code": "2.1.1.001",
                "description": "Pending settlement — hold"
            }
        },
        "commit": {
            "debit": {
                "code": "2.1.1.001",
                "description": "Pending settlement — release"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — settled"
            }
        }
    }
}
Comportamiento de validación
Cuando la validación de rutas está habilitada para un Ledger y los asientos contables están configurados:
  • Solo se permiten los eventos con asientos registrados. Si un cliente registra solo la acción direct en una ruta, cualquier intento de ejecutar una Transacción en Dos Fases (que requiere hold) será rechazado automáticamente.
  • Las operaciones exitosas tendrán los detalles de la rúbrica registrados en los campos routeCode y routeDescription de cada operación.
Si una ruta tiene asientos contables configurados pero la transacción enviada utiliza una acción que no está registrada, la transacción será denegada. Esto previene discrepancias en sus reportes contables al asegurar que todas las etapas de una operación estén correctamente mapeadas antes de la ejecución.
Escenario: Un cliente crea una Ruta de Operación con solo la acción direct configurada.Si ese cliente intenta una Transacción en Dos Fases (enviando pending: true), la transacción es rechazada automáticamente porque no hay un asiento hold registrado.Esto asegura que sus reportes contables permanezcan consistentes — todas las etapas de una operación deben estar mapeadas antes de poder ser ejecutadas.

​
Operaciones Continuas

​
5. Ejecutar Transacciones Validadas

Con su configuración de enrutamiento en su lugar, ahora puede enviar transacciones con confianza incluyendo el ID de la Ruta de Transacción previamente creada en su solicitud de transacción. Midaz validará automáticamente la transacción contra sus patrones de enrutamiento definidos, asegurando consistencia e integridad en todas las operaciones financieras. Para los ejemplos de Ruta de Transacción y Rutas de Operación previamente configurados, el sistema compone la siguiente estructura de validación: 
Ruta de transacción: "Transacción de tarifa" (ID: 5656daa5-5b2a-4637-955f-e43bafceaf5d)

├── Ruta de operación 1: "Tarifa de retiro del usuario" (ID: 0197e6aa-1695-734a-a8c3-8c79e0ad32c2)
│ ├── Tipo: origen
│ ├── Regla de cuenta: account_type ["user_wallet", "asset"]
│ └── Valida: operaciones de origen en transacciones
└── Ruta de operación 2: "Cobro de ingresos por tarifas" (ID: 0197e675-37cc-71d7-96c2-f58000f33aa0)
    ├── Tipo: destino
    ├── Regla de cuenta: alias "@external/BRL"
    └── Valida: operaciones de destino en transacciones
Para propiedades de ruta en transacciones Midaz, una solicitud de payload apropiada:

{
    "route": "5656daa5-5b2a-4637-955f-e43bafceaf5d",
    "description": "Transacción de cobro de tarifa por retiro",
    "send": {
        "asset": "BRL",
        "value": "10",
        "source": {
            "from": [
                {
                    "accountAlias": "@user/wallet_123",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Débito de tarifa desde la billetera del usuario",
                    "route": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
                }
            ]
        },
        "distribute": {
            "to": [
                {
                    "accountAlias": "@external/BRL",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Crédito de tarifa a la cuenta de ingresos",
                    "route": "0197e675-37cc-71d7-96c2-f58000f33aa0"
                }
            ]
        }
    }
}
Cuando se envía esta transacción, Midaz valida que la cuenta @user/wallet_123 coincida con la regla de tipo de cuenta user_wallet, y que @external/BRL coincida con el requisito de alias exacto, asegurando que la transacción siga sus patrones de enrutamiento configurados.
Campos de ruta en operaciones
Cuando la validación de rutas está habilitada y los asientos contables están configurados, cada operación procesada exitosamente incluirá dos campos adicionales poblados a partir de la rúbrica coincidente:
  • routeCode — El código del plan de cuentas de la rúbrica del asiento contable coincidente.
  • routeDescription — La descripción de la rúbrica del asiento contable coincidente.
Estos campos proporcionan un enlace directo entre cada operación y su clasificación contable, permitiendo que sistemas posteriores (como Reporter) produzcan reportes financieros precisos sin búsquedas adicionales.

​
Gestión de Rutas de Operación y Transacción

Para configurar sus Rutas de Operación, use los siguientes endpoints: Para configurar sus Rutas de Transacción, use los siguientes endpoints: