Rutas Contables

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

​

¿Para qué sirven las Rutas Contables?

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

​

Trabajando con las Rutas Contables

​

Configuración Inicial

​

1. Configurar Ledger para validación de ruta de transacción

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

​

2. Crear Rutas de Operación

• 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 a continuación.

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

• Apuntar a Cuenta Específica

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

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

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

​

3. Construir Rutas Contables

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

• 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

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

​

Operaciones Continuas

​

5. Ejecutar Transacciones Validadas

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

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

Campos de ruta en operaciones

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

​

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

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

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