Rutas Contables

Valida cada Transacción con Rutas Contables y Rutas de Operación — aplica estructura y reglas de negocio antes de registrar cualquier movimiento.

Las Rutas Contables son el sistema de validación de dos capas de Midaz para transacciones financieras. Las Rutas Contables definen el patrón completo de la transacción. Las Rutas de Operación validan cada operación dentro de ese patrón. Juntas, mantienen cada transacción estructuralmente correcta y en cumplimiento con tus reglas de negocio.

Nomenclatura: La Lerian Console y la documentación del producto llaman a este concepto Rutas Contables (Accounting Routes). En la API y los SDKs, el recurso transactionRoute representa la ruta a nivel de transacción, con los endpoints transaction-route. Los dos términos se refieren a lo mismo.

• Las Rutas Contables definen la estructura completa de una transacción: la secuencia requerida de operaciones que forma un evento financiero válido.
• Las Rutas de Operación definen las reglas para cada operación (o “tramo”) de esa transacción. Cada regla establece el tipo de cuenta esperado o la cuenta específica, la anotación contable y el lado de débito o crédito.

Cuando envías una transacción, Midaz la valida en dos capas. La capa de Rutas Contables verifica que la estructura general coincida con el patrón predefinido. La capa de Rutas de Operación verifica que cada componente cumpla con los requisitos de cuenta y las reglas de negocio.

Si alguna parte de la transacción falla estas verificaciones, Midaz la rechaza antes de registrar la transacción. Esto protege la integridad de tu libro contable y no limita su flexibilidad.

Tú defines los patrones de validación a través de las Rutas de Operación y las Rutas Contables. Midaz verifica que tus transacciones cumplan con estas reglas antes de procesarlas.

​

¿Para qué sirven las Rutas Contables?

---

Las Rutas Contables proporcionan control estructurado sobre tus operaciones financieras al separar la lógica de transacción del código de negocio. En lugar de codificar reglas de validación en tu aplicación, configuras patrones reutilizables. Estos patrones hacen que cada movimiento financiero siga los requisitos de tu organización.

Estas entidades vinculan Transacciones y Operaciones del libro contable de Midaz con abstracciones de nivel superior. Estas abstracciones te ayudan a integrar plugins especializados y sistemas externos, especialmente para contabilidad y tesorería. Las anotaciones y clasificaciones estructuradas crean un vocabulario estandarizado que otros componentes pueden entender y usar.

Este enfoque ofrece:

• Consistencia: Todas las transacciones siguen estructuras predefinidas independientemente de dónde se originen.
• Flexibilidad: Adapta el diseño de tu libro contable para que coincida con las necesidades de tu negocio sin cambios de código.
• Integridad: La validación automática previene que transacciones mal formadas afecten tu libro contable.
• Mantenibilidad: La configuración centralizada facilita la actualización de reglas financieras a medida que tu negocio evoluciona.
• Interoperabilidad: Los campos con semántica de negocio te permiten integrar plugins contables y sistemas financieros externos.

Las Rutas Contables mantienen tus datos financieros estructurados y validados para transferencias simples y transacciones complejas de múltiples partes. También proporcionan la base semántica para integraciones avanzadas.

​

Trabajando con las Rutas Contables

---

Para usar las Rutas Contables, completas una configuración inicial única y luego ejecutas transacciones. Los pasos a continuación muestran el proceso completo.

​

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, habilita las configuraciones de validación a través de la API de Configuración del Ledger. Esto controla si las transacciones en ese Ledger deben cumplir con tus rutas configuradas.

PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings

{
  "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, Midaz rechaza una cuenta cuyo type no sea un Tipo de cuenta registrado. Esto controla la creación de cuentas, no las transacciones — la regla account_type de una Ruta de operación la aplica validateRoutes, con independencia de esta bandera.

Los cambios en las configuraciones no requieren redespliegue: puedes actualizarlas en cualquier momento a través de la API. La escritura invalida la caché de configuraciones, pero las lecturas se almacenan en caché durante 5 minutos, así que espera hasta ese tiempo para que todas las réplicas observen el cambio.

​

2. Crear Rutas de Operación

Crea 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.

• code (obsoleto): una referencia externa heredada que se mantiene por retrocompatibilidad. El motor no lo escribe en las operaciones. En su lugar, registra el code de la rúbrica resuelta (de accountingEntries) como routeCode en cada 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 que reciben los fondos (lado crédito).
  • bidirectional — Se aplica a ambos lados de la transacción, como origen y destino.

• account: Reglas de validación opcionales que establecen un tipo de cuenta requerido o una 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. Consulta Asientos Contables a continuación.

Configura las reglas de cuenta según tus necesidades:

Opción A: Sin Regla de Cuenta

Si no necesitas validación de cuenta para la ruta de operación, omite el objeto account:

JSON

 {
    "title": "Fee Collection",
    "description": "Operation route for collecting service fees from user transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "source"
}

Opción B: Regla de Validación de Cuenta

Si necesitas validación de cuenta para la operación, configura reglas de cuenta basadas en la configuración de tu libro contable:

• Apuntar a Cuenta Específica

Valida contra una cuenta específica usando su alias.

JSON

{
    "title": "Fee Revenue Collection",
    "description": "Operation route for crediting collected fees to revenue account",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "destination",
    "account": {
        "ruleType": "alias",
        "validIf": "@external/BRL"
    }
}

• Apuntar a Tipo de Cuenta

Valida contra tipos de cuenta específicos.

JSON

{
    "title": "User Cashout Fee",
    "description": "Operation route for collecting fees from user cashout transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "fee"
    },
    "operationType": "source",
    "account": {
        "ruleType": "account_type",
        "validIf": ["user_wallet", "asset"]
    }
}

