> ## 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. > [!NOTE] > > **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ê habilita a validação de rota em um Ledger, o Midaz valida cada transação 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. > [!NOTE] > > 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](https://docs.lerian.studio/pt/products/midaz/ledgers.md#ledger-settings). Isso controla se as transações nesse Ledger devem cumprir as rotas que você configurou. ```json PATCH /v2/organizations/{organization_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. #### 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. 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](#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" }, "accountingEntries": { "direct": { "credit": { "code": "3.1.001", "description": "Fee revenue" } } } } ``` * **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"] }, "accountingEntries": { "direct": { "debit": { "code": "1.1.1.001", "description": "User wallet fee" } } } } ``` **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-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" } } ``` > [!NOTE] > > 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. Uma Rota Contábil precisa de pelo menos uma Rota de Operação de origem e uma de destino (erros `0153` e `0154`). Uma rota bidirecional conta como as duas. Na `/v2`, uma Rota Contábil também pode vincular Rotas de Operação opcionais em `optionalOperationRoutes`. Uma transação pode deixar uma rota opcional sem uso, por exemplo uma rota de tarifa quando nenhuma tarifa se aplica. O Midaz valida uma perna que a usa como qualquer outra perna. Apenas as rotas em `operationRoutes` contam para a regra de origem e destino. * 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`. ```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": [ "0197e6aa-1695-734a-a8c3-8c79e0ad32c2", "0197e675-37cc-71d7-96c2-f58000f33aa0" ] } ``` #### 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`. Quatro chaves suplementares (`overdraft`, `block`, `unblock` e `crossLedger`) descrevem impacto contábil, mas **não** são ações válidas de rota de transação. Os lançamentos determinam as anotações `routeCode` e `routeDescription` em cada operação. A configuração `accounting.validateRoutes` nas [Configurações do Ledger](https://docs.lerian.studio/pt/products/midaz/ledgers.md#ledger-settings) controla esse comportamento. Quando você a habilita, o Midaz rejeita uma transação cujas pernas não correspondem aos lançamentos da Rota Contábil dela. Quando você a desabilita, o Midaz não resolve nenhuma rubrica, e `routeCode` fica vazio. > [!NOTE] > > A página **[Lançamentos Contábeis](https://docs.lerian.studio/pt/products/midaz/accounting-entries.md)** 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 | > [!CAUTION] > > 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 (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). > [!TIP] > > 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, defina **`routeId`** com o ID da Rota Contábil que você criou, e **`operationRouteId`** em cada perna. 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 ``` Uma requisição correspondente para [criar uma transação direta](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct.md): ```json JSON expandable theme={null} { "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" } ] } ``` Quando você envia essa transação, o Midaz verifica se a conta `@user_wallet_123` tem um dos tipos de conta da regra `account_type`. Ele também verifica se a conta creditada é `@external/BRL`. ##### 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](https://docs.lerian.studio/pt/products/reporter/what-is-reporter.md) 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](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-operation-route.md): defina uma nova regra contábil para suas operações. * [Listar Rotas de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-operation-routes.md): veja todas as Rotas de Operação configuradas. * [Consultar uma Rota de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-operation-route-by-id.md): obtenha informações detalhadas sobre uma Rota de Operação específica. * [Atualizar uma Rota de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-operation-route.md): modifique regras contábeis existentes. * [Excluir uma Rota de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-operation-route.md): remova uma Rota de Operação desatualizada ou não usada. Para configurar suas Rotas Contábeis (o recurso `transactionRoute` na API), use os seguintes endpoints: * [Criar uma Rota de Transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-route.md): defina uma nova lógica de roteamento para conectar transações a operações contábeis. * [Listar Rotas de Transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-transaction-routes.md): veja todas as Rotas de Transação configuradas. * [Consultar uma Rota de Transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-transaction-route-by-id.md): obtenha detalhes de uma Rota de Transação específica. * [Atualizar uma Rota de Transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-transaction-route.md): modifique critérios de roteamento existentes. * [Excluir uma Rota de Transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-transaction-route.md): remova rotas que não são mais aplicáveis. As rotas pertencem à Organização. Uma transação em qualquer Ledger da Organização pode usar uma rota, seja qual for o Ledger em que você a criou. Para criar uma rota sem Ledger, use [Criar uma Rota de Operação da organização](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-organization-operation-route.md) e [Criar uma Rota de Transação da organização](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-organization-transaction-route.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.