> ## 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`).
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. Toda transação tem dois lançamentos: um débito e um crédito. Essa estrutura registra toda a atividade financeira e mantém suas contas balanceadas.
Cada transação afeta duas contas e as mantém em equilíbrio:
* **Débitos** mostram o valor recebido ou os recursos consumidos.
* **Créditos** mostram o valor dado ou os recursos fornecidos.
O Midaz rastreia e balanceia automaticamente todo débito e crédito.
### 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.
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`)
**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.
**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`).
**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 saldo 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`).
**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.
**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` | Uma transação de reversão foi iniciada e está sendo processada. Este é um status transitório que avança automaticamente para `APPROVED` quando a reversão é concluída. | Sim | [Reverter uma transação](/pt/reference/products/midaz/v2/revert-transaction) |
| `APPROVED` | A transação foi concluída com sucesso. Os fundos foram movidos entre as contas. | Sim | Transação direta (sem a flag `pending`), commit de uma transação `PENDING`, ou progressão automática a partir de `CREATED` |
| `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](/pt/reference/products/midaz/v1/create-transaction-json) 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](/pt/reference/products/midaz/v2/cancel-transaction) |
| `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](/pt/reference/products/midaz/v1/create-transaction-annotation) |
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 reversão:** → `CREATED` → `APPROVED` (automático)
* **Fluxo de anotação:** → `NOTED` (terminal, sem transições)
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.
Se a validação passa e a transação **não** é pendente (fluxo de Transação em Duas Fases), 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.
Esse processo é síncrono. Em caso de sucesso, o status da transação passa a `APPROVED`.
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 Midaz move os fundos reservados de `available` para `on_hold`.
* O Midaz registra **uma** operação, do tipo `ON_HOLD`, no saldo de origem. O saldo de destino permanece intocado: nenhum débito ou crédito é lançado ainda.
* Você deve fazer `commit` explicitamente para executar a transferência, ou `cancel` para liberar os fundos.
O recurso de Transação em Duas Fases oferece suporte ao [Flowker](/pt/products/flowker/what-is-flowker). Você reserva os fundos no início de um workflow e roda as validações depois. O Midaz garante a execução se o workflow aprovar a transação.
Na *Figura 6*, você pode ver um exemplo de uma transação em duas fases com 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](/pt/reference/products/midaz/v1/create-transaction-json) 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 e lança a operação `ON_HOLD` na origem. Nenhum débito ou crédito chega ao destino ainda.
#### 2. Confirmar ou cancelar a transação pendente
* **Commit**: finaliza a transação. Os fundos passam de `on_hold` para o saldo de destino, e o Midaz adiciona as operações `DEBIT` e `CREDIT`. Uma transação em duas fases com commit carrega três operações no total (`ON_HOLD`, `DEBIT`, `CREDIT`).
* Use o endpoint [Confirmar uma transação pendente](/pt/reference/products/midaz/v2/commit-transaction).
* Status: `APPROVED`.
* **Cancel**: libera os fundos reservados de volta para `available` no mesmo saldo.
* Use o endpoint [Cancelar uma transação pendente](/pt/reference/products/midaz/v2/cancel-transaction).
* Status: `CANCELED`.
## 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.
* Transações com impacto financeiro recalculam o estado histórico do saldo como se o Midaz as tivesse processado naquela data.
* Transações criadas pelo endpoint [Criar uma anotação de transação](/pt/reference/products/midaz/v1/create-transaction-annotation) 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"
}
}
]
}
}
}
```
Envie todas as transações passadas antes de iniciar as operações em produção. Assim, o Midaz recalcula os saldos de forma consistente em todo o ledger.
## 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.
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"
},
"balanceAffected": false
}
]
},
"distribute": {
"to": [
{
"accountAlias": "@account1_BRL",
"amount": {
"asset": "BRL",
"value": "1000"
},
"balanceAffected": false
}
]
}
}
}
```
#### Endpoint relacionado
* [Criar uma anotação de transação](/pt/reference/products/midaz/v1/create-transaction-annotation): registre uma transação sem impacto financeiro no ledger.
## Publicação de eventos em tempo real
***
O Midaz oferece suporte à publicação de eventos em tempo real por meio do RabbitMQ. Você pode acompanhar o status das suas transações à medida que elas acontecem.
Depois de habilitar esse recurso, cada transação gera um evento: `APPROVED`, `PENDING`, `CANCELED`, `CREATED` ou `NOTED`. Sistemas externos se inscrevem nesses eventos por meio de roteamento baseado em tópicos.
Para saber mais sobre como publicar e consumir eventos de transação, veja a página [Publicador de eventos](/pt/products/midaz/event-publisher).
## 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 funciona como a ponte entre o Midaz e o mundo financeiro externo (bancos, PSPs, trilhos de pagamento e assim por diante).
### Por que isso importa?
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. A conta externa agora mostra um saldo negativo. Isso é esperado: 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
* `@external/{{assetCode}}` pode ter um saldo **zero ou negativo**, mas nunca **positivo**.
* O saldo dela é sempre o **inverso** do saldo combinado de todas as contas do Midaz que mantêm esse ativo.
* Toda entrada aumenta a liquidez interna e reduz o saldo da conta externa (ou seja, simula um depósito).
* Toda saída faz o inverso.
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.
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.
Pense nisso como 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. Você não trata a validação separadamente para cada transação. Em vez disso, 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 ou destino) e as regras de validação para cada "perna" do evento financeiro.
Não use o campo `route` nas entradas `FromTo`. 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 mantém o campo `route` por compatibilidade retroativa, mas vai remover o campo em uma versão futura.
### Por que isso importa?
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
***
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](/pt/reference/retries-idempotency) para mais detalhes.
Use a API de transação JSON para iniciar uma transação.
### Formato da requisição JSON na v2
Cada lado da transação usa uma representação: `from` ou `sources`, e independentemente `to` ou `destinations`. Não envie as duas representações para o mesmo lado, e não envie um `null` explícito para um campo escalar não utilizado.
Cada item de `sources` ou `destinations` exige `account` e exatamente uma expressão de valor: `amount` ou `share`. A expressão `remaining` não é aceita na v2. Cada array aceita no máximo 500 itens. `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.
### Usando o endpoint JSON
* Para criar uma transação com JSON, use o endpoint [Criar uma transação usando JSON](/pt/reference/products/midaz/v1/create-transaction-json).
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.
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.
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 mesmos metadados.
* Operações invertidas (quem recebe passa a enviar, quem envia passa a receber).
* Status inicial: `CREATED` (não `PENDING`) → depois avança para `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`, `CREATED` ou `CANCELED`.
#### 4. A transação não pode ser revertida
* Isso acontece quando a transação não tem operações válidas para inverter.
* Por exemplo, uma transação sem operações padrão de CREDIT ou DEBIT.
#### 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](/pt/products/midaz/transaction-routing-entities).
O Midaz reverte as operações CREDIT e DEBIT. Ele não reverte operações ON\_HOLD ou RELEASE.
### Casos de uso
A reversão de transações ajuda em diversos 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](/pt/reference/products/midaz/v1/create-transaction-json), 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.
O Midaz é **agnóstico quanto ao motivo de negócio** para bloquear ou desbloquear fundos. Registre o motivo no campo `metadata`.
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](/pt/products/midaz/balances): 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](/pt/reference/products/midaz/v1/create-transaction-block) para bloquear fundos.
* Use o endpoint [Criar uma transação de desbloqueio](/pt/reference/products/midaz/v1/create-transaction-unblock) 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](/pt/reference/products/midaz/v1/create-transaction-json): envie uma transação diretamente usando um payload JSON.
* [Confirmar uma transação pendente](/pt/reference/products/midaz/v2/commit-transaction): finalize uma transação reservada.
* [Cancelar uma transação pendente](/pt/reference/products/midaz/v2/cancel-transaction): libere fundos reservados sem executar a transação.
* [Reverter uma transação](/pt/reference/products/midaz/v2/revert-transaction): crie uma transação de reversão para desfazer uma transação aprovada.
* [Criar uma transação de entrada](/pt/reference/products/midaz/v1/create-transaction-inflow): registre fundos recebidos de fontes externas no Ledger.
* [Criar uma transação de saída](/pt/reference/products/midaz/v1/create-transaction-outflow): mova fundos de contas internas para o mundo externo.
* [Criar uma transação de bloqueio](/pt/reference/products/midaz/v1/create-transaction-block): sinalize fundos como bloqueados com operações do tipo `BLOCK`.
* [Criar uma transação de desbloqueio](/pt/reference/products/midaz/v1/create-transaction-unblock): libere fundos bloqueados anteriormente com operações do tipo `UNBLOCK`.
* [Listar transações](/pt/reference/products/midaz/v2/get-all-transactions): veja todas as Transações do seu workspace.
* [Recuperar uma transação](/pt/reference/products/midaz/v2/get-transaction): obtenha os detalhes de uma Transação específica.
* [Atualizar uma transação](/pt/reference/products/midaz/v2/update-transaction): edite os metadados de uma Transação existente.
* [Criar uma anotação de transação](/pt/reference/products/midaz/v1/create-transaction-annotation): registre uma transação sem impacto financeiro no ledger.
### Via Lerian Console
Você pode fazer todas as ações de gerenciamento de Transações (visualizar, criar e cancelar) pelo Lerian Console.
Saiba mais no guia [Gerenciando Transações](/pt/products/midaz/console/managing-transactions).