Opción C: Con Asientos Contables

Adjunta asientos contables directamente a la ruta de operación a través del campo accountingEntries. Este campo mapea cada etapa del ciclo de vida de la transacción a los códigos contables de partida doble correctos. Consulta Configurar Asientos Contables (Acciones) a continuación para el modelo completo de tipos de acción, los requisitos de débito/crédito y la matriz de validación.

Una ruta con asientos contables configurados:

JSON

{
    "title": "PIX Cash-in - Current Account",
    "description": "Operation route for receiving PIX payments into current account",
    "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"
            }
        },
        "commit": {
            "debit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            },
            "credit": {
                "code": "3.1.001",
                "description": "Service Revenue"
            }
        },
        "cancel": {
            "debit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            },
            "credit": {
                "code": "1.1.002",
                "description": "Clearing Values"
            }
        }
    },
    "account": {
        "ruleType": "alias",
        "validIf": "@current_account"
    },
    "metadata": {
        "channel": "pix"
    }
}

El campo operationType también admite bidirectional. Una ruta bidireccional opera en ambas direcciones. Úsala para rutas que tanto envían como reciben, o para operaciones que puedas necesitar revertir.

​

3. Construir Rutas Contables

Completa tu configuración combinando Rutas de Operación en Rutas Contables (el recurso transactionRoute en la API). Estas definen tus patrones de transacción completos. Cada patrón mapea cómo las operaciones trabajan juntas para formar eventos financieros equilibrados que coinciden con tus procesos de negocio.

El campo operationRoutes utiliza un array de objetos con operationRouteId en lugar de un array simple de strings UUID.

JSON

