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, você precisa configurá-lo no serviço de Transaction. Isso significa atualizar as variáveis de Transaction no arquivo .env do serviço Midaz Transaction onde você deseja usar a validação de rotas. Sua configuração deve ficar assim: 
# List of <organization-id>:<ledger-id> separated by comma
TRANSACTION_ROUTE_VALIDATION=

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

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

​
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: