Accounting Routes

Las Accounting Routes son el sistema de validación de dos capas de Midaz para las transacciones financieras. Las Accounting Routes definen el patrón completo de la transacción. Las Operation Routes validan cada operación dentro de ese patrón. Juntas, mantienen cada transacción estructuralmente correcta y conforme con tus reglas de negocio.

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

Las Accounting Routes definen la estructura completa de una transacción: la secuencia requerida de operaciones que forma un evento financiero válido.
Las Operation Routes definen las reglas de 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 habilitas la validación de rutas en un Ledger, Midaz valida cada transacción en dos capas. La capa de Accounting Routes verifica que la estructura general coincida con el patrón predefinido. La capa de Operation Routes verifica que cada componente cumpla los requisitos de cuenta y las reglas de negocio. Si alguna parte de la transacción no supera estas verificaciones, Midaz la rechaza antes de registrarla.

Defines los patrones de validación mediante las Operation Routes y las Accounting Routes.

¿Para qué sirven las Accounting Routes?

Las Accounting Routes brindan control estructurado sobre tus operaciones financieras al separar la lógica de la transacción del código de negocio. En lugar de codificar reglas de validación directamente en tu aplicación, configuras patrones reutilizables. Estos patrones hacen que cada movimiento financiero siga los requisitos de tu organización. Estas entidades vinculan las Transacciones y las Operaciones del ledger 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 sin importar dónde se originen.
Flexibilidad: adapta el diseño de tu ledger a tus necesidades de negocio sin cambios de código.
Integridad: la validación automática evita que las transacciones mal formadas afecten tu ledger.
Facilidad de mantenimiento: la configuración centralizada facilita actualizar las reglas financieras a medida que tu negocio evoluciona.
Interoperabilidad: los campos con semántica de negocio permiten integrar plugins contables y sistemas financieros externos.

Trabajar con las Accounting Routes

Para usar las Accounting Routes, completas una configuración única y luego ejecutas transacciones.

Configuración inicial

1. Configura el Ledger para la validación de rutas de transacción

Para activar la validación de rutas de transacción en un Ledger específico, habilita la configuración de validación mediante la API de configuración del Ledger. Esto controla si las transacciones de ese Ledger deben cumplir con tus rutas configuradas.

{
  "accounting": {
    "validateRoutes": true,
    "validateAccountType": true
  }
}

validateRoutes: cuando está habilitado, cada transacción debe hacer referencia a una ruta de transacción válida.
validateAccountType: cuando está habilitado, Midaz rechaza una cuenta cuyo type no sea un Account Type registrado. Esto controla la creación de cuentas, no las transacciones. validateRoutes aplica la regla account_type en una Operation Route, independientemente de este indicador.

Crea Operation Routes

Crea Operation Routes que definan las reglas de validación y el comportamiento de los componentes individuales de la transacción. Campos clave:

title: etiqueta breve que identifica la ruta de operación.
code (en desuso): una referencia externa heredada que se mantiene por compatibilidad con versiones anteriores. El motor no la 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 el contexto de negocio y la categorización personalizada.
operationType: la dirección contable de esta ruta (source, destination o bidirectional).
- source: identifica las cuentas donde se originan los fondos (lado de débito).
- destination: identifica las cuentas que reciben los fondos (lado de crédito).
- bidirectional: se aplica a ambos lados de la transacción, como origen y destino a la vez.
account: reglas de validación opcionales que establecen un tipo de cuenta requerido o una cuenta específica.
- ruleType: el tipo de regla de validación de cuenta (account_type, alias).
- validIf: el valor esperado que debe coincidir para que la validación se apruebe.
accountingEntries: asientos contables opcionales para cada tipo de acción. Con la validación de rutas habilitada, una transacción puede usar la ruta solo para las acciones que tienen un asiento. Consulta Asientos contables más abajo.

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:

 {
    "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 las reglas de cuenta según la configuración de tu ledger:

Apuntar a una cuenta específica

Valida contra una cuenta específica usando su alias.

{
    "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"
    },
    "accountingEntries": {
        "direct": {
            "credit": {
                "code": "3.1.001",
                "description": "Fee revenue"
            }
        }
    }
}

Apuntar a un tipo de cuenta

Valida contra tipos de cuenta específicos.

{
    "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"]
    },
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "User wallet fee"
            }
        }
    }
}

