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. Com a validação de rota habilitada, uma transação pode usar a rota apenas para as ações que têm um lançamento. 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"
    },
    "accountingEntries": {
        "direct": {
            "credit": {
                "code": "3.1.001",
                "description": "Fee revenue"
            }
        }
    }
}

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

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

​

3. Construa Rotas Contábeis

• Uma rota nas duas listas retorna 0541.
• Uma rota opcional com uma entrada crossLedger retorna 0256.
• Uma atualização na v2 aplica cada lista como um JSON merge patch: uma lista ausente ou null mantém os vínculos armazenados, e [] os remove.
• A /v1 recusa 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"
    ]
}

​

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 (erro 0163). 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 hold, commit, cancel, revert ou overdraft, também deve definir direct (erro 0164). Ele é 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.
• crossLedger classifica as pernas da Conta Externa que o Midaz adiciona quando uma transação abrange vários Ledgers. Ele exige as duas rubricas e uma rota bidirectional (erro 0162) sem nenhum outro lançamento (erro 0256). Uma Rota Contábil vincula no máximo uma rota desse tipo.
• Qualquer chave fora dessas nove é 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",
    "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"
        }
    ]
}

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

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