> ## 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 Transações de partida dobrada no Midaz — múltiplos Saldos, débitos, créditos e rastreabilidade total entre Contas.
Uma **Transação** no Midaz representa um evento financeiro completo, frequentemente envolvendo múltiplas contas e saldos. No coração do Midaz está um **poderoso sistema de contabilidade por partidas dobradas** que garante que cada movimentação financeira seja precisa, confiável e balanceada.
Com o recurso de **múltiplos saldos**, cada operação pode especificar não apenas a conta, mas também a **chave de saldo** a ser utilizada. Isso possibilita cenários avançados onde fundos são debitados ou creditados em diferentes saldos lógicos da mesma conta (ex.: crédito, operacional, garantia).
Se nenhum `balanceKey` for fornecido, a transação usa automaticamente o **saldo padrão.**
## Contabilidade por partidas dobradas
***
O sistema de partidas dobradas opera com um princípio simples, mas transformador: para cada transação, existem dois lançamentos correspondentes, um débito e um crédito. Esse framework garante que todas as atividades financeiras sejam registradas de forma holística, fornecendo uma visão completa e balanceada das suas contas.
Cada transação impacta duas contas, mantendo o equilíbrio no ecossistema financeiro:
* **Débitos** refletem o valor recebido ou recursos consumidos.
* **Créditos** indicam o valor fornecido ou recursos entregues.
O Midaz garante que cada débito e crédito seja automaticamente rastreado e balanceado, otimizando seus processos financeiros.
### Exemplo
Considere este exemplo: você realiza uma transação para transferir R\$1.000 de uma conta para outra. Esse processo terá 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.
No Midaz, esses lançamentos são capturados automaticamente, garantindo precisão e alinhamento com sua estratégia financeira. O design intuitivo da nossa plataforma permite que você visualize e analise essas movimentações sem esforço, promovendo uma cultura de autonomia financeira.
## Transações N:N (Muitos-para-Muitos)
***
Diferente dos sistemas financeiros tradicionais que limitam transações a relacionamentos um-para-um ou um-para-muitos, o Midaz permite transações N:N, possibilitando múltiplas contas de origem e destino dentro de uma única transação.
### Exemplos
* **Pagamento em marketplace**: múltiplos vendedores (várias origens) são pagos a partir de uma única conta escrow, e cada vendedor paga uma taxa da plataforma.
* **Peer-to-peer com taxas**: uma transação debita o pagador e credita tanto o beneficiário quanto uma conta de taxas.
O Midaz processa esses casos como uma única transação atômica, creditando e debitando todas as partes de uma só vez.
## Atomicidade e integridade
***
Transações são operações atômicas; **ou todas as operações constituintes são bem-sucedidas, ou nenhuma é**. Isso garante que eventos financeiros parciais não ocorram.
Se qualquer parte de uma transação falhar na validação (por exemplo, fundos insuficientes em uma conta), toda a transação não será aplicada, preservando a integridade do ledger.
## Origem da transação
***
Transações no Midaz podem ser iniciadas a partir de uma ou múltiplas origens.
A soma dos valores na `source` deve sempre ser igual ao valor especificado logo após o `send` e igual à soma dos valores no `distribute`.
### Origem única
Em uma transação de origem única, o valor especificado é retirado diretamente de uma conta de origem e, opcionalmente, de um saldo específico.
#### Exemplo
Neste exemplo (*Figura 1*):
* BRL 30,00 é retirado de `@account1` (saldo `credit`).
* 100% é enviado 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": [
{
"account": "@account1",
"balanceKey": "credit", // optional
"amount": {
"asset": "BRL",
"value": "30.00"
}
}
]
},
"distribute": {
"to": [
{
"account": "@destinationAccount1",
"balanceKey": "operational", // optional
"share": {
"percentage": 100
}
}
]
}
}
}
```
```go DSL Example theme={null}
(transaction v1
(description "single source transaction")
(send BRL 3000
(source
(from @account1 credit :amount BRL 3000)
)
(distribute
(to @destinationAccount1 operational :share 100)
)
)
)
```
### Múltiplas origens
Em uma transação com múltiplas origens, os fundos são retirados de múltiplas contas e/ou saldos.
#### Exemplo
Neste exemplo (*Figura 2*):
* BRL 30,00 será enviado para a conta de destino (`@destinationAccount1`).
* BRL 15,00 de `@account1` (saldo `default`).
* BRL 15,00 de `@account2` (saldo `investment`).
* A conta de destino receberá 100% do valor enviado.
**Exemplos de código**
```json JSON Example theme={null}
{
"description": "multi-source transaction",
"send": {
"asset": "BRL",
"value": "30.00",
"source": {
"from": [
{
"account": "@account1",
"balanceKey": "default",
"amount": {
"asset": "BRL",
"value": "15.00"
}
},
{
"account": "@account2",
"balanceKey": "investment",
"amount": {
"asset": "BRL",
"value": "15.00"
}
}
]
},
"distribute": {
"to": [
{
"account": "@destinationAccount1",
"share": {
"percentage": 100
}
}
]
}
}
}
```
```go DSL Example theme={null}
(transaction v1
(description "multi-source transaction")
(send BRL 3000
(source
(from @account1 credit :amount BRL 1500)
(from @account2 investment :amount BRL 1500)
)
(distribute
(to @destinationAccount1 :share 100)
)
)
)
```
## Destino da transação
***
Similar às origens, os destinos podem ser únicos ou múltiplos.
### Destino único
Em uma transação de destino único, o valor é enviado para apenas uma conta de destino.
#### Exemplo
Neste exemplo (*Figura 3*):
* BRL 30,00 é retirado de uma conta externa (`@external|BRL`).
* 100% é enviado para a conta de destino (`@destinationAccount1`).
**Exemplos de código**
```json JSON Example theme={null}
{
"description":"single destination transaction",
"send":{
"asset":"BRL",
"value":"3000",
"source":{
"from":[
{
"account":"@external|BRL",
"amount":{
"asset":"BRL",
"value":"3000"
}
}
]
},
"distribute":{
"to":[
{
"account":"@destinationAccount1",
"share":{
"percentage":100
}
}
]
}
}
}
```
```go DSL Example theme={null}
(transaction v1
(description "single destination transaction")
(send BRL 3000
(source
(from @external/BRL :amount BRL 3000)
)
(distribute
(to @destinationAccount1 :share 100)
)
)
)
```
### Múltiplos destinos
Em transações com múltiplos destinos, o valor da transação é dividido entre múltiplas contas de destino. Os valores podem ser distribuídos por percentuais, valores fixos ou saldo remanescente.
#### Exemplo
Neste exemplo (*Figura 4*):
* BRL 100 é retirado 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 remanescente vai para a conta 5 (`@account5`).
**Exemplo de código**
```json JSON Example theme={null}
{
"description":"multi-destination transaction",
"send":{
"asset":"BRL",
"value":"10000",
"source":{
"from":[
{
"account":"@account1",
"amount":{
"asset":"BRL",
"value":"10000"
}
}
]
},
"distribute":{
"to":[
{
"account":"@account2",
"share":{
"percentage":38
}
},
{
"account":"@account3",
"share":{
"percentage":50
}
},
{
"account":"@account4",
"amount":{
"asset":"BRL",
"value":"200"
}
},
{
"account":"@account5",
"remaining":"remaining"
}
]
}
}
}
```
```go DSL Example theme={null}
(transaction v1
(description "multi-destination transaction")
(send BRL 10000
(source
(from @account1 :amount BRL 10000)
)
(distribute
(to @account2 :share 38)
(to @account3 :share 50)
(to @account4 :amount BRL 200)
(to @account5 :remaining)
)
)
)
```
## Múltiplas origens e múltiplos destinos
***
Essas transações complexas envolvem múltiplas origens e múltiplos destinos. Isso é útil para cenários como uma campanha de financiamento coletivo, onde as contribuições são reunidas e distribuídas entre múltiplos beneficiários.
#### Exemplo
Neste exemplo (*Figura 5*):
* BRL 4.000,00 serão doados, e o valor será retirado de quatro contas diferentes.
* 25% será retirado da conta 1 (`@account1`).
* 25% será retirado da conta 2 (`@account2`).
* 40% será retirado da conta 3 (`@account3`)
* 10% será retirado da conta 4 (`@account4`).
* As doações serão distribuídas para quatro contas de doação separadas, e cada uma receberá 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":[
{
"account":"@account1",
"share":{
"percentage":25
}
},
{
"account":"@account2",
"share":{
"percentage":25
}
},
{
"account":"@account3",
"share":{
"percentage":40
}
},
{
"account":"@account4",
"share":{
"percentage":10
}
}
]
},
"distribute":{
"to":[
{
"account":"@donation1",
"share":{
"percentage":25
}
},
{
"account":"@donation2",
"share":{
"percentage":25
}
},
{
"account":"@donation3",
"share":{
"percentage":25
}
},
{
"account":"@donation4",
"share":{
"percentage":25
}
}
]
}
}
}
```
```go DSL Example theme={null}
(transaction v1
(description "multi-source and multi-destination transaction")
(send BRL 400000|2
(source
(from @account1 :share 25)
(from @account2 :share 25)
(from @account3 :share 40)
(from @account4 :share 10)
)
(distribute
(to @donation1 :share 25)
(to @donation2 :share 25)
(to @donation3 :share 25)
(to @donation4 :share 25)
)
)
)
```
## Status da transação
***
Toda transação no Midaz tem um status que reflete sua etapa atual no ciclo de vida. Entender esses status é essencial para projetar fluxos de transação, configurar consumidores de eventos e interpretar os dados do ledger.
| Status | O que significa | Afeta saldos? | Como é criado |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `CREATED` | Uma transação de reversão foi iniciada e está sendo processada. Esse é um status transitório que progride automaticamente para `APPROVED` assim que a reversão é concluída. | Sim | [Reverter uma Transação](/pt/reference/midaz/revert-a-transaction) |
| `APPROVED` | A transação foi concluída com sucesso. Os fundos foram movidos entre as contas. | Sim | Transação direta (sem 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 estão reservados em `on_hold` mas ainda não foram transferidos. | Sim (reserva) | [Criar uma Transação](/pt/reference/midaz/create-a-transaction-using-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/midaz/cancel-a-pending-transaction) |
| `NOTED` | Uma transação de anotação registrada no ledger sem afetar os saldos. As operações preservam a estrutura de partida dobrada, mas todos os campos de saldo ficam zerados. | Não | [Criar uma Anotação de Transação](/pt/reference/midaz/create-a-transaction-annotation) |
O status `NOTED` é particularmente útil para importar transações legadas, registrar trilhas de auditoria e registrar eventos de conformidade — qualquer cenário 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 através desses status:
* **Fluxo padrão:** → `APPROVED` (etapa única)
* **Fluxo em duas fases:** → `PENDING` → `APPROVED` (commit) ou `CANCELED` (cancelamento)
* **Fluxo de reversão:** → `CREATED` → `APPROVED` (automático)
* **Fluxo de anotação:** → `NOTED` (terminal, sem transições)
`NOTED` e `CANCELED` são status terminais — uma vez que uma transação atinge qualquer um desses estados, ela não pode mais transicionar.
## Fluxo da transação
***
Quando uma transação é iniciada, o Midaz valida:
* As contas envolvidas.
* Os saldos especificados (`balanceKey`, ou `default` se não fornecido).
* Permissões (`allowSending`, `allowReceiving`).
* Fundos disponíveis suficientes no saldo selecionado.
Se essa condição for atendida e a transação **não** estiver marcada como pendente (fluxo de Transação em Duas Fases), o valor especificado é transferido **imediatamente** da conta de origem para a conta de destino, usando o saldo disponível.
Esse processo é síncrono, e em caso de sucesso, o status da transação será `APPROVED`.
Os usuários devem **apenas** iniciar esse tipo de transação se pretendem confirmá-la no ledger imediatamente.
Para transações que requerem validação ou aprovação antes da execução, você pode usar a flag `pending` para criar uma **Transação em Duas Fases**.
## Transação em Duas Fases
***
Nesse cenário, a transação é criada com status `PENDING`. Em vez de mover fundos imediatamente, o Midaz reserva o valor especificado no saldo correto (`balanceKey`, ou `default` se não fornecido).
* Os fundos reservados são movidos de `available` para `on_hold`.
* Nenhuma operação (débitos ou créditos) é registrada no ledger ainda.
* Você deve explicitamente fazer `commit` para executar a transferência, ou `cancel` para liberar os fundos.
O recurso de Transação em Duas Fases desempenha um papel fundamental no [Flowker](/pt/flowker/what-is-flowker), permitindo que você reserve fundos no início de um fluxo de trabalho e realize validações depois, com execução garantida se aprovado.
Na *Figura 6*, você pode encontrar um exemplo de transação em duas fases usando 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/midaz/create-a-transaction-using-json) com `"pending": true`.
O Midaz valida as contas, os saldos especificados (`balanceKey`), permissões (`allowSending`, `allowReceiving`) e fundos disponíveis. Se válido:
* Os fundos são reservados no saldo correto.
* O status da transação é definido como `PENDING`.
* Os metadados são armazenados, mas nenhum débito/crédito é registrado ainda.
#### 2. Confirmar ou cancelar a transação pendente
* **Confirmar**: Finaliza a transação. Os fundos são movidos de on\_hold para o saldo de destino, e as operações de débito/crédito são registradas.
* Use o endpoint [Confirmar uma Transação Pendente](/pt/reference/midaz/commit-a-pending-transaction).
* Status: `APPROVED`.
* **Cancelar**: Libera os fundos reservados de volta para available no mesmo saldo.
* Use o endpoint [Cancelar uma Transação Pendente](/pt/reference/midaz/cancel-a-pending-transaction).
* Status: `CANCELED`.
## Transações Passadas
***
O Midaz também suporta transações passadas, permitindo que instituições importem eventos financeiros legados preservando a precisão histórica.
* Use o campo opcional `createdAt` para definir a data original da transação.
* Transações com impacto financeiro recalculam o estado histórico dos saldos como se processadas naquela data.
* Transações criadas via [Criar uma Anotação de Transação](/pt/reference/midaz/create-a-transaction-annotation) validam a estrutura, mas **não** impactam saldos. Elas são úteis para auditorias, conformidade e importações onde os saldos devem permanecer inalterados.
### Exemplo
```json theme={null}
{
"description": "past transaction example",
"createdAt": "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"
}
}
]
}
}
}
```
Ao importar dados legados, envie todas as transações passadas antes de iniciar as operações em tempo real. Isso garante que os saldos sejam recalculados de forma consistente em todo o ledger.
## Transações sem impacto financeiro
***
O Midaz suporta a criação de transações que são registradas no ledger, mas não afetam os saldos das contas. Essas transações garantem integridade estrutural enquanto mantêm os saldos inalterados.
Esse recurso é útil quando você precisa:
* Importar **transações legadas** sem alterar saldos.
* Registrar **eventos de auditoria ou conformidade**.
* Adicionar **operações de negócio** que devem ser rastreadas no ledger, mas não requerem movimentação de fundos.
### Como funciona?
Quando uma transação é criada sem impacto financeiro:
* Os campos `balance` e `balanceAfter` são armazenados como 0 para preservar a validação de partidas dobradas.
* O campo `balanceAffected` (booleano) foi introduzido em cada operação:
* true → a operação afeta o saldo da conta.
* false → a operação é registrada no ledger sem impactar saldos.
Mesmo quando nenhum saldo é atualizado, o Midaz aplica as regras de partidas dobradas. Isso garante consistência em todas as transações no ledger.
#### Exemplo
```json theme={null}
{
"description": "annotation example",
"createdAt": "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/midaz/create-a-transaction-annotation) — Registre uma transação sem impacto financeiro no ledger.
## Publicação de eventos em tempo real
***
Quer acompanhar o status das suas transações conforme elas acontecem? O Midaz suporta publicação de eventos em tempo real via RabbitMQ.
Uma vez habilitado, cada transação gera um evento — `APPROVED`, `PENDING`, `CANCELED`, `CREATED` ou `NOTED` — que sistemas externos podem assinar usando roteamento baseado em tópicos.
Para mais informações sobre como publicar e consumir eventos de transação, confira a página do [Publicador de eventos](/pt/midaz/event-publisher).
## Entradas, saídas e contas externas
***
O Midaz usa um sistema de ledger por partidas dobradas no qual todo valor que entra ou sai do sistema deve passar por uma conta especial: a **Conta Externa**. Essa conta — representada como `@external/{{assetCode}}` — atua como a ponte entre o Midaz e o mundo financeiro externo (bancos, PSPs, trilhos de pagamento, etc.).
### Por que isso importa?
Quando o ledger é inicializado, todas as contas — incluindo `@external` — começam com saldo zero. Para refletir saldos do mundo real (ex.: fundos institucionais mantidos externamente), você deve **iniciar uma transação que injeta fundos nas contas do Midaz debitando a conta externa**.
Essa é a única forma de trazer fundos para dentro do Midaz.
### Entradas – Adicionando valor ao Ledger
Para creditar uma conta interna de fora do ledger:
* **Origem**: `@external/{{assetCode}}` (ex.: `@external/BRL`).
* **Destino**: Uma ou mais contas internas (ex.: `@organization.main`).
**Exemplo: Primeiro depósito no Ledger**
Sua instituição possui R\$10.000 em um banco do mundo real e quer trazer 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 mostrará um saldo negativo, o que é esperado e representa o valor total que sua organização trouxe para o ledger.
### Saídas – Movendo valor para fora do Ledger
Para simular valor saindo 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. Na vida real, seu sistema (via SPI ou outras integrações) transferirá os fundos para o destinatário pretendido.
### Comportamento e regras de saldo
* `@external/{{assetCode}}` pode ter saldo **zero ou negativo**, mas nunca **positivo**.
* Seu saldo é sempre o **inverso** do saldo combinado de todas as contas do Midaz que mantêm aquele ativo.
* Cada entrada aumenta a liquidez interna e reduz o saldo da conta externa (ou seja, simula um depósito).
* Cada saída faz o inverso.
Todas as movimentações de valor entre o mundo externo e o ledger do Midaz devem passar pela conta externa.
Nada entra ou sai do sistema sem uma transação formal, garantindo total rastreabilidade, integridade de saldos e conformidade com os princípios de partidas dobradas.
## Definindo uma data personalizada para a transação
***
O campo `transactionDate` permite especificar uma data personalizada para a transação, independente de quando ela é enviada para a API.
* **Opcional.** Se omitido, 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`
* Somente data: `2026-01-15`
* **Restrição:** Datas futuras **não são permitidas**. Enviar uma data futura retorna o erro `0121`.
* **Restrição:** Não pode ser usado em transações `PENDING`. Usar `transactionDate` com `"pending": true` retorna o erro `0122`.
### Casos de uso
* Registrar transações que ocorreram no passado (ex.: correções do mesmo dia)
* Importar dados financeiros históricos para um novo ledger
* Reconciliação com sistemas externos que utilizam 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.
Este conceito é chamado de **Rotas Contábeis** (Accounting Routes) no Lerian Console e na documentação do produto. O recurso e os endpoints da API mantêm o nome `transactionRoute` / Rotas de Transação; ambos se referem à mesma rota em nível de transação.
Enquanto a API de Transações lida com a execução de eventos financeiros (débitos e créditos entre contas), as Rotas de Transação definem templates para **como** esses eventos devem ser estruturados e validados, garantindo consistência e integridade.
Pense nisso como a camada de validação que garante que as transações de negócio sigam **padrões predefinidos** e **mantenham a estrutura financeira adequada**.
Por exemplo, uma transação de **taxa**, **depósito** ou **pagamento** pode exigir diferentes tipos de conta, regras de validação e estruturas. Em vez de lidar com a validação separadamente para cada transação, você configura regras predefinidas que dizem ao Midaz: "*Quando o usuário enviar esse tipo de transação, valide-a contra esses requisitos de conta e padrões de estrutura.*"
Cada Rota de Transação combina múltiplas **Rotas de Operação**, que definem os componentes individuais de uma transação, especificando requisitos de conta, direções (origem/destino) e regras de validação para cada "perna" do evento financeiro.
O campo `route` nas entradas `FromTo` está depreciado — use `routeId` no lugar. O campo `routeId` aceita um UUID que referencia uma Rota de Transação criada via API de Rotas de Transação. O campo `route` é mantido por compatibilidade retroativa, mas será removido em uma versão futura.
### Por que isso importa?
Ao usar **Rotas de Transação**, você:
* Garante estrutura consistente de transações em toda a sua aplicação.
* Torna seu ledger mais fácil de manter, previsível e confiável.
* Valida eventos financeiros contra padrões predefinidos.
* Permite a configuração de templates de transação sem alterações de código.
* Mantém a integridade dos dados através de validação estruturada.
## Iniciando uma transação
***
Ao criar transações via API, sempre implemente **idempotência** para evitar processamento duplicado. O Midaz oferece suporte integrado de idempotência através do header `X-Idempotency`, e você deve validar o header de resposta `X-Idempotency-Replayed` para distinguir transações novas de replays em cache. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes.
Existem duas formas principais de iniciar uma transação:
### Usando DSL
Este recurso está descontinuado e será removido na próxima versão.
**Atualize seus fluxos de trabalho o mais rápido possível para evitar erros ou indisponibilidade.**
Uma Domain-Specific Language (DSL) simplifica a interação do usuário focando em conceitos específicos do domínio, permitindo que não desenvolvedores realizem tarefas complexas sem habilidades técnicas. DSLs reduzem código boilerplate e incorporam restrições em sua sintaxe, aplicando regras de negócio e minimizando erros. No entanto, seus padrões predefinidos podem limitar a flexibilidade, tornando mais difícil criar parsers customizados ou adaptar-se a novos requisitos.
A **DSL de Transações** no Midaz, chamada **Gold**, simplifica o processamento de transações com uma sintaxe contábil intuitiva. Ela armazena informações de transação em arquivos `.gold`, permitindo que equipes de negócio definam transações facilmente e promovendo a colaboração entre fluxos de trabalho técnicos e de negócio.
Para usar a DSL, siga estes passos:
Crie o arquivo `.gold` de acordo com a estrutura da [DSL de Transações](/pt/midaz/transactions-dsl).
Envie o arquivo usando o endpoint [Criar uma Transação usando DSL](/pt/reference/midaz/create-a-transaction-using-dsl).
Quer se aprofundar na estrutura da DSL? Confira a página da [DSL de Transações](/pt/midaz/transactions-dsl) para mais detalhes.
### Usando endpoint JSON
Endpoints JSON fornecem um padrão flexível e amigável para desenvolvedores para intercâmbio de dados, permitindo controle preciso sobre estruturas de requisição adaptadas para fluxos de trabalho customizados e casos de uso específicos. Sua ampla compatibilidade com diversas linguagens de programação facilita a integração e a depuração.
No entanto, essa flexibilidade pode resultar em verbosidade e erros do usuário, já que os desenvolvedores precisam lidar com a validação manualmente. Para não desenvolvedores, a complexidade do JSON pode apresentar desafios, tornando-o menos intuitivo do que uma Domain-Specific Language (DSL) para tarefas do dia a dia.
* Para criar uma transação usando JSON, use o endpoint [Criar uma Transação usando JSON](/pt/reference/midaz/create-a-transaction-using-json).
Se você precisa reservar fundos **antes** de completar a transferência, defina o campo `pending` como `true` (fluxo de Transação em Duas Fases).
## Revertendo uma transação
***
O Midaz suporta reversão de transações, permitindo que você desfaça transações aprovadas criando uma transação espelho que inverte os débitos e créditos originais. Esse mecanismo mantém trilhas de auditoria completas enquanto efetivamente 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.
### Como funciona?
Quando você reverte uma transação, o Midaz automaticamente:
1. **Inverte as operações**:
* Operações de CREDIT se tornam operações de origem (`from`).
* Operações de DEBIT se tornam operações de destino (`to`).
2. **Cria uma nova transação** com:
* Mesmo valor e código de ativo.
* Mesma descrição e metadados.
* Operações invertidas (destinatários se tornam remetentes, remetentes se tornam destinatários).
* Status inicial: `CREATED` (não `PENDING`) → depois avança para `APPROVED`.
* `parentTransactionID` referenciando a transação original.
3. **Processa a reversão** pelo fluxo padrão de transação, incluindo validação, atualização de saldos e registro no histórico.
### Exemplo
Considere este cenário:
**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**:
* Conta A retorna ao seu saldo anterior (recebe de volta os -100).
* Conta B retorna ao seu saldo anterior (perde os +100).
* Ambas as transações permanecem no histórico do ledger para fins de auditoria.
* A transação de reversão inclui `parentTransactionID` apontando para a original.
### Restrições de reversão
O Midaz aplica regras rígidas para manter a integridade do ledger. As reversões falharão nos seguintes casos:
#### 1. A transação já possui uma reversão
* Apenas uma reversão por transação é permitida.
* Previne múltiplas reversões da mesma transação.
#### 2. A transação já é uma reversão
* Não é possível reverter uma transação que já é uma reversão.
* Previne a criação de "reversões de reversões".
#### 3. O status da transação não é APPROVED
* Apenas transações aprovadas podem ser revertidas.
* Transações com status `PENDING`, `CREATED` ou `CANCELED` não podem ser revertidas.
#### 4. A transação não pode ser revertida
* Ocorre quando a transação não possui operações válidas para inverter.
* Por exemplo, transações sem operações padrão de CREDIT/DEBIT.
Apenas operações de CREDIT e DEBIT são consideradas para reversão. Operações como ON\_HOLD e RELEASE não são incluídas no processo de reversão.
### Casos de uso
A reversão de transações é essencial para vários cenários operacionais:
#### 1. Reversão de pagamento incorreto
Um cliente pagou BRL 500 para o fornecedor errado.
* Reverta a transação.
* Os fundos retornam à conta do cliente.
* O cliente pode iniciar um novo pagamento para o 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 da venda.
* Os fundos retornam à 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 o reembolso.
#### 5. Compensação de falha de integração
Uma transação foi aprovada, mas falhou em um sistema externo.
* Reverta para desfazer a operação contábil.
* Os saldos retornam ao estado anterior.
## Bloqueando e desbloqueando fundos
***
Alguns cenários exigem marcar fundos como **bloqueados** — uma retenção por conformidade, uma ordem judicial, uma investigação de fraude — e depois **liberá-los**. O Midaz oferece suporte a isso com dois endpoints dedicados que criam transações cujas operações resultantes são do tipo `BLOCK` e `UNBLOCK`.
Essas transações aceitam o **mesmo corpo** que o endpoint [Criar uma Transação usando JSON](/pt/reference/midaz/create-a-transaction-using-json), com duas diferenças principais:
* **Sempre postadas imediatamente.** O campo `pending` do corpo da requisição é ignorado (sobrescrito para `false`): transações de bloqueio e desbloqueio nunca são em duas fases e vão direto para `APPROVED`.
* **As operações são do tipo `BLOCK` / `UNBLOCK`.** Essa classificação é o que as distingue no ledger e nas consultas de operações, de modo que as movimentações de fundos bloqueados são auditáveis sem inspecionar o `metadata`.
O Midaz é **agnóstico quanto ao motivo de negócio** para bloquear ou desbloquear fundos — registre-o no campo `metadata`.
Uma transação de bloqueio registra uma **movimentação no ledger** com operações do tipo `BLOCK`. Isso é diferente dos controles em nível de saldo descritos em [Saldos](/pt/midaz/balances) — as `permission flags` (`allowSending`/`allowReceiving`) e os saldos de garantia — que restringem a movimentação sem registrar uma transação. Use um saldo de garantia para uma restrição operacional permanente; use uma transação de bloqueio quando precisar de uma entrada auditável no ledger.
* Use o endpoint [Criar uma Transação de Bloqueio](/pt/reference/midaz/create-a-block-transaction) para bloquear fundos.
* Use o endpoint [Criar uma Transação de Desbloqueio](/pt/reference/midaz/create-an-unblock-transaction) para liberar fundos previamente bloqueados.
## Gerenciando transações
***
Você pode gerenciar suas Transações via API ou através do Lerian Console.
### Via API
* [Criar uma Transação usando DSL](/pt/reference/midaz/create-a-transaction-using-dsl) **(descontinuado)** — Envie um arquivo de transação usando a DSL do Midaz.
* [Criar uma Transação usando JSON](/pt/reference/midaz/create-a-transaction-using-json) — Envie uma transação diretamente usando um payload JSON.
* [Confirmar uma transação pendente](/pt/reference/midaz/commit-a-pending-transaction) — Finalize uma transação reservada.
* [Cancelar uma transação pendente](/pt/reference/midaz/cancel-a-pending-transaction) — Libere fundos reservados sem executar.
* [Reverter uma Transação](/pt/reference/midaz/revert-a-transaction) — Crie uma transação de reversão para desfazer uma transação aprovada.
* [Criar uma Transação de Entrada](/pt/reference/midaz/create-an-inflow-transaction) — Registre fundos recebidos de fontes externas no Ledger.
* [Criar uma Transação de Saída](/pt/reference/midaz/create-an-outflow-transaction) — Mova fundos de contas internas para o mundo externo.
* [Criar uma Transação de Bloqueio](/pt/reference/midaz/create-a-block-transaction) — Marque fundos como bloqueados com operações do tipo `BLOCK`.
* [Criar uma Transação de Desbloqueio](/pt/reference/midaz/create-an-unblock-transaction) — Libere fundos previamente bloqueados com operações do tipo `UNBLOCK`.
* [Listar Transações](/pt/reference/midaz/list-transactions) — Visualize todas as Transações no seu workspace.
* [Recuperar uma Transação](/pt/reference/midaz/retrieve-a-transaction) — Obtenha detalhes de uma Transação específica.
* [Atualizar uma Transação](/pt/reference/midaz/update-a-transaction) — Edite os metadados de uma Transação existente.
* [Criar uma Anotação de Transação](/pt/reference/midaz/create-a-transaction-annotation) — Registre uma transação sem impacto financeiro no ledger.
### Via Lerian Console
Todas as ações de gerenciamento de Transações, incluindo visualização, criação e cancelamento, podem ser feitas através do Lerian Console.
Saiba mais no guia de [Gerenciamento de Transações](/pt/midaz/console/managing-transactions).