Rotas Contábeis

• Rotas Contábeis definem a estrutura completa de uma transação: a sequência exigida de operações que forma um evento financeiro válido.
• Rotas de Operação definem as regras para cada operação (ou “perna”) dessa transação. Cada regra define o tipo de conta esperado ou a conta específica, a anotação contábil e o lado de 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 corresponder às suas necessidades de negócio sem mudanças 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 conforme seu negócio evolui.
• Interoperabilidade: Campos com semântica de negócio permitem integrar plugins contábeis e sistemas financeiros externos.

​

Trabalhando com Rotas Contábeis

​

Configuração inicial

​

1. Configure o Ledger para validação de rota de transação

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

• validateRoutes: Quando habilitado, toda transação deve referenciar uma rota de transação válida.
• validateAccountType: Quando habilitado, o Midaz rejeita uma conta cujo type não seja um Tipo de Conta registrado. Isso controla a criação de conta, não as transações. validateRoutes aplica a regra account_type em uma Rota de Operação, independentemente dessa flag.

​

2. Crie Rotas de Operação

• title: Rótulo breve que identifica a rota de operação.
• code (obsoleto): uma referência externa legada mantida por retrocompatibilidade. O engine não a grava nas operações. Em vez disso, ele 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 dessa rota (source, destination ou bidirectional).
  • source: identifica contas onde os fundos se originam (lado do débito).
  • destination: identifica contas que recebem fundos (lado do crédito).
  • bidirectional: aplica-se a ambos os lados da transação, como origem e destino.
• account: Regras de validação opcionais que definem um tipo de conta exigido ou uma conta específica.
  • ruleType: Tipo de regra de validação de conta (account_type, alias).
  • validIf: O valor esperado que deve corresponder para a validação passar.
• 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"
}

• Direcionar para uma 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"
    }
}

• Direcionar para um 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"
            }
        },
        "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"
    }
}

​

3. Construa 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. Configure Lançamentos Contábeis (Ações)

• Rotas source exigem a rubrica debit.
• Rotas destination exigem a rubrica credit.
• Rotas bidirectional exigem ambas as rubricas debit e credit.

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

• Atomicidade do grupo de reserva: Em rotas source e bidirectional, se você definir hold, também deve definir commit e cancel (e vice-versa). Essas três ações formam um grupo atômico ali. Você não pode configurar uma sem as outras. Em rotas destination, hold e cancel não são permitidos (erro 0162), então commit pode ser configurado sem eles. Ainda assim, ele exige direct conforme a regra abaixo.
• Direct é obrigatório: Se você definir qualquer outra ação (hold, commit, cancel, revert, overdraft, block, unblock), também deve definir direct. Ele serve como o lançamento base da rota de operação.
• overdraft exige ambas as rubricas em todo operationType, incluindo source e destination.
• block e unblock espelham direct: débito em uma rota source, crédito em uma rota destination, ambos em bidirectional.
• Qualquer chave fora dessas oito é rejeitada com o erro 0053 (Unexpected Fields).

​

Operações contínuas

​

5. Execute 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

{
    "routeId": "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",
                    "routeId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
                }
            ]
        },
        "distribute": {
            "to": [
                {
                    "accountAlias": "@external/BRL",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Fee credit to revenue account",
                    "routeId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
                }
            ]
        }
    }
}

Campos de rota nas operações

• routeCode: o code do AccountingRubric resolvido para a ação e a direção dessa operação.
• routeDescription: a descrição da rubrica contábil resolvida. O Midaz a preenche junto com routeCode.

​

Gerenciando Rotas de Operação e Rotas Contábeis

• Criar uma Rota de Operação: defina uma nova regra contábil para suas operações.
• Listar Rotas de Operação: veja todas as Rotas de Operação configuradas.
• Consultar uma Rota de Operação: obtenha informações detalhadas sobre uma Rota de Operação específica.
• Atualizar uma Rota de Operação: modifique regras contábeis existentes.
• Excluir uma Rota de Operação: remova uma Rota de Operação desatualizada ou não utilizada.

• Criar uma Rota de Transação: defina uma nova lógica de roteamento para conectar transações a operações contábeis.
• Listar Rotas de Transação: veja todas as Rotas de Transação configuradas.
• Consultar uma Rota de Transação: obtenha detalhes de uma Rota de Transação específica.
• Atualizar uma Rota de Transação: modifique critérios de roteamento existentes.
• Excluir uma Rota de Transação: remova rotas que não são mais aplicáveis.