{
    "title": "Fee Transaction",
    "description": "Complete transaction for collecting fees from user cashout operations",
    "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. Estas rúbricas estructuradas definen cómo Midaz registra los asientos de débito y crédito para cada evento transaccional: direct, hold, commit, cancel y revert, además de tres claves complementarias — overdraft, block y unblock — que describen impacto contable pero no son acciones válidas de ruta de transacción. El motor las utiliza para resolver qué cuentas debita y acredita en cada acción. También determinan las anotaciones routeCode y routeDescription en cada operación.

La configuración accounting.validateRoutes en la Configuración del Ledger controla este comportamiento. Cuando la habilitas, Midaz rechaza una ruta de operación que falta o no coincide, y devuelve 0117 ErrAccountingRouteNotFound. Cuando la deshabilitas, la resolución de rutas es de mejor esfuerzo. Una rúbrica faltante deja routeCode vacío y no detiene la transacción.

La página de Asientos Contables documenta el modelo completo en detalle. Esto incluye las acciones de asiento contable, los requisitos de débito/crédito por tipo de operación, los modos de validación tolerante y estricto, y ejemplos de configuración. Esta sección cubre solo cómo se adjuntan las rúbricas a las Rutas de Operación.

A nivel de ruta, proporcionas los asientos contables a través del bloque accountingEntries. Consulta la Opción C en Crear Rutas de Operación arriba. Cada acción toma un asiento con una rúbrica de debit, una rúbrica de credit, o ambas, según el operationType de la ruta:

• 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.

Matriz de validación de asientos 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 coinciden, Midaz rechaza la solicitud antes de persistir la ruta.

Esta matriz es crítica para los integradores. Una combinación inválida devuelve el error 0166 (campo requerido) o 0162/0165 (escenario no permitido para la dirección).

source

Acción	Débito	Crédito	Notas
direct	Requerido	Opcional	Transacción estándar de un paso en el origen
hold	Requerido	Requerido	Reserva fondos — mueve available → on_hold
commit	Requerido	Opcional	Finaliza una transacción de dos fases
cancel	Requerido	Requerido	Libera los fondos reservados — mueve on_hold → available
revert	—	—	No permitido (error 0165). Usa bidirectional en su lugar

destination

Acción	Débito	Crédito	Notas
direct	Opcional	Requerido	Transacción estándar de un paso en el destino
hold	—	—	No permitido (error 0162)
commit	Opcional	Requerido	Finaliza una transacción de dos fases
cancel	—	—	No permitido (error 0162)
revert	—	—	No permitido (error 0165). Usa bidirectional en su lugar

bidirectional

Acción	Débito	Crédito	Notas
direct	Requerido	Requerido	Ambos lados de la partida doble
hold	Requerido	Requerido	Ambos lados de la partida doble
commit	Requerido	Requerido	Ambos lados de la partida doble
cancel	Requerido	Requerido	Ambos lados de la partida doble
revert	Requerido	Requerido	Única dirección que admite revert

Si un asiento no tiene ni debit ni credit, Midaz lo rechaza, independientemente del tipo de operación o acción.

Reglas adicionales:

• Atomicidad del grupo de reserva: En rutas source y bidirectional, si defines hold, también debes definir commit y cancel (y viceversa). Estas tres acciones forman un grupo atómico ahí; no puedes configurar ninguna de ellas de forma aislada. En rutas destination, hold y cancel no están permitidos (error 0162), así que puedes configurar commit sin ellos; direct sigue siendo obligatorio según la regla siguiente.
• direct es obligatorio: Si defines cualquier otra acción (hold, commit, cancel, revert, overdraft, block, unblock), también debes definir direct. Sirve como la entrada base para la ruta de operación.
• overdraft requiere ambas rúbricas en todo operationType, incluidos source y destination.
• block y unblock replican direct: débito en una ruta source, crédito en una ruta destination, ambos en bidirectional.
• Cualquier clave fuera de estas ocho se rechaza con el error 0053 (Unexpected Fields).

Al diseñar tus rutas de operación, comienza con la acción direct. Agrega hold/commit/cancel solo si necesitas soporte para transacciones de dos fases. Agrega revert solo en rutas bidirectional.

​

Operaciones Continuas

​

5. Ejecutar Transacciones Validadas

Con tu configuración de enrutamiento en su lugar, ahora puedes enviar transacciones. En la solicitud de transacción, incluye el ID de la Ruta Contable que creaste. Midaz luego valida la transacción contra tus patrones de enrutamiento. Esto mantiene todas las operaciones financieras consistentes y correctas.

Para la Ruta Contable y las Rutas de Operación configuradas arriba, Midaz compone la siguiente estructura de validación:

text

Transaction Route: "Fee Transaction" (ID: 5656daa5-5b2a-4637-955f-e43bafceaf5d)

├── Operation Route 1: "User Cashout Fee" (ID: 0197e6aa-1695-734a-a8c3-8c79e0ad32c2)
│   ├── Type: source
│   ├── Account Rule: account_type ["user\_wallet", "asset"]
│   └── Validates: source operations in transactions
└── Operation Route 2: "Fee Revenue Collection" (ID: 0197e675-37cc-71d7-96c2-f58000f33aa0)
    ├── Type: destination
    ├── Account Rule: alias "@external/BRL"
    └── Validates: destination operations in transactions

Para propiedades de ruta en transacciones Midaz, una solicitud de payload apropiada:

JSON

{
    "routeId": "5656daa5-5b2a-4637-955f-e43bafceaf5d",
    "description": "Cashout fee collection transaction",
    "send": {
        "asset": "BRL",
        "value": "10",
        "source": {
            "from": [
                {
                    "accountAlias": "@user/wallet_123",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Fee debit from user wallet",
                    "routeId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
                }
            ]
        },
        "distribute": {
            "to": [
                {
                    "accountAlias": "@external/BRL",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Fee credit to revenue account",
                    "routeId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
                }
            ]
        }
    }
}

Cuando envías esta transacción, Midaz valida dos cosas. La cuenta @user/wallet_123 debe coincidir con la regla de tipo de cuenta user_wallet. La cuenta @external/BRL debe coincidir con el alias exacto. Ambas verificaciones confirman que la transacción sigue tus patrones de enrutamiento.

Campos de ruta en operaciones

Cuando habilitas la validación de rutas y configuras los asientos contables, cada operación procesada incluye dos campos adicionales. Midaz completa estos campos a partir de la rúbrica coincidente:

• routeCode — El code de la AccountingRubric resuelta para la acción y dirección de esa operación.
• routeDescription — La descripción de la rúbrica contable resuelta. Midaz la completa junto con routeCode.

Estos campos vinculan cada operación con su clasificación contable. Los sistemas posteriores como Reporter pueden entonces producir reportes financieros precisos sin búsquedas adicionales.

​

Gestión de Rutas de Operación y Rutas Contables

---

Para configurar tus Rutas de Operación, usa los siguientes endpoints:

• Crear una Ruta de Operación — Definir una nueva regla contable para tus operaciones.
• Listar Rutas de Operación — Ver todas las Rutas de Operación configuradas.
• Recuperar una Ruta de Operación — Obtener información detallada sobre una Ruta de Operación específica.
• Actualizar una Ruta de Operación — Modificar reglas contables existentes.
• Eliminar una Ruta de Operación — Eliminar una Ruta de Operación obsoleta o no utilizada.

Para configurar tus Rutas Contables (el recurso transactionRoute en la API), usa los siguientes endpoints:

• Crear una Ruta de Transacción — Definir nueva lógica de enrutamiento para conectar transacciones con operaciones contables.
• Listar Rutas de Transacción — Ver todas las Rutas de Transacción configuradas.
• Recuperar una Ruta de Transacción — Obtener detalles de una Ruta de Transacción específica.
• Actualizar una Ruta de Transacción — Modificar criterios de enrutamiento existentes.
• Eliminar una Ruta de Transacción — Eliminar rutas que ya no sean aplicables.