Pular para o conteúdo principal
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: source ou destination indicando o fluxo direcional da operação.
  • 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.
Configure-os 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.

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

​
Operações Contínuas

​
4. 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.

​
Gerenciando Operation e Transaction Routes

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