Rotas Contábeis

• Rotas Contábeis definem a estrutura completa de uma transação — a sequência necessária de operações e como elas se encaixam para formar um evento financeiro válido.
• Operation Routes definem as regras para cada operação individual (ou “perna”) dessa transação, incluindo o tipo de conta esperado ou conta específica, a anotação contábil e se é um débito ou crédito.

​

Para que servem as Rotas Contábeis?

• Consistência: Todas as transações seguem estruturas predefinidas, independentemente de onde se originam.
• Flexibilidade: Adapte o design do seu ledger para atender às necessidades do seu negócio sem alterações de código.
• Integridade: A validação automática impede que transações malformadas afetem seu ledger.
• Manutenibilidade: A configuração centralizada facilita a atualização das regras financeiras à medida que seu negócio evolui.
• Interoperabilidade: Campos com semântica de negócio permitem integração transparente com plugins contábeis e sistemas financeiros externos.

​

Trabalhando com Rotas Contábeis

​

Configuração Inicial

​

1. Configurar o Ledger para validação de transaction route

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

• validateRoutes: Quando habilitada, cada transação deve referenciar uma rota de transação válida.
• validateAccountType: Quando habilitada, os tipos de conta são validados contra as regras das rotas de operação.

​

2. Criar Operation Routes

• title: Rótulo breve que identifica a operation route.
• code (obsoleto): uma referência externa legada mantida por retrocompatibilidade. Não é escrito nas operações — em vez disso, o motor registra o code da rubrica resolvida (de accountingEntries) como routeCode em cada operação.
• description: Explicação detalhada opcional.
• metadata: Pares chave-valor para contexto de negócio e categorização personalizada.
• operationType: A direção contábil desta rota — source, destination ou bidirectional.
  • source — Identifica contas de onde os fundos se originam (lado do débito).
  • destination — Identifica contas para onde os fundos são enviados (lado do crédito).
  • bidirectional — Aplica-se a ambos os lados da transação, atuando como origem e destino.
• account: Regras de validação opcionais especificando o tipo de conta necessário ou conta específica.
  • ruleType: Tipo de regra de validação de conta (account_type, alias).
  • validIf: O valor esperado que deve corresponder para que a validação seja aprovada.
• accountingEntries: Lançamentos Contábeis opcionais para cada tipo de ação. Veja Lançamentos Contábeis abaixo.

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

• Conta 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"
    }
}

• Tipo de Conta

{
    "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 Rotas Contábeis

{
    "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 Lançamentos Contábeis (Actions)

• Rotas de origem (source) exigem a rubrica de débito.
• Rotas de destino (destination) exigem a rubrica de crédito.
• Rotas bidirecionais (bidirectional) exigem ambas as rubricas de débito e crédito.

Matriz de validação de lançamentos contábeis

• Atomicidade do grupo de reserva: Se você define hold, também deve definir commit e cancel (e vice-versa). Essas três ações formam um grupo atômico — você não pode configurar uma sem as outras.
• direct é obrigatório: Se qualquer outra ação (hold, commit, cancel, revert) for definida, direct também deve estar presente. Serve como o lançamento base para a operation route.

​

Operações Contínuas

​

5. Executar Transações 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 rota nas operações

• routeCode — O code da AccountingRubric resolvida para a ação e a direção daquela operação.
• routeDescription — A descrição da rubrica contábil resolvida, preenchida junto com o routeCode.

​

Gerenciando Operation Routes e Rotas Contábeis

• Criar uma Operation Route — Defina uma nova regra contábil para suas operações.
• Listar Operation Routes — Visualize todas as Operation Routes configuradas.
• Recuperar uma Operation Route — Obtenha informações detalhadas sobre uma Operation Route específica.
• Atualizar uma Operation Route — Modifique regras contábeis existentes.
• Excluir uma Operation Route — Remova uma Operation Route desatualizada ou não utilizada.

• Criar uma Transaction Route — Defina nova lógica de roteamento para conectar transações a operações contábeis.
• Listar Transaction Routes — Visualize todas as Transaction Routes configuradas.
• Recuperar uma Transaction Route — Obtenha detalhes de uma Transaction Route específica.
• Atualizar uma Transaction Route — Modifique critérios de roteamento existentes.
• Excluir uma Transaction Route — Remova rotas que não são mais aplicáveis.