> ## 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. # 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, construido a partir de **Rutas Contables** (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 tus reglas de negocio. **Nomenclatura:** Este concepto se llama **Rutas Contables** (Accounting Routes) en la Lerian Console y en la documentación del producto. En la API y los SDKs, la ruta a nivel de transacción se representa con el recurso `transactionRoute` (y los endpoints `transaction-route`). Ambos términos se refieren a lo mismo. * **Las Rutas Contables** 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 Contables** 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 tu libro contable sin limitar su flexibilidad. Tú defines los patrones de validación a través de las Rutas de Operación y Rutas Contables. Midaz asegura 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 que aseguran que cada movimiento financiero siga los requisitos de tu 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**: 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 permiten una integración perfecta con plugins contables y sistemas financieros externos. Ya sea que estés procesando transferencias simples o transacciones complejas de múltiples partes, las Rutas Contables aseguran que tus datos financieros permanezcan estructurados, validados y confiables a escala, mientras proporciona la base semántica para integraciones avanzadas. ## Trabajando con las Rutas Contables *** Para usar las Rutas Contables, debes completar la configuración inicial seguida de la ejecución continua de transacciones. Aquí está tu 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, habilita las configuraciones de validación a través de la [API de Configuración del Ledger](/es/midaz/ledgers#ledger-settings). Esto controla si las transacciones en ese Ledger deben cumplir con tus rutas configuradas. ```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null} { "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. Puedes actualizarlas en cualquier momento a través de la API. #### 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. **No** se escribe en las operaciones — en su lugar, el motor 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 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. Consulta [Asientos Contables](#4-configurar-asientos-contables-acciones) 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 JSON theme={null} { "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 JSON theme={null} { "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 JSON theme={null} { "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`, mapeando cada etapa del ciclo de vida de la transacción a los códigos contables de partida doble correctos. El modelo completo de tipos de acción, los requisitos de débito/crédito y la matriz de validación se cubren en [Configurar Asientos Contables (Acciones)](#4-configurar-asientos-contables-acciones) a continuación. Una ruta con asientos contables configurados: ```json JSON theme={null} { "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" } } }, "account": { "ruleType": "alias", "validIf": "@current_account" }, "metadata": { "channel": "pix" } } ``` El campo `operationType` 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. #### 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, mapeando cómo diferentes 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 JSON theme={null} { "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** — rúbricas estructuradas que definen cómo se registran los asientos de débito y crédito para cada tipo de evento transaccional (`direct`, `hold`, `commit`, `cancel`, `revert`). Son lo que el motor utiliza para resolver qué cuentas se debitan y se acreditan para cada acción, y determinan las anotaciones `routeCode`/`routeDescription` escritas en cada operación. Si una rúbrica faltante se tolera (tolerante) o se rechaza con `0117 ErrAccountingRouteNotFound` (estricto) está controlado por `accounting.validateRoutes` en la [Configuración del Ledger](/es/midaz/ledgers#ledger-settings). Las acciones de asiento contable, los requisitos de débito/crédito por tipo de operación, los modos de validación tolerante vs. estricto y los ejemplos completos de configuración están documentados en detalle en la página **[Asientos Contables](/es/midaz/accounting-entries)**. Esta sección cubre solo cómo se adjuntan las rúbricas a las Rutas de Operación. A nivel de ruta, los asientos contables se proporcionan a través del bloque `accountingEntries` (consulta la **Opción C** en [Crear Rutas de Operación](#2-crear-rutas-de-operación) arriba), con un asiento por acción y una rúbrica de `debit` y/o `credit` 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 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ó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 | 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`. ### Operaciones Continuas #### 5. Ejecutar Transacciones Validadas Con tu configuración de enrutamiento en su lugar, **ahora puedes enviar transacciones con confianza incluyendo el ID de la Ruta Contable previamente creada en tu solicitud de transacción**. Midaz validará automáticamente la transacción contra tus patrones de enrutamiento definidos, asegurando consistencia e integridad en todas las operaciones financieras. Para los ejemplos de Ruta Contable y Rutas de Operación previamente configurados, el sistema compone la siguiente estructura de validación: ```bash text theme={null} 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 JSON expandable theme={null} { "route": "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", "route": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2" } ] }, "distribute": { "to": [ { "accountAlias": "@external/BRL", "amount": { "asset": "BRL", "value": "10" }, "description": "Fee credit to revenue account", "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 tus 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 `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, poblada junto con `routeCode`. Estos campos proporcionan un enlace directo entre cada operación y su clasificación contable, permitiendo que sistemas posteriores (como [Reporter](/es/reporter/what-is-reporter)) produzcan 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](/es/reference/midaz/create-an-operation-route) — Definir una nueva regla contable para tus operaciones. * [Listar Rutas de Operación](/es/reference/midaz/list-operation-routes) — Ver todas las Rutas de Operación configuradas. * [Recuperar una Ruta de Operación](/es/reference/midaz/retrieve-an-operation-route) — Obtener información detallada sobre una Ruta de Operación específica. * [Actualizar una Ruta de Operación](/es/reference/midaz/update-an-operation-route) — Modificar reglas contables existentes. * [Eliminar una Ruta de Operación](/es/reference/midaz/delete-an-operation-route) — 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](/es/reference/midaz/create-transaction-route) — Definir nueva lógica de enrutamiento para conectar transacciones con operaciones contables. * [Listar Rutas de Transacción](/es/reference/midaz/list-transaction-routes) — Ver todas las Rutas de Transacción configuradas. * [Recuperar una Ruta de Transacción](/es/reference/midaz/retrieve-a-transaction-route) — Obtener detalles de una Ruta de Transacción específica. * [Actualizar una Ruta de Transacción](/es/reference/midaz/update-a-transaction-route) — Modificar criterios de enrutamiento existentes. * [Eliminar una Ruta de Transacción](/es/reference/midaz/delete-a-transaction-route) — Eliminar rutas que ya no sean aplicables.