Opción C: con asientos contables Adjunta asientos contables directamente a la ruta de operación mediante el campo accountingEntries. Este campo asigna cada etapa del ciclo de vida de la transacción a los códigos contables de partida doble correctos. Consulta Configura los asientos contables (acciones) más abajo para conocer 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:

{
    "title": "Pix Cash-out - Current Account",
    "description": "Operation route for sending Pix payments from 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 envían y reciben a la vez, o para operaciones que quizás necesites revertir.

3. Crea las Accounting Routes

Completa tu configuración combinando Operation Routes en Accounting Routes (el recurso transactionRoute en la API). Estas definen tus patrones completos de transacción. Cada patrón describe cómo las operaciones trabajan juntas para formar eventos financieros balanceados que coinciden con tus procesos de negocio. Una Accounting Route necesita al menos una Operation Route de origen y una de destino (errores 0153 y 0154). Una ruta bidireccional cuenta como ambas. En /v2, una Accounting Route también puede vincular Operation Routes opcionales en optionalOperationRoutes. Una transacción puede dejar sin usar una ruta opcional, por ejemplo una ruta de comisión cuando no aplica ninguna comisión. Midaz valida un tramo que la usa como cualquier otro tramo. Solo las rutas en operationRoutes cuentan para la regla de origen y destino.

Una ruta en ambas listas devuelve 0541.
Una ruta opcional con una entrada crossLedger devuelve 0256.
Una actualización en v2 aplica cada lista como un JSON merge patch: una lista ausente o null conserva los vínculos guardados, y [] los quita.
/v1 rechaza optionalOperationRoutes.

{
    "title": "Fee Transaction",
    "description": "Complete transaction for collecting fees from user cashout operations",
    "metadata": {
        "transactionType": "cashout_fee",
        "businessFlow": "withdrawal_processing"
    },
    "operationRoutes": [
        "0197e6aa-1695-734a-a8c3-8c79e0ad32c2",
        "0197e675-37cc-71d7-96c2-f58000f33aa0"
    ]
}

Configura los asientos contables (acciones)

Cada Operation Route 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. Cuatro claves complementarias (overdraft, block, unblock y crossLedger) describen el impacto contable, pero no son acciones válidas de ruta de transacción. Los asientos determinan las anotaciones routeCode y routeDescription de cada operación. La configuración accounting.validateRoutes en la configuración del Ledger controla este comportamiento. Cuando la habilitas, Midaz rechaza una transacción cuyos tramos no coinciden con los asientos de su Accounting Route. Cuando la deshabilitas, Midaz no resuelve ninguna rúbrica, y routeCode queda vacío.

La página 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 Operation Routes.

En el nivel de la ruta, proporcionas los asientos contables mediante el bloque accountingEntries. Consulta la Opción C en Crea Operation Routes más arriba. Cada acción toma una entrada 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 de 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 Operation Route. Si las reglas no coinciden, Midaz rechaza la solicitud antes de persistir la ruta. Una combinación inválida devuelve el error 0166 (campo requerido) o 0162/0165 (escenario no permitido para esa dirección). source

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

destination

Acción	Débito	Crédito	Notas
`direct`	Opcional	Obligatorio	Transacción estándar de un paso en el destino
`hold`	—	—	No permitido (error `0162`)
`commit`	Opcional	Obligatorio	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`	Obligatorio	Obligatorio	Ambos lados de la partida doble
`hold`	Obligatorio	Obligatorio	Ambos lados de la partida doble
`commit`	Obligatorio	Obligatorio	Ambos lados de la partida doble
`cancel`	Obligatorio	Obligatorio	Ambos lados de la partida doble
`revert`	Obligatorio	Obligatorio	Única dirección que admite revert

Si una entrada no tiene ni debit ni credit, Midaz la rechaza, sin importar el tipo de operación o la acción.

Reglas adicionales:

Atomicidad del grupo de reserva: en las rutas source y bidirectional, si defines hold, también debes definir commit y cancel (y viceversa). En esas rutas, estas tres acciones forman un grupo atómico. No puedes configurar una sin las otras (error 0163). En las rutas destination, hold y cancel no están permitidas (error 0162), así que commit se puede configurar sin ellas. Aun así requiere direct, según la regla siguiente.
Direct es obligatoria: si defines hold, commit, cancel, revert u overdraft, también debes definir direct (error 0164). Es la entrada base de la ruta de operación.
overdraft requiere ambas rúbricas en todo operationType, incluidos source y destination.
block y unblock reflejan direct: débito en una ruta source, crédito en una ruta destination, ambas en bidirectional.
crossLedger clasifica los tramos de la Cuenta externa que Midaz agrega cuando una transacción abarca varios Ledgers. Requiere ambas rúbricas y una ruta bidirectional (error 0162) sin ningún otro asiento (error 0256). Una Accounting Route vincula como máximo una ruta de ese tipo.
Cualquier clave fuera de estas nueve se rechaza con el error 0053 (Unexpected Fields).

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

Operaciones continuas

5. Ejecuta transacciones validadas

Con tu configuración de enrutamiento lista, ya puedes enviar transacciones. En la solicitud de transacción, define routeId con el ID de la Accounting Route que creaste, y operationRouteId en cada tramo. Midaz valida entonces la transacción contra tus patrones de enrutamiento. Para la Accounting Route y las Operation Routes configuradas arriba, Midaz compone la siguiente estructura de validación:

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

Una solicitud correspondiente para crear una transacción directa:

{
    "routeId": "5656daa5-5b2a-4637-955f-e43bafceaf5d",
    "description": "Cashout fee collection transaction",
    "asset": "BRL",
    "amount": "10",
    "debits": [
        {
            "alias": "@user_wallet_123",
            "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
            "amount": "10",
            "description": "Fee debit from user wallet",
            "operationRouteId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
        }
    ],
    "credits": [
        {
            "alias": "@external/BRL",
            "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
            "amount": "10",
            "description": "Fee credit to revenue account",
            "operationRouteId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
        }
    ]
}

Cuando envías esta transacción, Midaz verifica que la cuenta @user_wallet_123 tenga uno de los tipos de cuenta de la regla account_type. También verifica que la cuenta acreditada sea @external/BRL.

Campos de ruta en las operaciones

Cuando habilitas la validación de rutas y configuras 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 la 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. Sistemas posteriores como Reporter pueden entonces producir informes financieros precisos sin búsquedas adicionales.

Gestionar las Operation Routes y las Accounting Routes

Para configurar tus Operation Routes, usa los siguientes endpoints:

Crear una Operation Route: define una nueva regla contable para tus operaciones.
Listar las Operation Routes: consulta todas las Operation Routes configuradas.
Consultar una Operation Route: obtén información detallada de una Operation Route específica.
Actualizar una Operation Route: modifica reglas contables existentes.
Eliminar una Operation Route: elimina una Operation Route obsoleta o sin uso.

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

Crear una Transaction Route: define una nueva lógica de enrutamiento para conectar transacciones con operaciones contables.
Listar las Transaction Routes: consulta todas las Transaction Routes configuradas.
Consultar una Transaction Route: obtén los detalles de una Transaction Route específica.
Actualizar una Transaction Route: modifica los criterios de enrutamiento existentes.
Eliminar una Transaction Route: elimina rutas que ya no sean aplicables.

Las rutas pertenecen a la Organización. Una transacción en cualquier Ledger de la Organización puede usar una ruta, sin importar en qué Ledger la creaste. Para crear una ruta sin Ledger, usa Crear una Operation Route de la organización y Crear una Transaction Route de la organización.

Midaz Core

CRM

Fees

Accounting Routes

¿Para qué sirven las Accounting Routes?

Trabajar con las Accounting Routes

Configuración inicial

1. Configura el Ledger para la validación de rutas de transacción

Crea Operation Routes

3. Crea las Accounting Routes

Configura los asientos contables (acciones)

Matriz de validación de asientos contables

Operaciones continuas

5. Ejecuta transacciones validadas

Campos de ruta en las operaciones

Gestionar las Operation Routes y las Accounting Routes

​¿Para qué sirven las Accounting Routes?

​Trabajar con las Accounting Routes

​Configuración inicial

​1. Configura el Ledger para la validación de rutas de transacción

​ Crea Operation Routes

​3. Crea las Accounting Routes

​ Configura los asientos contables (acciones)

Matriz de validación de asientos contables

​Operaciones continuas

​5. Ejecuta transacciones validadas

Campos de ruta en las operaciones

​Gestionar las Operation Routes y las Accounting Routes

¿Para qué sirven las Accounting Routes?

Trabajar con las Accounting Routes

Configuración inicial

1. Configura el Ledger para la validación de rutas de transacción

Crea Operation Routes

3. Crea las Accounting Routes

Configura los asientos contables (acciones)

Operaciones continuas

5. Ejecuta transacciones validadas

Gestionar las Operation Routes y las Accounting Routes