Asientos Contables

Mapea las acciones de transacción y las direcciones de ruta a clasificaciones contables, y anota cada operación con su código y descripción contables.

Los Asientos Contables (también conocidos como Rúbricas) asignan una acción de transacción y la dirección de una ruta a un code y una description contables. Anotan una operación después de resolver la ruta; las reglas de la Ruta de Operación y los tramos de la transacción determinan las cuentas participantes.

​

Qué son los Asientos Contables

---

Una rúbrica asigna una acción de transacción y la dirección de una ruta a una clasificación contable. En lugar de calcular cada clasificación a mano, registras las rúbricas una sola vez. Midaz luego las resuelve automáticamente a medida que procesa las transacciones.

Cada rúbrica lleva:

• code — un código contable (por ejemplo, 1.1.1.001).
• description — una etiqueta legible para el asiento (ej., Customer checking — outbound).
• Un conjunto de mapeos de acción — un asiento por tipo de acción, cada uno con su propia rúbrica de débito y/o crédito.

Cuando el motor procesa una transacción con la validación de rutas (accounting.validateRoutes) habilitada y una rúbrica correspondiente registrada, resuelve la rúbrica de cada operación. Registra el routeCode y el routeDescription resultantes en la operación. Esto te da una pista de auditoría completa desde la transacción hasta la operación y la rúbrica. Tus equipos pueden rastrear exactamente qué regla contable se aplicó a cada movimiento.

Configura las rúbricas por acción en cada Ruta de Operación. Para las acciones direct y commit, las rutas Source requieren la rúbrica de débito y las rutas Destination requieren la rúbrica de crédito. Las rúbricas dedicadas de block y unblock son opcionales; cuando no existen, Midaz resuelve la rúbrica direct para esas acciones. Las acciones hold y cancel en rutas source requieren ambas rúbricas, y overdraft requiere ambas en cada tipo de ruta compatible. Las rutas Bidirectional siempre requieren ambas.

​

Los 8 tipos de acción

---

Cada acción representa un evento transaccional distinto. Las primeras cinco acciones cubren el ciclo de vida de la transacción. Las últimas tres cubren los movimientos de sobregiro, bloqueo y desbloqueo. Una sola rúbrica puede asignar diferentes clasificaciones de débito y crédito para cada acción. Cada etapa de una operación recibe entonces la anotación contable correcta.

Acción	Identificador	Descripción
Direct	direct	Débito/crédito inmediato, de un solo paso, entre dos cuentas, sin etapas intermedias (ej., una comisión o un ajuste).
Hold	hold	Reserva fondos creando un movimiento pendiente (mueve valor de available a on_hold en la cuenta de origen).
Commit	commit	Confirma un monto previamente retenido, liberando el valor on_hold a la cuenta de destino.
Cancel	cancel	Cancela/revierte una retención, devolviendo el valor on_hold al saldo available en la cuenta de origen.
Revert	revert	Revierte una transacción direct completada creando una contra-transacción que deshace la original.
Overdraft	overdraft	Clasifica los movimientos de sobregiro — la rúbrica de débito marca el uso del sobregiro (el déficit crece) y la rúbrica de crédito marca el pago (el déficit disminuye). Ambas rúbricas son obligatorias cuando se configura este asiento.
Block	block	Clasifica opcionalmente un movimiento de bloqueo de fondos que congela valor en una cuenta (por ejemplo, un asset-freeze).
Unblock	unblock	Clasifica opcionalmente la liberación de fondos previamente bloqueados de vuelta al saldo available.

Overdraft clasifica las operaciones complementarias que el motor genera automáticamente durante el uso y el pago del sobregiro. Para cada tipo de ruta y dirección compatibles, configura ambas rúbricas: debit y credit. Block y unblock pueden usar rúbricas dedicadas para las operaciones que producen los endpoints de bloqueo y desbloqueo; sin ellas, esas acciones usan la rúbrica direct. Cuando lo necesites, registra las rúbricas dedicadas de estas acciones de la misma manera que las demás acciones.

Cada acción puede apuntar a diferentes clasificaciones contables de débito y crédito dentro de la misma rúbrica. Mapea solo las acciones que una ruta usa. Si habilitas la validación estricta (más abajo), cubre cada acción que emitan tus transacciones.

​

Configurar Asientos Contables

---

Registras las rúbricas a través de la API como parte de tus Rutas de Operación. El bloque accountingEntries de una ruta define un asiento por acción. Cada asiento lleva su rúbrica de debit y/o credit:

accountingEntries

{
    "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"
            }
        }
    }
}

Gestionas estos asientos a través de los endpoints de Ruta de Operación — consulta Crear una Ruta de Operación y Actualizar una Ruta de Operación. Para el flujo completo de configuración, consulta Enrutamiento de Transacciones.

​

Modos de validación

---

Midaz reacciona ante una rúbrica faltante según la configuración contable del Ledger. Dos compuertas distintas controlan este comportamiento:

​

Por defecto (tolerante)

Por defecto (accounting.validateRoutes deshabilitado), Midaz no resuelve rúbricas en absoluto: la transacción procede normalmente y los campos routeCode y routeDescription quedan vacíos (nil) en cada operación. No genera ningún error.

​

Estricto (opcional)

Establece accounting.validateRoutes en true en la Configuración del Ledger para aplicar la validación de rutas. En modo estricto, una acción solicitada sin rutas en la caché de rutas de transacción devuelve 0157 ErrNoRoutesForAction. 0117 ErrAccountingRouteNotFound se aplica cuando falta un ID de Ruta de Operación en esa caché.

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

{
  "accounting": {
    "validateRoutes": true
  }
}

En modo estricto, no trates 0117 ErrAccountingRouteNotFound como el error para toda acción no mapeada: se aplica cuando falta un ID de Ruta de Operación en la caché de rutas de transacción. Una acción solicitada sin rutas en esa caché devuelve 0157 ErrNoRoutesForAction.

Usa el modo estricto en ledgers de producción donde cada tipo de transacción necesita una clasificación contable. El valor predeterminado tolerante ayuda mientras configuras las rutas. En producción, puede dejar movimientos sin clasificación de forma silenciosa.

Cuando Midaz encuentra una rúbrica coincidente, anota la operación con dos campos:

• routeCode — el code de la AccountingRubric resuelta para esa acción y dirección.
• routeDescription — la descripción de la rúbrica resuelta, poblada junto con routeCode.