> ## 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. # Transações > Registre eventos financeiros com as Transações de partidas dobradas do Midaz: múltiplos Saldos, débitos, créditos e rastreabilidade completa entre Contas. Uma **Transação** no Midaz registra um evento financeiro completo. Uma transação costuma usar múltiplas contas e saldos. O Midaz roda em um sistema de contabilidade de partidas dobradas que mantém toda movimentação financeira balanceada. Com o recurso de **múltiplos saldos**, cada operação especifica a conta e a **chave de saldo** a ser usada. Você pode então debitar ou creditar diferentes saldos lógicos da mesma conta (por exemplo, `credit`, `operational` ou `collateral`). > [!NOTE] > > Se você não informar uma `balanceKey`, a transação usa o **saldo padrão**. ## Contabilidade de partidas dobradas *** O sistema de partidas dobradas segue um princípio. Uma transação lançada tem pelo menos uma operação de débito e uma de crédito. Uma transação pendente registra apenas o lado de origem até você confirmá-la. Essa estrutura registra toda a atividade financeira e mantém suas contas balanceadas. Cada transação usa dois tipos de lançamento: * **Débitos** mostram o valor recebido ou os recursos consumidos. * **Créditos** mostram o valor dado ou os recursos fornecidos. O Midaz rejeita uma transação cujos débitos e créditos não se equilibram. ### Exemplo Neste exemplo, você transfere R\$ 1.000 de uma conta para outra. A transação tem duas operações: * Uma operação para debitar R\$1.000,00 da conta de origem. * Uma operação para creditar R\$1.000,00 na conta de destino. O Midaz captura os dois lançamentos automaticamente. Você pode visualizar e analisar essas movimentações pela API ou pelo Lerian Console. ## Transações N:N (muitos para muitos) *** Sistemas financeiros tradicionais limitam as transações a relações um-para-um ou um-para-muitos. O Midaz oferece suporte a transações N:N. Uma única transação pode usar múltiplas contas de origem e destino. ### Exemplos * **Repasse de marketplace**: uma única conta escrow paga vários vendedores, e cada vendedor paga uma tarifa da plataforma. * **Peer-to-peer com tarifas**: uma transação debita o pagador e credita tanto o recebedor quanto uma conta de tarifa. O Midaz processa cada caso como uma única transação atômica. Ele debita e credita todas as partes juntas. ## Atomicidade e integridade *** As transações são atômicas. **Ou todas as operações são bem-sucedidas, ou nenhuma é.** Eventos financeiros parciais não ocorrem. Se qualquer parte de uma transação falhar na validação (por exemplo, uma conta tem fundos insuficientes), o Midaz não aplica a transação. O ledger permanece consistente. ## Origem da transação *** Uma transação no Midaz pode partir de uma única origem ou de múltiplas origens. > [!CAUTION] > > A soma dos valores em `source` deve ser igual ao valor em `send`. Ela também deve ser igual à soma dos valores em `distribute`. ### Origem única Em uma transação de origem única, o Midaz retira o valor de uma conta de origem. Você também pode especificar um saldo específico. #### Exemplo Neste exemplo (*Figura 1*): * O Midaz retira BRL 30,00 de `@account1` (saldo `credit`). * Ele envia 100% para `@destinationAccount1` (saldo `operational`) ![Transação de origem única movendo BRL 30,00 de uma conta de origem para uma única conta de destino](https://mintcdn.com/lerian-49cb71fc/TGLv2g3qhXqf0dqb/images/pt/d2/single-source.svg?fit=max\&auto=format\&n=TGLv2g3qhXqf0dqb\&q=85\&s=96804eb477dc5113ad509cd57f273238) Figura 1. Exemplo de uma transação de origem única. **Exemplos de código** ```json JSON Example expandable theme={null} { "description": "single source transaction", "send": { "asset": "BRL", "value": "30.00", "source": { "from": [ { "accountAlias": "@account1", "balanceKey": "credit", // optional "amount": { "asset": "BRL", "value": "30.00" } } ] }, "distribute": { "to": [ { "accountAlias": "@destinationAccount1", "balanceKey": "operational", // optional "share": { "percentage": 100 } } ] } } } ``` ### Múltiplas origens Em uma transação de múltiplas origens, o Midaz retira fundos de múltiplas contas ou saldos. #### Exemplo Neste exemplo (*Figura 2*): * O Midaz envia BRL 30,00 para a conta de destino (`@destinationAccount1`). * BRL 15,00 de `@account1` (saldo `default`). * BRL 15,00 de `@account2` (saldo `investment`). * A conta de destino recebe 100% do valor. ![Transação de múltiplas origens em que BRL 30,00 são retirados de duas contas de origem e enviados para uma única conta de destino](https://mintcdn.com/lerian-49cb71fc/TGLv2g3qhXqf0dqb/images/pt/d2/multi-source.svg?fit=max\&auto=format\&n=TGLv2g3qhXqf0dqb\&q=85\&s=08668e5d8a9e2388565fcce22fcba2b4) Figura 2. Exemplo de uma transação de múltiplas origens. **Exemplos de código** ```json JSON Example theme={null} { "description": "multi-source transaction", "send": { "asset": "BRL", "value": "30.00", "source": { "from": [ { "accountAlias": "@account1", "balanceKey": "default", "amount": { "asset": "BRL", "value": "15.00" } }, { "accountAlias": "@account2", "balanceKey": "investment", "amount": { "asset": "BRL", "value": "15.00" } } ] }, "distribute": { "to": [ { "accountAlias": "@destinationAccount1", "share": { "percentage": 100 } } ] } } } ``` ## Destino da transação *** Assim como as origens, os destinos podem ser únicos ou múltiplos. ### Destino único Em uma transação de destino único, o Midaz envia o valor para apenas uma conta de destino. #### Exemplo Neste exemplo (*Figura 3*): * O Midaz retira BRL 30,00 de uma conta externa (`@external/BRL`). * Ele envia 100% para a conta de destino (`@destinationAccount1`). ![Transação de destino único movendo BRL 30,00 de uma conta externa para uma conta de destino](https://mintcdn.com/lerian-49cb71fc/TGLv2g3qhXqf0dqb/images/pt/d2/single-destination.svg?fit=max\&auto=format\&n=TGLv2g3qhXqf0dqb\&q=85\&s=28d8fce8770d0af45542e8434051c283) Figura 3. Exemplo de uma transação de destino único. **Exemplos de código** ```json JSON Example theme={null} { "description":"single destination transaction", "send":{ "asset":"BRL", "value":"30.00", "source":{ "from":[ { "accountAlias":"@external/BRL", "amount":{ "asset":"BRL", "value":"30.00" } } ] }, "distribute":{ "to":[ { "accountAlias":"@destinationAccount1", "share":{ "percentage":100 } } ] } } } ``` ### Múltiplos destinos Em uma transação de múltiplos destinos, o Midaz divide o valor entre múltiplas contas de destino. Você pode distribuir os valores por percentuais, valores fixos ou o valor restante. #### Exemplo Neste exemplo (*Figura 4*): * O Midaz retira BRL 100 da conta de origem (`@account1`). * 38% do valor vai para a conta 2 (`@account2`). * 50% vai para a conta 3 (`@account3`). * Um valor fixo de BRL 2,00 vai para a conta 4 (`@account4`). * O valor restante vai para a conta 5 (`@account5`). ![Transação com múltiplos destinos dividindo BRL 100,00 de uma conta de origem entre cinco contas de destino por percentual e valores fixos](https://mintcdn.com/lerian-49cb71fc/TGLv2g3qhXqf0dqb/images/pt/d2/multi-destination.svg?fit=max\&auto=format\&n=TGLv2g3qhXqf0dqb\&q=85\&s=2d4447f5bb8cee43361ef957cc0604db) Figura 4. Exemplo de uma transação com múltiplos destinos. **Exemplo de código** ```json JSON Example theme={null} { "description":"multi-destination transaction", "send":{ "asset":"BRL", "value":"100.00", "source":{ "from":[ { "accountAlias":"@account1", "amount":{ "asset":"BRL", "value":"100.00" } } ] }, "distribute":{ "to":[ { "accountAlias":"@account2", "share":{ "percentage":38 } }, { "accountAlias":"@account3", "share":{ "percentage":50 } }, { "accountAlias":"@account4", "amount":{ "asset":"BRL", "value":"2.00" } }, { "accountAlias":"@account5", "remaining":"remaining" } ] } } } ``` ## Múltiplas origens e múltiplos destinos *** Essas transações usam múltiplas origens e múltiplos destinos. Elas são úteis para casos como uma campanha de financiamento coletivo. O Midaz reúne as contribuições e as distribui entre múltiplos destinatários. #### Exemplo Neste exemplo (*Figura 5*): * A doação é de BRL 4.000,00. O Midaz a retira de quatro contas diferentes. * 25% vêm da conta 1 (`@account1`). * 25% vêm da conta 2 (`@account2`). * 40% vêm da conta 3 (`@account3`) * 10% vêm da conta 4 (`@account4`). * O Midaz distribui as doações para quatro contas separadas. Cada conta recebe uma parcela de 25% do total. ![Transação com múltiplas origens e múltiplos destinos retirando BRL 4.000,00 de quatro contas e distribuindo-as igualmente entre quatro contas de destino](https://mintcdn.com/lerian-49cb71fc/TGLv2g3qhXqf0dqb/images/pt/d2/multi-source-destination.svg?fit=max\&auto=format\&n=TGLv2g3qhXqf0dqb\&q=85\&s=6953060d696f499d6d4250a669c6e784) Figura 5. Exemplo de uma transação com múltiplas origens e múltiplos destinos. **Exemplos de código** ```json JSON Example theme={null} { "description":"multi-source and multi-destination transaction", "send":{ "asset":"BRL", "value":"4000.00", "source":{ "from":[ { "accountAlias":"@account1", "share":{ "percentage":25 } }, { "accountAlias":"@account2", "share":{ "percentage":25 } }, { "accountAlias":"@account3", "share":{ "percentage":40 } }, { "accountAlias":"@account4", "share":{ "percentage":10 } } ] }, "distribute":{ "to":[ { "accountAlias":"@donation1", "share":{ "percentage":25 } }, { "accountAlias":"@donation2", "share":{ "percentage":25 } }, { "accountAlias":"@donation3", "share":{ "percentage":25 } }, { "accountAlias":"@donation4", "share":{ "percentage":25 } } ] } } } ``` ## Status das transações *** Toda transação no Midaz tem um status. O status reflete o estágio atual dela no ciclo de vida. Você precisa desses status para projetar fluxos de transação, configurar consumidores de eventos e ler dados do ledger. | Status | O que significa | Afeta saldos? | Como é criada | | :- | :- | :- | :- | | `CREATED` | O Midaz lançou a transação imediatamente. Apenas a resposta de criação traz este status. O Midaz armazena a transação como `APPROVED`. | Sim | Resposta de criação de uma transação que não é pendente nem anotação, incluindo reversões | | `APPROVED` | A transação foi concluída com sucesso. Os fundos foram movidos entre as contas. | Sim | Status armazenado de uma transação `CREATED`, ou commit de uma transação `PENDING` | | `PENDING` | Uma Transação em Duas Fases está aguardando confirmação. Os fundos ficam reservados em `on_hold`, mas ainda não são transferidos. | Sim (reserva) | [Criar uma transação](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md) com `"pending": true` | | `CANCELED` | Uma Transação em Duas Fases foi cancelada. Os fundos reservados são liberados de volta para `available`. | Sim (liberação) | [Cancelar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/cancel-transaction.md) | | `NOTED` | Uma transação de anotação registrada no ledger sem afetar saldos. As operações preservam a estrutura de partidas dobradas, mas todos os campos de saldo são zerados. | Não | [Criar uma anotação de transação](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-annotation.md) | > [!TIP] > > Use o status `NOTED` para importar transações legadas, registrar trilhas de auditoria e registrar eventos de compliance. Ele serve para qualquer caso em que a transação precise existir no ledger, mas os saldos já tenham sido liquidados em outro lugar. ### Transições de status As transações seguem caminhos previsíveis por esses status: * **Fluxo padrão:** → `APPROVED` (uma etapa) * **Fluxo em duas fases:** → `PENDING` → `APPROVED` (commit) ou `CANCELED` (cancel) * **Fluxo de anotação:** → `NOTED` (terminal, sem transições) > [!NOTE] > > Quando uma transação chega a `NOTED` ou `CANCELED`, ela não pode fazer mais transições. Ambos são status terminais. ## Fluxo da transação *** Quando uma transação começa, o Midaz valida: * As contas envolvidas. * Os saldos especificados (`balanceKey`, ou `default` se não for informado). * Permissões (`allowSending`, `allowReceiving`). * Fundos disponíveis suficientes no saldo selecionado. Contas externas não passam por essa verificação, e um saldo que permite overdraft pode usar o [overdraft](https://docs.lerian.studio/pt/products/midaz/balance-overdraft.md). Se a validação passa e a transação não é pendente nem anotação, o Midaz transfere o valor **imediatamente**. Ele move o valor da conta de origem para a conta de destino, a partir do saldo disponível. Em caso de sucesso, o status da transação passa a `APPROVED`. > [!CAUTION] > > Inicie esse tipo de transação **apenas** se você pretende registrá-la no ledger imediatamente. Para transações que precisam de validação ou aprovação antes, use a flag `pending` para criar uma **Transação em Duas Fases**. ## Transação em Duas Fases *** Nesse fluxo, o Midaz cria a transação com status `PENDING`. O Midaz não move os fundos de imediato. Em vez disso, ele reserva o valor no saldo correto (`balanceKey`, ou `default` se você não informar um). * O saldo de destino não muda até você fazer o commit. * Você deve fazer `commit` explicitamente para executar a transferência, ou `cancel` para liberar os fundos. * O Midaz recusa uma conta externa que você envia como origem de uma transação pendente (erro `0098`). > [!TIP] > > O recurso de Transação em Duas Fases oferece suporte ao [Flowker](https://docs.lerian.studio/pt/products/flowker/what-is-flowker.md). Você reserva os fundos no início de um workflow e roda as validações depois. Na *Figura 6*, você pode ver um exemplo de uma transação em duas fases com antifraude. ![Transação em duas fases em um workflow antifraude, reservando os fundos primeiro e confirmando ou cancelando-os após a validação](https://mintcdn.com/lerian-49cb71fc/vmD1Fy0bDd1EWOlC/images/pt/d2/two-phase-transaction.svg?fit=max\&auto=format\&n=vmD1Fy0bDd1EWOlC\&q=85\&s=6d9b8b6b3ae5c00427a12bedaf7238c5) Figura 6. Exemplo de workflow antifraude ### Fluxo da Transação em Duas Fases #### 1. Criar uma Transação em Duas Fases * Use o endpoint [Criar uma transação usando JSON](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md) com `"pending": true`. O Midaz valida as contas, os saldos especificados (`balanceKey`), as permissões (`allowSending`, `allowReceiving`) e os fundos disponíveis. Se válida: * O Midaz reserva os fundos no saldo correto. * O Midaz define o status da transação como `PENDING`. * O Midaz armazena os metadados. #### 2. Confirmar ou cancelar a transação pendente * **Commit**: finaliza a transação. Os fundos passam de `on_hold` para o saldo de destino. * Use o endpoint [Confirmar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/commit-transaction.md). * Status: `APPROVED`. * **Cancel**: libera os fundos reservados de volta para `available` no mesmo saldo. * Use o endpoint [Cancelar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/cancel-transaction.md). * Status: `CANCELED`. Se você repetir uma confirmação ou um cancelamento depois que ele foi bem-sucedido, o Midaz responde `0486` por até 300 segundos e `0099` depois disso. Para saber o resultado, consulte o status da transação. ## Transações Passadas *** O Midaz também oferece suporte a transações passadas. As instituições podem importar eventos financeiros legados e manter a precisão histórica. * Use o campo opcional `transactionDate` para definir a data original da transação. * `transactionDate` não altera o histórico do saldo. O histórico do saldo usa o momento em que o Midaz registra a transação. * Transações criadas pelo endpoint [Criar uma anotação de transação](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-annotation.md) validam a estrutura, mas **não** afetam saldos. Elas servem para auditorias, compliance e importações em que os saldos devem permanecer inalterados. ### Exemplo ```json theme={null} { "description": "past transaction example", "transactionDate": "2025-01-01T13:38:31.064Z", // optional "send": { "asset": "BRL", "value": "1000", "source": { "from": [ { "accountAlias": "@external/BRL", "amount": { "asset": "BRL", "value": "1000" } } ] }, "distribute": { "to": [ { "accountAlias": "@account1_BRL", "amount": { "asset": "BRL", "value": "1000" } } ] } } } ``` ## Transações sem impacto financeiro *** O Midaz pode criar transações que registra no ledger, mas que não afetam os saldos das contas. Essas transações mantêm a integridade estrutural e deixam os saldos inalterados. Esse recurso é útil quando você precisa: * Importar transações legadas mantendo os saldos inalterados. * Registrar eventos de auditoria ou compliance. * Adicionar operações de negócio que o ledger deve rastrear, mas que não movem fundos. ### Como funciona? Quando você cria uma transação sem impacto financeiro: * O Midaz armazena os campos `balance` e `balanceAfter` como 0 para preservar a validação de partidas dobradas. * Cada operação tem um campo `balanceAffected` (booleano): * true → a operação afeta o saldo da conta. * false → o Midaz registra a operação no ledger, mas não altera os saldos. > [!CAUTION] > > Mesmo quando o Midaz não atualiza nenhum saldo, ele aplica as regras de partidas dobradas. Isso mantém a consistência em todas as transações do ledger. #### Exemplo ```json theme={null} { "description": "annotation example", "transactionDate": "2025-01-01T13:38:31.064Z", "send": { "asset": "BRL", "value": "1000", "source": { "from": [ { "accountAlias": "@external/BRL", "amount": { "asset": "BRL", "value": "1000" } } ] }, "distribute": { "to": [ { "accountAlias": "@account1_BRL", "amount": { "asset": "BRL", "value": "1000" } } ] } } } ``` #### Endpoint relacionado * [Criar uma anotação de transação](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-annotation.md): registre uma transação sem impacto financeiro no ledger. ## Publicação de eventos em tempo real *** O Midaz publica eventos do ciclo de vida das transações pela sua superfície de streaming compatível com Kafka. Você pode acompanhar suas transações à medida que elas mudam. Depois de habilitar esse recurso, o Midaz emite `transaction.posted`, `transaction.committed`, `transaction.canceled` e `transaction.reverted`. Uma nova transação `PENDING` e uma transação `NOTED` não emitem evento. Uma transação que abrange vários Ledgers também emite eventos de grupo; veja [Publicador de eventos](https://docs.lerian.studio/pt/products/midaz/event-publisher.md). Para saber mais sobre como publicar e consumir eventos de transação, veja a página [Publicador de eventos](https://docs.lerian.studio/pt/products/midaz/event-publisher.md). ## Entradas, saídas e contas externas *** O Midaz usa um ledger de partidas dobradas. Todo valor que entra ou sai do sistema deve passar por uma conta especial: a **Conta Externa**. O Midaz representa essa conta como `@external/{{assetCode}}`. Ela é a ponte entre o Midaz e o mundo financeiro externo (bancos, PSPs, trilhos de pagamento e assim por diante). ### Trazendo fundos para o Midaz Quando você inicializa o ledger pela primeira vez, todas as contas, incluindo `@external`, começam com saldo zero. Para refletir saldos do mundo real, como fundos institucionais mantidos fora do Midaz, você deve iniciar uma transação que injete fundos nas contas do Midaz e debite a conta externa. Essa é a única forma de trazer fundos para o Midaz. ### Entradas – adicionando valor ao Ledger Para creditar uma conta interna de fora do ledger: * **Origem**: `@external/{{assetCode}}` (por exemplo, `@external/BRL`). * **Destino**: uma ou mais contas internas (por exemplo, `@organization.main`). **Exemplo: primeiro depósito no Ledger** Sua instituição mantém R\$ 10.000 em um banco do mundo real e quer trazê-los para o Midaz. Você cria uma transação: | Origem | Destino | Valor | | :- | :- | :- | | @external/BRL | @accountA | BRL 10.000 | Isso debita a conta externa e credita sua conta interna. O saldo da conta externa representa o valor total que sua organização trouxe para o ledger. ### Saídas – movendo valor para fora do Ledger Para mover valor do ledger para um destino externo: * **Origem**: uma ou mais contas do Midaz. * **Destino**: `@external/{{assetCode}}`. **Exemplo: uma transferência Pix do Ledger para um banco externo** | Origem | Destino | Valor | | :- | :- | :- | | @accountA | @external/BRL | BRL 1.000 | Isso debita `@accountA` e credita a conta externa. Em seguida, seu sistema transfere os fundos para o destinatário por meio do SPI ou de outra integração. ### Comportamento e regras de saldo > [!NOTE] > > Todo valor que se move entre o mundo externo e o ledger do Midaz deve passar pela conta externa. > > Nada entra ou sai do sistema sem uma transação formal. ## Definindo uma data personalizada para a transação *** O campo `transactionDate` permite definir uma data personalizada para uma transação, independentemente de quando você a envia para a API. * **Opcional.** Se você omiti-lo, o Midaz usa o timestamp atual. * **Formatos aceitos:** * ISO 8601 com fuso horário: `2026-01-15T10:30:00Z` * ISO 8601 sem fuso horário: `2026-01-15T10:30:00` * Apenas a data: `2026-01-15` * **Restrição:** você não pode usar uma data futura. Uma data futura retorna o erro `0121`. * **Restrição:** você não pode usá-lo em transações `PENDING`. Um `transactionDate` com `"pending": true` retorna o erro `0122`. ### Casos de uso * Registrar transações que ocorreram no passado (por exemplo, correções no mesmo dia) * Importar dados financeiros históricos para um novo ledger * Conciliar com sistemas externos que usam uma data de lançamento diferente ## Rotas de Transação *** A API de **Rotas de Transação** permite o processamento estruturado e validado de transações no Midaz. > [!NOTE] > > O Lerian Console e a documentação do produto chamam esse conceito de **Rotas Contábeis**. O recurso e os endpoints da API mantêm o nome `transactionRoute` / Rotas de Transação. Ambos se referem à mesma rota no nível da transação. A API de Transações executa eventos financeiros: débitos e créditos entre contas. As Rotas de Transação definem templates para **como** estruturar e validar esses eventos. Isso os mantém consistentes e corretos. A API de Rotas de Transação é a camada de validação. Ela faz as transações de negócio seguirem padrões predefinidos e manterem uma estrutura financeira adequada. Por exemplo, uma tarifa, um depósito ou um repasse podem precisar de diferentes tipos de conta, regras de validação e estruturas. Em vez de tratar a validação separadamente para cada transação, você configura regras predefinidas. Essas regras dizem ao Midaz: "*Quando o usuário enviar esse tipo de transação, valide-a de acordo com estes requisitos de conta e padrões de estrutura.*" Cada Rota de Transação combina múltiplas **Rotas de Operação**. Uma Rota de Operação define um componente de uma transação. Ela define os requisitos de conta, a direção (origem, destino ou bidirecional) e as regras de validação para cada "perna" do evento financeiro. > [!WARNING] > > Não use o campo `route` nas entradas `from` e `to` da v1. Use `routeId` em vez disso. `routeId` aceita um UUID que referencia uma Rota de Operação criada pela API de Rotas de Operação. O Midaz aceita `route`, mas não o usa na validação. ### O que você faz com as Rotas de Transação Com as **Rotas de Transação**, você: * Mantém uma estrutura de transação consistente em toda a sua aplicação. * Valida eventos financeiros de acordo com padrões predefinidos. * Configura templates de transação sem alterações de código. * Mantém a integridade dos dados por meio de validação estruturada. ## Iniciando uma transação *** > [!WARNING] > > Ao criar transações pela API, sempre implemente **idempotência** para evitar o processamento duplicado. O Midaz oferece suporte nativo a idempotência por meio do header `X-Idempotency`. Valide o header de resposta `X-Idempotency-Replayed` para diferenciar novas transações de replays em cache. Veja [Novas tentativas e idempotência](https://docs.lerian.studio/pt/reference/retries-idempotency.md) para mais detalhes. Use a API de transação JSON para iniciar uma transação. ### Formato da requisição JSON na v2 Os endpoints v2 [`direct`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct), [`hold`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-hold), [`block`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-block) e [`unblock`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-unblock) compartilham um mesmo corpo. Os arrays obrigatórios `debits` e `credits` contêm as pernas de cada lado. As pernas de cada lado devem somar o `amount` do nível da requisição. Cada perna exige `alias`, `organizationId`, `ledgerId` e exatamente uma expressão de valor: `amount` ou `share`. A expressão `remaining` não é aceita na v2. Cada array aceita de 1 a 500 pernas. `share.percentage` vai de 1 a 100; `share.percentageOfPercentage` vai de 0 a 100, em que `0` significa nenhum estreitamento. As requisições de criação da v2 têm um limite de corpo de 1 MiB. O campo opcional `scheme` indica o esquema de pagamento da transação, por exemplo `PIX`, `WIRE`, `CARD` ou `CRYPTO`. O Midaz aceita até 50 letras, dígitos, sublinhados ou hífens e armazena o valor sem espaços nas pontas e em maiúsculas. As respostas da v2 e os eventos de transação o retornam, e um estorno na v2 mantém o esquema da transação original. Um corpo da v1 não pode enviá-lo. ### Usando o endpoint JSON * Para criar uma transação com JSON, use o endpoint [Criar uma transação usando JSON](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md). > [!CAUTION] > > Se você precisar reservar fundos **antes** de concluir a transferência, defina o campo `pending` como `true` (fluxo de Transação em Duas Fases). ## Revertendo uma transação *** O Midaz oferece suporte à reversão de transações. Você pode desfazer uma transação aprovada. O Midaz cria uma transação espelho que inverte os débitos e créditos originais. Esse mecanismo mantém trilhas de auditoria completas e cancela o impacto financeiro nos saldos das contas. > [!NOTE] > > A reversão cria uma **nova transação** que compensa a original. A transação original permanece no histórico do ledger para rastreabilidade completa. > [!WARNING] > > A reversão não envia uma chave de idempotência própria, então o Midaz deriva uma. Leia o header de resposta `X-Idempotency-Replayed`: `true` significa que você recebeu uma reversão em cache, e não uma recém-criada. Trate um replay como um sinal para verificar o estado da origem antes de tentar novamente. ### Como funciona? Quando você reverte uma transação, o Midaz automaticamente: 1. **Inverte as operações**: * As operações CREDIT se tornam operações de origem (`from`). * As operações DEBIT se tornam operações de destino (`to`). 2. **Cria uma nova transação** com: * O mesmo valor e código de ativo. * A mesma descrição e os seus metadados. * Operações invertidas (quem recebe passa a enviar, quem envia passa a receber). * Status: `CREATED` na resposta de criação, armazenado como `APPROVED`. * `parentTransactionId` que referencia a transação original. 3. **Processa a reversão** pelo fluxo padrão de transação: validação, atualização de saldos e registro no histórico. ### Exemplo **Transação original**: * Conta A (débito -100) → Conta B (crédito +100) **Transação de reversão criada**: * Conta B (débito -100) → Conta A (crédito +100) **Resultado**: * A Conta A volta ao saldo anterior (recebe de volta o -100). * A Conta B volta ao saldo anterior (perde o +100). * As duas transações permanecem no histórico do ledger para fins de auditoria. * A transação de reversão inclui um `parentTransactionId` que aponta para a original. ### Restrições de reversão O Midaz aplica regras rígidas para manter a integridade do ledger. Uma reversão falha nestes casos: #### 1. A transação já tem uma reversão * O Midaz permite apenas uma reversão por transação. * Isso evita múltiplas reversões da mesma transação. #### 2. A transação já é uma reversão * Você não pode reverter uma transação que já é uma reversão. * Isso evita "reversões de reversões". #### 3. O status da transação não é APPROVED * Você pode reverter apenas transações aprovadas. * Você não pode reverter uma transação com status `PENDING`, `CANCELED` ou `NOTED`. #### 4. A transação não pode ser revertida * Isso acontece quando a transação não tem operações válidas para inverter. * Uma cobrança de [dívida de tarifa](https://docs.lerian.studio/pt/products/midaz/fees/fee-debt.md) não pode ser estornada. * Uma transação de bloqueio ou de desbloqueio não pode ser estornada (`0539`). Para desfazer um bloqueio, crie um desbloqueio. Para desfazer um desbloqueio, crie um bloqueio. #### 5. Uma rota de operação na transação não é bidirecional * Toda operação que carrega um `routeId` deve referenciar uma Rota de Operação cujo `operationType` seja `bidirectional`. * Uma rota `source` ou `destination` não pode ser revertida: o Midaz retorna o erro `0150` (Route Not Bidirectional). * Planeje isso ao projetar rotas. Veja [Rotas Contábeis](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md). #### 6. O registro de dívida de tarifa não está completo * O Midaz recusa o estorno de uma transação que abriu uma dívida de tarifa enquanto o registro dessa dívida não está completo. * O Midaz retorna o erro `0529` (HTTP 409) e não movimenta nada. Tente novamente mais tarde. > [!CAUTION] > > Ele não reverte operações ON\_HOLD ou RELEASE. ### Casos de uso A reversão de transações ajuda em vários cenários operacionais: #### 1. Reversão de pagamento incorreto Um cliente pagou BRL 500 ao fornecedor errado. * Reverta a transação. * Os fundos voltam para a conta do cliente. * O cliente pode iniciar um novo pagamento ao fornecedor correto. #### 2. Cancelamento de compra Uma loja processou uma venda de BRL 1.000, mas o cliente cancela a compra. * Reverta a transação de venda. * Os fundos voltam para a conta do cliente. #### 3. Correção de erro operacional Um operador criou uma transação com o valor errado. * Reverta a transação incorreta. * Crie uma nova transação com o valor correto. #### 4. Devolução de produto Um cliente comprou e pagou BRL 200, mas devolveu o produto. * Reverta a transação de pagamento. * O cliente recebe uma devolução. #### 5. Compensação de falha de integração Uma transação é aprovada, mas falha em um sistema externo. * Reverta para desfazer a operação contábil. * Os saldos voltam ao estado anterior. ## Bloqueio e desbloqueio de fundos *** Alguns cenários exigem que você sinalize fundos como **bloqueados** (uma retenção de compliance, uma ordem judicial, uma investigação de fraude) e depois os **libere**. O Midaz oferece suporte a isso com dois endpoints dedicados. Esses endpoints criam transações cujas operações são do tipo `BLOCK` e `UNBLOCK`. Essas transações aceitam o mesmo corpo do endpoint [Criar uma transação usando JSON](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md), com duas diferenças importantes: * **Sempre lançadas imediatamente.** O Midaz ignora o campo `pending` no corpo da requisição e o substitui por `false`. Transações de bloqueio e desbloqueio nunca são em duas fases. Elas vão direto para `APPROVED`. * **As operações são do tipo `BLOCK` ou `UNBLOCK`.** Essa classificação as distingue no ledger e nas consultas de operações. Você pode auditar movimentações de fundos bloqueados sem consultar os metadados. * **Sem uso de overdraft.** Um bloqueio nunca usa overdraft. Um bloqueio maior que o valor disponível retorna `0018`, mesmo quando o saldo permite overdraft. Um desbloqueio paga primeiro o overdraft em aberto e registra esse pagamento como uma operação `OVERDRAFT`. O Midaz é agnóstico quanto ao motivo de negócio para bloquear ou desbloquear fundos. Registre o motivo no campo `metadata`. > [!NOTE] > > Uma transação de Bloqueio registra uma **movimentação no ledger** com operações do tipo `BLOCK`. Isso difere dos controles no nível do saldo em [Saldos](https://docs.lerian.studio/pt/products/midaz/balances.md): flags de permissão (`allowSending` / `allowReceiving`) e saldos de garantia. Esses controles restringem a movimentação, mas não registram nenhuma transação. Use um saldo de garantia para uma restrição operacional permanente. Use uma transação de Bloqueio quando precisar de um lançamento auditável no ledger. * Use o endpoint [Criar uma transação de bloqueio](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-block.md) para bloquear fundos. * Use o endpoint [Criar uma transação de desbloqueio](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-unblock.md) para liberar fundos bloqueados anteriormente. ## Gerenciando transações *** Você pode gerenciar suas Transações pela API ou pelo Lerian Console. ### Via API * [Criar uma transação usando JSON](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md): envie uma transação diretamente usando um payload JSON. * [Confirmar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/commit-transaction.md): finalize uma transação reservada. * [Cancelar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/cancel-transaction.md): libere fundos reservados sem executar a transação. * [Reverter uma transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/revert-transaction.md): crie uma transação de reversão para desfazer uma transação aprovada. * [Criar uma transação de entrada](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-inflow.md): registre fundos recebidos de fontes externas no Ledger. * [Criar uma transação de saída](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-outflow.md): mova fundos de contas internas para o mundo externo. * [Criar uma transação de bloqueio](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-block.md): sinalize fundos como bloqueados com operações do tipo `BLOCK`. * [Criar uma transação de desbloqueio](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-unblock.md): libere fundos bloqueados anteriormente com operações do tipo `UNBLOCK`. * [Listar transações](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-all-transactions.md): veja todas as Transações do seu workspace. * [Recuperar uma transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-transaction.md): obtenha os detalhes de uma Transação específica. * [Atualizar uma transação](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-transaction.md): edite os metadados de uma Transação existente. * [Criar uma anotação de transação](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-annotation.md): registre uma transação sem impacto financeiro no ledger. ### Via Lerian Console Você pode visualizar e criar Transações pelo Lerian Console. Saiba mais no guia [Gerenciando Transações](https://docs.lerian.studio/pt/products/midaz/console/managing-transactions). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.