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 Libro Contable para Validación de Ruta de Transacción

Para activar la validación de ruta de transacción para un libro contable específico, debe configurarlo en el servicio de Transacción. Esto significa actualizar las variables de Transacción en el archivo .env del servicio Midaz Transaction donde desea usar la validación de ruta. Su configuración debería verse así: 
# Lista de <organization-id>:<ledger-id> separados por coma
TRANSACTION_ROUTE_VALIDATION=

​
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: source o destination indicando el flujo direccional de la operación.
  • 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.
Configúrelos 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"]
    }
}

​
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. 
{
    "title": "Transacción de tarifa",
    "description": "Transacción completa para cobrar tarifas de las operaciones de retiro de los usuarios",
    "metadata": {
        "transactionType": "cashout_fee",
        "businessFlow": "withdrawal_processing"
    },
    "operationRoutes": [
        "0197e6aa-1695-734a-a8c3-8c79e0ad32c2",
        "0197e675-37cc-71d7-96c2-f58000f33aa0"
    ]
}

​
Operaciones Continuas

​
4. 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.

​
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:
⌘I