> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Rotas Contábeis > Valide toda Transação com Rotas Contábeis e Rotas de Operação. Aplique estrutura e regras de negócio antes de registrar qualquer movimento. Rotas Contábeis são o sistema de validação em duas camadas do Midaz para transações financeiras. **Rotas Contábeis** definem o padrão completo da transação. **Rotas de Operação** validam cada operação dentro desse padrão. Juntas, elas mantêm toda transação estruturalmente correta e em conformidade com suas regras de negócio. **Nomenclatura:** O Lerian Console e a documentação do produto chamam esse conceito de **Rotas Contábeis**. Na API e nos SDKs, o recurso `transactionRoute` representa a rota no nível da transação, com endpoints `transaction-route`. Os dois termos se referem à mesma coisa. * **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. Quando você envia 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 Rotas de Operação 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. Você define os padrões de validação por meio de Rotas de Operação e Rotas Contábeis. ## 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 fixar regras de validação no código da sua aplicação, você configura padrões reutilizáveis. Esses padrões fazem cada movimento financeiro seguir os requisitos da sua organização. Essas entidades vinculam Transações e Operações do ledger do Midaz a abstrações de nível mais alto. 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 entrega: * **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

*** Para usar Rotas Contábeis, você completa uma configuração única e depois executa transações. ### Configuração inicial #### 1. Configure o Ledger para validação de rota de transação Para ativar a validação de rota de transação para um Ledger específico, habilite as configurações de validação por meio da [API de Configurações do Ledger](/pt/products/midaz/ledgers#ledger-settings). Isso controla se as transações nesse Ledger devem cumprir as rotas que você configurou. ```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null} { "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. Mudanças de configuração não precisam de reimplantação: você as atualiza a qualquer momento pela API. A escrita invalida o cache de configurações, mas as leituras ficam em cache por **5 minutos**. Cada réplica pode levar até esse tempo para ver uma mudança.

2. Crie Rotas de Operação

