Pular para o conteúdo principal

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.

O Roteamento de Transações é o sistema de validação em duas camadas do Midaz para transações financeiras, construído a partir de Transaction Routes (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.
  • Transaction Routes 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: Transaction Routes garantem que a estrutura geral corresponda ao padrão predefinido, enquanto 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 Transaction Routes. O Midaz garante que suas transações estejam em conformidade com essas regras antes do processamento.

​
Para que serve o Roteamento de Transações?

O Roteamento de Transações oferece 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, o Roteamento de Transações garante 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 Roteamento de Transações

Para usar o Roteamento de Transações, 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. 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, 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.
  • 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). Representa a Origem.
    • destination — Identifica contas para onde os fundos são enviados (lado do crédito). Representa o Destino.
    • bidirectional — Aplica-se a ambos os lados da transação, atuando como Origem e Destino (Bidirecional).
  • 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 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 Cada etapa do ciclo de vida de uma transação — execução, liquidação, cancelamento, reversão — pode exigir suas próprias anotações contábeis. O campo accountingEntries mapeia cada etapa para os códigos contábeis de partida dobrada corretos automaticamente. Configure os lançamentos contábeis para cada tipo de ação: 
{
    "title": "PIX Cash-in - Current Account",
    "description": "Operation route for receiving PIX payments into current account",
    "code": "PIX-CASHIN-001",
    "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"
    }
}
Cada tipo de ação (direct, hold, commit, cancel, revert) é mapeado para um par contábil de partida dobrada — permitindo que seu ledger anote automaticamente as operações com os códigos contábeis corretos com base na etapa do ciclo de vida da transação.
O campo operationType agora também suporta bidirectional, que permite que a rota opere em ambas as direções — útil para rotas que lidam tanto com envio quanto recebimento, ou para operações que podem precisar ser revertidas.

​
Matriz de validação de accounting entries

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çãoDébitoCréditoNotas
directObrigatórioOpcionalTransação padrão de etapa única na origem
holdObrigatórioObrigatórioReserva fundos — move available → on_hold
commitObrigatórioOpcionalFinaliza uma transação em duas fases
cancelObrigatórioObrigatórioLibera os fundos reservados — move on_hold → available
revert——Não permitido (erro 0165). Use bidirectional no lugar
destination
AçãoDébitoCréditoNotas
directOpcionalObrigatórioTransação padrão de etapa única no destino
hold——Não permitido (erro 0162)
commitOpcionalObrigatórioFinaliza uma transação em duas fases
cancel——Não permitido (erro 0162)
revert——Não permitido (erro 0165). Use bidirectional no lugar
bidirectional
AçãoDébitoCréditoNotas
directObrigatórioObrigatórioAmbos os lados da partida dobrada
holdObrigatórioObrigatórioAmbos os lados da partida dobrada
commitObrigatórioObrigatórioAmbos os lados da partida dobrada
cancelObrigatórioObrigatórioAmbos os lados da partida dobrada
revertObrigatórioObrigatórioÚnica direção que suporta revert
Uma entry sem debit nem credit é sempre rejeitada, 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 a entry 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.

​
3. Construir Transaction Routes

Complete sua configuração combinando Operation Routes em Transaction Routes. 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 agora utiliza um array de objetos com operationRouteId em vez de um array simples de UUIDs. Se você tem integrações existentes, atualize-as para usar o novo formato.
{
    "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 Rota de Operação 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. Quando um Ledger está configurado para validar rotas, apenas eventos com lançamentos registrados são permitidos. Isso garante consistência nos seus relatórios contábeis.
Tipos de ação
Cada ação representa um evento transacional. Você configura Lançamentos Contábeis por ação em cada Rota de Operação:
AçãoIdentificadorDescrição
Transação DiretadirectTransação padrão de uma etapa entre duas contas, sem estágios intermediários.
Reserva de ValorholdPrimeiro passo de uma Transação em Duas Etapas: move o valor do saldo available para on_hold na conta de origem.
Confirmação da ReservacommitConfirma uma Transação em Duas Etapas pendente, transferindo o valor on_hold da conta de origem para o saldo available na conta de destino.
Cancelamento da ReservacancelCancela uma Transação em Duas Etapas pendente, retornando o valor on_hold para o saldo available na conta de origem.
EstornorevertCria uma transação reversa que desfaz a operação original.
Estrutura do Lançamento Contábil
Cada lançamento de ação contém uma rubrica de Débito e/ou Crédito, dependendo do tipo de operação:
  • Rotas de Origem (source) requerem a rubrica de Débito.
  • Rotas de Destino (destination) requerem a rubrica de Crédito.
  • Rotas Bidirecionais (bidirectional) requerem ambas as rubricas de Débito e Crédito.
Cada rubrica possui:
  • code — O Código da Conta no plano de contas (ex.: 1.1.1.001).
  • description — Uma descrição legível do lançamento (ex.: Customer checking — outbound).
{
    "title": "Pix Transfer",
    "description": "Bidirectional route for Pix transfers between checking accounts",
    "operationType": "bidirectional",
    "account": {
        "ruleType": "account_type",
        "validIf": ["checking"]
    },
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — reserve"
            },
            "credit": {
                "code": "2.1.1.001",
                "description": "Pending settlement — hold"
            }
        },
        "commit": {
            "debit": {
                "code": "2.1.1.001",
                "description": "Pending settlement — release"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — settled"
            }
        }
    }
}
Comportamento de validação
Quando a validação de rotas está habilitada para um Ledger e Lançamentos Contábeis estão configurados:
  • Apenas eventos com lançamentos registrados são permitidos. Se um cliente registrar apenas a ação direct em uma rota, qualquer tentativa de executar uma Transação em Duas Etapas (que requer hold) será automaticamente rejeitada.
  • Operações bem-sucedidas terão os detalhes da rubrica registrados nos campos routeCode e routeDescription em cada operação.
Se uma rota possui Lançamentos Contábeis configurados, mas a transação submetida utiliza uma ação que não está registrada, a transação será negada. Isso previne inconsistências nos seus relatórios contábeis ao garantir que todas as etapas de uma operação estejam devidamente mapeadas antes da execução.
Cenário: Um cliente cria uma Rota de Operação com apenas a ação direct configurada.Se esse cliente tentar uma Transação em Duas Etapas (enviando pending: true), a transação é automaticamente rejeitada porque não há lançamento hold registrado.Isso garante que seus relatórios contábeis permaneçam consistentes — todas as etapas de uma operação devem ser mapeadas antes de poderem ser executadas.

​
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 Transaction Route 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 Transaction Route e Operation Routes configurados anteriormente, o sistema 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: 
{
    "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 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 Código da Conta no plano de contas da rubrica do Lançamento Contábil correspondente.
  • routeDescription — A descrição da rubrica do Lançamento Contábil correspondente.
Esses campos fornecem uma ligação direta entre cada operação e sua classificação contábil, permitindo que sistemas downstream (como o Reporter) produzam relatórios financeiros precisos sem consultas adicionais.

​
Gerenciando Operation e Transaction Routes

Para configurar suas Operation Routes, use os seguintes endpoints: Para configurar suas Transaction Routes, use os seguintes endpoints: