Rotas Contábeis

As Rotas Contábeis são o sistema de validação em duas camadas do Midaz para transações financeiras. As Rotas Contábeis definem o padrão completo da transação. As Operation Routes validam cada operação dentro desse padrão. Juntas, mantêm cada transação estruturalmente correta e em conformidade com suas regras de negócio.

Nomenclatura: O Lerian Console e a documentação do produto chamam este conceito de Rotas Contábeis (Accounting Routes). Na API e nos SDKs, o recurso transactionRoute representa a rota em nível de transação, com os endpoints transaction-route. Os dois termos se referem à mesma coisa.

Rotas Contábeis definem a estrutura completa de uma transação: a sequência necessária de operações que forma um evento financeiro válido.
Operation Routes 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.

Quando você submete uma transação, o Midaz a valida em duas camadas. A camada de Rotas Contábeis verifica se a estrutura geral corresponde ao padrão predefinido. A camada de Operation Routes verifica se cada componente atende aos requisitos de conta e às regras de negócio. Se qualquer parte da transação falhar nessas verificações, o Midaz a rejeita antes de registrar a transação. Isso protege a integridade do seu ledger e não limita sua flexibilidade.

Você define os padrões de validação por meio de Operation Routes e Rotas Contábeis. O Midaz verifica se suas transações estão em conformidade com essas regras antes de processá-las.

Para que servem as Rotas Contábeis?

As Rotas Contábeis oferecem controle estruturado sobre suas operações financeiras ao separar a lógica de transação do código de negócio. Em vez de codificar regras de validação na sua aplicação, você configura padrões reutilizáveis. Esses padrões fazem cada movimentação financeira seguir os requisitos da sua organização. Essas entidades vinculam Transactions e Operations do ledger do Midaz a abstrações de nível superior. Essas abstrações ajudam você a integrar plugins especializados e sistemas externos, especialmente para contabilidade e tesouraria. As anotações e classificações estruturadas criam um vocabulário padronizado que outros componentes podem entender e usar. Essa abordagem oferece:

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 que você integre plugins contábeis e sistemas financeiros externos.

As Rotas Contábeis mantêm seus dados financeiros estruturados e validados para transferências simples e transações complexas com múltiplas partes. Elas também fornecem a base semântica para integrações avançadas.

Trabalhando com Rotas Contábeis

Para usar as Rotas Contábeis, você conclui uma configuração inicial única e depois executa transações. Os passos abaixo mostram o processo completo.

Configuração Inicial

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

Para ativar a validação de transaction route em um Ledger específico, habilite as configurações de validação através da API de Configurações do Ledger. Isso controla se as transações nesse Ledger devem estar em conformidade com suas rotas configuradas.

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

validateRoutes: Quando habilitada, cada transação deve referenciar uma rota de transação válida.
validateAccountType: Quando habilitada, o Midaz rejeita uma conta cujo type não seja um Tipo de conta registrado. Isso controla a criação de contas, não as transações — a regra account_type de uma Operation Route é aplicada pelo validateRoutes, independentemente dessa flag.

As alterações nas configurações não exigem redeploy: você pode atualizá-las a qualquer momento pela API. A escrita invalida o cache de configurações, mas as leituras ficam em cache por 5 minutos, então conte com esse tempo para que todas as réplicas observem a mudança.

2. Criar Operation Routes

Crie Operation Routes que definem regras de validação e comportamento para componentes individuais de transação. Campos principais:

title: Rótulo breve que identifica a operation route.
code (obsoleto): uma referência externa legada mantida por retrocompatibilidade. O motor não o escreve nas operações. Em vez disso, 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 que recebem os 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 necessário 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 que a validação seja aprovada.
accountingEntries: Lançamentos Contábeis opcionais para cada tipo de ação. Veja Lançamentos Contábeis abaixo.

Configure regras de conta de acordo com suas necessidades: Opção A: Sem Regra de Conta Se você não precisa de validação de conta para a operation route, omita o objeto account:

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