Crie Rotas de Operação que definam regras de validação e comportamento para componentes individuais da transação. **Campos principais:** * **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](#4-configure-accounting-entries-actions) abaixo. Configure as regras de conta de acordo com suas necessidades: **Opção A: Sem regra de conta** Se você não precisar de validação de conta para a rota de operação, omita o objeto account: ```json JSON theme={null} { "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ê precisar de validação de conta para a operação, configure as regras de conta de acordo com a configuração do seu ledger: * **Direcionar para uma conta específica** Valide contra uma conta específica usando o alias dela. ```json JSON theme={null} { "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** Valide contra tipos de conta específicos. ```json JSON theme={null} { "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 à rota de operação por meio do campo `accountingEntries`. Esse campo mapeia cada estágio do ciclo de vida da transação para os códigos contábeis corretos de partidas dobradas. Veja [Configure Lançamentos Contábeis (Ações)](#4-configure-accounting-entries-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: ```json JSON theme={null} { "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 aceita `bidirectional`. Uma rota bidirecional opera em ambas as direções. Use-a para rotas que enviam e recebem, ou para operações que você talvez precise reverter. #### 3. Construa Rotas Contábeis Complete sua configuração combinando Rotas de Operação 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 trabalham juntas para formar eventos financeiros equilibrados que correspondem aos seus processos de negócio. O campo `operationRoutes` usa um array de objetos com `operationRouteId`, em vez de um array simples de strings UUID. ```json JSON theme={null} { "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)

Cada Rota de Operação 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`. Três chaves suplementares (`overdraft`, `block` e `unblock`) descrevem impacto contábil, mas **não** são ações válidas de rota de transação. O engine as usa para resolver quais contas debita e credita para cada ação. Elas também determinam as anotações `routeCode` e `routeDescription` em cada operação. A configuração `accounting.validateRoutes` nas [Configurações do Ledger](/pt/products/midaz/ledgers#ledger-settings) controla esse comportamento. Quando você a habilita, o Midaz rejeita uma rota de operação ausente ou que não corresponda, e retorna `0117 ErrAccountingRouteNotFound`. Quando você a desabilita, a resolução de rota é best-effort. Uma rubrica ausente deixa `routeCode` vazio e não interrompe a transação. A página **[Lançamentos Contábeis](/pt/products/midaz/accounting-entries)** 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 strict, e exemplos de configuração. Esta seção cobre apenas como as rubricas se anexam às Rotas de Operação. No nível da rota, você fornece lançamentos contábeis por meio do bloco `accountingEntries`. Veja a **Opção C** em [Crie Rotas de Operação](#2-create-operation-routes) acima. Cada ação recebe um lançamento com uma rubrica `debit`, uma rubrica `credit`, ou ambas, dependendo do `operationType` da rota: * 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 Nem toda combinação de `operationType` e ação é válida. O Midaz aplica uma matriz de validação estrita quando você cria ou atualiza uma Rota de Operação. Se as regras não corresponderem, o Midaz rejeita a requisição antes de persistir a rota. 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 uma etapa 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 fundos reservados — move on\_hold → available | | `revert` | — | — | Não permitido (erro `0165`). Use `bidirectional` em vez disso | **destination** | Ação | Débito | Crédito | Notas | | :------- | :------- | :---------- | :------------------------------------------------------------ | | `direct` | Opcional | Obrigatório | Transação padrão de uma etapa 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` em vez disso | **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 aceita revert | Se um lançamento não tiver nem `debit` nem `credit`, o Midaz o rejeita, independentemente do tipo de operação ou da ação. **Regras adicionais:** * **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). Ao desenhar suas rotas de operação, comece com a ação `direct`. Adicione `hold`/`commit`/`cancel` apenas se você precisar de suporte a transação em duas fases. Adicione `revert` apenas em rotas `bidirectional`. ### Operações contínuas #### 5. Execute Transações Validadas Com sua configuração de roteamento pronta, agora você pode enviar 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. Para a Rota Contábil e as Rotas de Operação configuradas acima, o Midaz compõe a seguinte estrutura de validação: ```bash text theme={null} 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: ```json JSON expandable theme={null} { "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ê envia essa 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 exatamente ao alias. 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 rota e configura lançamentos contábeis, toda operação processada inclui dois campos extras. O Midaz preenche esses campos a partir da rubrica correspondente: * **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`. Esses campos vinculam cada operação à sua classificação contábil. Sistemas downstream como o [Reporter](/pt/products/reporter/what-is-reporter) podem então produzir relatórios financeiros precisos sem consultas extras. ## Gerenciando Rotas de Operação e Rotas Contábeis *** Para **configurar suas Rotas de Operação**, use os seguintes endpoints: * [Criar uma Rota de Operação](/pt/reference/products/midaz/v2/create-operation-route): defina uma nova regra contábil para suas operações. * [Listar Rotas de Operação](/pt/reference/products/midaz/v2/list-operation-routes): veja todas as Rotas de Operação configuradas. * [Consultar uma Rota de Operação](/pt/reference/products/midaz/v2/get-operation-route-by-id): obtenha informações detalhadas sobre uma Rota de Operação específica. * [Atualizar uma Rota de Operação](/pt/reference/products/midaz/v2/update-operation-route): modifique regras contábeis existentes. * [Excluir uma Rota de Operação](/pt/reference/products/midaz/v2/delete-operation-route): remova uma Rota de Operação desatualizada ou não utilizada. Para **configurar suas Rotas Contábeis** (o recurso `transactionRoute` na API), use os seguintes endpoints: * [Criar uma Rota de Transação](/pt/reference/products/midaz/v2/create-transaction-route): defina uma nova lógica de roteamento para conectar transações a operações contábeis. * [Listar Rotas de Transação](/pt/reference/products/midaz/v2/list-transaction-routes): veja todas as Rotas de Transação configuradas. * [Consultar uma Rota de Transação](/pt/reference/products/midaz/v2/get-transaction-route-by-id): obtenha detalhes de uma Rota de Transação específica. * [Atualizar uma Rota de Transação](/pt/reference/products/midaz/v2/update-transaction-route): modifique critérios de roteamento existentes. * [Excluir uma Rota de Transação](/pt/reference/products/midaz/v2/delete-transaction-route): remova rotas que não são mais aplicáveis.