> ## 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 cada Transação com Rotas Contábeis e Operation Routes — aplique estrutura e regras de negócio antes de registrar qualquer movimentação. O conceito de **Rotas Contábeis** é o sistema de validação em duas camadas do Midaz para transações financeiras, construído a partir de **Rotas Contábeis** (que definem o padrão completo da transação) e **Operation Routes** (que validam cada operação individual dentro desse padrão). Juntos, eles garantem que toda transação seja estruturalmente correta e esteja em conformidade com suas regras de negócio. **Nomenclatura:** Este conceito é chamado de **Rotas Contábeis** (Accounting Routes) no Lerian Console e na documentação do produto. Na API e nos SDKs, a rota em nível de transação é representada pelo recurso `transactionRoute` (e pelos 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 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. Quando uma transação é submetida, o Midaz a valida em duas camadas: as **Rotas Contábeis** garantem que a estrutura geral corresponda ao padrão predefinido, enquanto as **Operation Routes** confirmam que cada componente atende aos requisitos de conta e regras de negócio. Se qualquer parte da transação falhar nessas verificações, ela é rejeitada antes de ser registrada — protegendo a integridade do seu ledger sem limitar sua flexibilidade. Você define os padrões de validação por meio de Operation Routes e Rotas Contábeis. O Midaz garante que suas transações estejam em conformidade com essas regras antes do processamento. ## Para que servem as Rotas Contábeis? *** As Rotas Contábeis oferecem controle estruturado sobre suas operações financeiras, separando a lógica de transações do código de negócio. Em vez de codificar regras de validação diretamente na sua aplicação, você configura padrões reutilizáveis que garantem que cada movimentação financeira siga os requisitos da sua organização. Essas entidades são dedicadas a vincular Transactions e Operations do ledger do Midaz a abstrações de nível superior que facilitam a integração com plugins especializados e sistemas externos, especialmente para abstrações de **contabilidade e tesouraria**. As anotações e classificações estruturadas criam um vocabulário padronizado que outros componentes podem entender e aproveitar. 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 integração transparente com plugins contábeis e sistemas financeiros externos. Seja processando transferências simples ou transações complexas com múltiplas partes, as Rotas Contábeis garantem que seus dados financeiros permaneçam estruturados, validados e confiáveis em escala, ao mesmo tempo que fornece a base semântica para integrações avançadas. ## Trabalhando com Rotas Contábeis *** Para usar as Rotas Contábeis, você precisa completar a configuração inicial seguida pela execução contínua de transações. Aqui está o processo passo a passo: ### 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](/pt/midaz/ledgers#ledger-settings). Isso controla se as transações nesse Ledger devem estar em conformidade com suas rotas configuradas. ```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null} { "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. As alterações nas configurações entram em vigor imediatamente — nenhum redeploy é necessário. Você pode atualizá-las a qualquer momento pela API. #### 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. **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](#4-configurar-lançamentos-contábeis-actions) 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: ```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ê 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. ```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" } } ``` * **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 à operation route através do campo `accountingEntries`, mapeando cada etapa do ciclo de vida da transação para os códigos contábeis de partidas dobradas corretos. O modelo completo de tipos de ação, os requisitos de débito/crédito e a matriz de validação são abordados em [Configurar Lançamentos Contábeis (Actions)](#4-configurar-lançamentos-contábeis-actions) abaixo. 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" } } }, "account": { "ruleType": "alias", "validIf": "@current_account" }, "metadata": { "channel": "pix" } } ``` O campo `operationType` também suporta `bidirectional`, que permite que a rota opere em ambas as direções — útil para rotas que lidam tanto com envio quanto com recebimento, ou para operações que podem precisar ser revertidas. #### 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, mapeando como diferentes 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. ```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. Configurar Lançamentos Contábeis (Actions) Cada Operation Route pode incluir **Lançamentos Contábeis** — rubricas estruturadas que definem como os lançamentos de débito e crédito são registrados para cada tipo de evento transacional (`direct`, `hold`, `commit`, `cancel`, `revert`). São eles que o motor usa para resolver quais contas são debitadas e creditadas para cada ação, e determinam as anotações `routeCode`/`routeDescription` escritas em cada operation. Se uma rubrica ausente é tolerada (graceful) ou rejeitada com `0117 ErrAccountingRouteNotFound` (estrito) é controlado por `accounting.validateRoutes` nas [Configurações do Ledger](/pt/midaz/ledgers#ledger-settings). 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 vs. estrito e exemplos completos de configuração estão documentados em detalhes na página de **[Lançamentos Contábeis](/pt/midaz/accounting-entries)**. Esta seção cobre apenas como as rubricas se vinculam às Operation Routes. No nível da rota, os lançamentos contábeis são fornecidos por meio do bloco `accountingEntries` (veja a **Opção C** em [Criar Operation Routes](#2-criar-operation-routes) acima), com um lançamento por ação e uma rubrica de `debit` e/ou `credit` 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 forem atendidas, a requisição é rejeitada antes de ser persistida. Entender essa matriz é fundamental para integradores: enviar 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 | Um lançamento sem `debit` nem `credit` é sempre rejeitado, independentemente do tipo de operação ou ação. **Regras adicionais:** * **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. Ao projetar suas operation routes, comece com a ação `direct` e 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 com confiança incluindo o ID da Rota Contábil previamente criada na sua requisição de transação**. O Midaz validará automaticamente a transação contra seus padrões de roteamento definidos, garantindo consistência e integridade em todas as operações financeiras. Para os exemplos de Rota Contábil e Operation Routes configurados anteriormente, o sistema 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} { "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" } ] } } } ``` Quando esta transação é submetida, o Midaz valida que a conta `@user/wallet_123` corresponde à regra de tipo de conta `user_wallet`, e `@external/BRL` corresponde ao requisito exato de alias, garantindo que a transação siga seus padrões de roteamento configurados. ##### Campos de rota nas operações Quando a validação de rotas está habilitada e os lançamentos contábeis estão configurados, toda operação processada com sucesso incluirá dois campos adicionais preenchidos 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, preenchida junto com o `routeCode`. Esses campos fornecem uma ligação direta entre cada operação e sua classificação contábil, permitindo que sistemas downstream (como o [Reporter](/pt/reporter/what-is-reporter)) produzam 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](/pt/reference/midaz/create-an-operation-route) — Defina uma nova regra contábil para suas operações. * [Listar Operation Routes](/pt/reference/midaz/list-operation-routes) — Visualize todas as Operation Routes configuradas. * [Recuperar uma Operation Route](/pt/reference/midaz/retrieve-an-operation-route) — Obtenha informações detalhadas sobre uma Operation Route específica. * [Atualizar uma Operation Route](/pt/reference/midaz/update-an-operation-route) — Modifique regras contábeis existentes. * [Excluir uma Operation Route](/pt/reference/midaz/delete-an-operation-route) — Remova uma Operation Route desatualizada ou não utilizada. Para **configurar suas Transaction Routes**, use os seguintes endpoints: * [Criar uma Transaction Route](/pt/reference/midaz/create-transaction-route) — Defina nova lógica de roteamento para conectar transações a operações contábeis. * [Listar Transaction Routes](/pt/reference/midaz/list-transaction-routes) — Visualize todas as Transaction Routes configuradas. * [Recuperar uma Transaction Route](/pt/reference/midaz/retrieve-a-transaction-route) — Obtenha detalhes de uma Transaction Route específica. * [Atualizar uma Transaction Route](/pt/reference/midaz/update-a-transaction-route) — Modifique critérios de roteamento existentes. * [Excluir uma Transaction Route](/pt/reference/midaz/delete-a-transaction-route) — Remova rotas que não são mais aplicáveis.