Opção B: Regra de Validação de Conta Se você precisa de validação de conta para a operação, configure as regras de conta com base na configuração do seu ledger:

Conta Específica

Valide contra uma conta específica usando seu alias.

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

Valide contra tipos de conta específicos.

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

Opção C: Com lançamentos contábeis Anexe lançamentos contábeis diretamente à operation route através do campo accountingEntries. Esse campo mapeia cada etapa do ciclo de vida da transação para os códigos contábeis de partidas dobradas corretos. Veja Configurar Lançamentos Contábeis (Actions) abaixo para o modelo completo de tipos de ação, os requisitos de débito/crédito e a matriz de validação. Uma rota com lançamentos contábeis configurados:

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

O campo operationType também suporta bidirectional. Uma rota bidirecional opera em ambas as direções. Use-a para rotas que tanto enviam quanto recebem, ou para operações que você possa precisar reverter.

3. Construir Rotas Contábeis

Complete sua configuração combinando Operation Routes em Rotas Contábeis (o recurso transactionRoute na API). Elas definem seus padrões completos de transação. Cada padrão mapeia como as operações funcionam juntas para formar eventos financeiros balanceados que correspondem aos seus processos de negócio.

O campo operationRoutes utiliza um array de objetos com operationRouteId em vez de um array simples de strings UUID.

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

Cada Operation Route pode incluir Lançamentos Contábeis. Essas rubricas estruturadas definem como o Midaz registra os lançamentos de débito e crédito para cada evento transacional: direct, hold, commit, cancel e revert, além de três chaves complementares — overdraft, block e unblock — que descrevem impacto contábil, mas não são ações válidas de rota de transação. O motor as usa para resolver quais contas ele debita e credita em cada ação. Elas também determinam as anotações routeCode e routeDescription em cada operation. A configuração accounting.validateRoutes nas Configurações do Ledger controla esse comportamento. Quando você a habilita, o Midaz rejeita uma operation route ausente ou que não corresponde, e retorna 0117 ErrAccountingRouteNotFound. Quando você a desabilita, a resolução de rotas é de melhor esforço. Uma rubrica ausente deixa routeCode vazio e não interrompe a transação.

A página de Lançamentos Contábeis documenta o modelo completo em detalhes. Isso inclui as ações de lançamento contábil, os requisitos de débito/crédito por tipo de operação, os modos de validação graceful e estrito, e exemplos de configuração. Esta seção cobre apenas como as rubricas se vinculam às Operation Routes.

No nível da rota, você fornece os lançamentos contábeis por meio do bloco accountingEntries. Veja a Opção C em Criar Operation Routes acima. Cada ação recebe um lançamento com uma rubrica de debit, uma rubrica de credit, ou ambas, dependendo do operationType da rota:

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

Nem toda combinação de operationType e ação é válida. O Midaz aplica uma matriz de validação rigorosa quando você cria ou atualiza uma Operation Route. Se as regras não corresponderem, o Midaz rejeita a requisição antes de persistir a rota. Essa matriz é fundamental para integradores. Uma combinação inválida retorna o erro 0166 (campo obrigatório) ou 0162/0165 (cenário não permitido para a direção). source

Ação	Débito	Crédito	Notas
`direct`	Obrigatório	Opcional	Transação padrão de etapa única na origem
`hold`	Obrigatório	Obrigatório	Reserva fundos — move available → on_hold
`commit`	Obrigatório	Opcional	Finaliza uma transação em duas fases
`cancel`	Obrigatório	Obrigatório	Libera os fundos reservados — move on_hold → available
`revert`	—	—	Não permitido (erro `0165`). Use `bidirectional` no lugar

destination

Ação	Débito	Crédito	Notas
`direct`	Opcional	Obrigatório	Transação padrão de etapa única no destino
`hold`	—	—	Não permitido (erro `0162`)
`commit`	Opcional	Obrigatório	Finaliza uma transação em duas fases
`cancel`	—	—	Não permitido (erro `0162`)
`revert`	—	—	Não permitido (erro `0165`). Use `bidirectional` no lugar

bidirectional

Ação	Débito	Crédito	Notas
`direct`	Obrigatório	Obrigatório	Ambos os lados da partida dobrada
`hold`	Obrigatório	Obrigatório	Ambos os lados da partida dobrada
`commit`	Obrigatório	Obrigatório	Ambos os lados da partida dobrada
`cancel`	Obrigatório	Obrigatório	Ambos os lados da partida dobrada
`revert`	Obrigatório	Obrigatório	Única direção que suporta revert

Se um lançamento não tiver nem debit nem credit, o Midaz o rejeita, independentemente do tipo de operação ou ação.

Regras adicionais:

Atomicidade do grupo de reserva: Em rotas source e bidirectional, se você define 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 você pode configurar commit sem eles; direct continua obrigatório conforme a regra abaixo.
direct é obrigatório: Se você define qualquer outra ação ou chave complementar (hold, commit, cancel, revert, overdraft, block, unblock), também deve definir direct. Serve como o lançamento base para a operation route.
overdraft exige as duas rubricas em todo operationType, inclusive 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).

Ao projetar suas operation routes, comece com a ação direct. Adicione hold/commit/cancel apenas se precisar de suporte a transações em duas fases. Adicione revert apenas em rotas bidirectional.

Operações Contínuas

5. Executar Transações Validadas

Com sua configuração de roteamento pronta, agora você pode submeter transações. Na requisição de transação, inclua o ID da Rota Contábil que você criou. O Midaz então valida a transação contra seus padrões de roteamento. Isso mantém todas as operações financeiras consistentes e corretas. Para a Rota Contábil e as Operation Routes configuradas acima, o Midaz compõe a seguinte estrutura de validação:

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

Para propriedades de rota em transações do Midaz, um payload de requisição apropriado:

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

Quando você submete esta transação, o Midaz valida duas coisas. A conta @user/wallet_123 deve corresponder à regra de tipo de conta user_wallet. A conta @external/BRL deve corresponder ao alias exato. Ambas as verificações confirmam que a transação segue seus padrões de roteamento.

Campos de rota nas operações

Quando você habilita a validação de rotas e configura os lançamentos contábeis, toda operação processada inclui dois campos adicionais. O Midaz preenche esses campos a partir da rubrica correspondente:

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. O Midaz a preenche junto com o routeCode.

Esses campos vinculam cada operação à sua classificação contábil. Sistemas downstream como o Reporter podem então produzir relatórios financeiros precisos sem consultas adicionais.

Gerenciando Operation Routes e Rotas Contábeis

Para configurar suas Operation Routes, use os seguintes endpoints:

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.

Para configurar suas Transaction Routes, use os seguintes endpoints:

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.

Midaz Core

CRM

Fees

Rotas Contábeis

Para que servem as Rotas Contábeis?

Trabalhando com Rotas Contábeis

Configuração Inicial

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

2. Criar Operation Routes

3. Construir Rotas Contábeis

4. Configurar Lançamentos Contábeis (Actions)

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

Operações Contínuas

5. Executar Transações Validadas

Campos de rota nas operações

Gerenciando Operation Routes e Rotas Contábeis

​Para que servem as Rotas Contábeis?

​Trabalhando com Rotas Contábeis

​Configuração Inicial

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

​2. Criar Operation Routes

​3. Construir Rotas Contábeis

​4. Configurar Lançamentos Contábeis (Actions)

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

​Operações Contínuas

​5. Executar Transações Validadas

Campos de rota nas operações

​Gerenciando Operation Routes e Rotas Contábeis

Para que servem as Rotas Contábeis?

Trabalhando com Rotas Contábeis

Configuração Inicial

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

2. Criar Operation Routes

3. Construir Rotas Contábeis

4. Configurar Lançamentos Contábeis (Actions)

Operações Contínuas

5. Executar Transações Validadas

Gerenciando Operation Routes e Rotas Contábeis