Montar um ledger e lançar a primeira transação (API)

Da organização e do ledger até uma transação lançada e seus saldos, pela API do Midaz.

Crie a estrutura do ledger no Midaz, lance a primeira transação e leia o resultado.

​

Participantes

---

• Sua instituição. O seu sistema. Ele chama a API do Midaz.
• Midaz. O ledger. Ele guarda as organizações, os ledgers, os ativos, as contas, os saldos e as transações.

​

Antes de começar

---

• O seu sistema tem um token que pode criar organizações, ledgers, ativos, contas e transações no Midaz.
• Escolha o código do ativo, por exemplo BRL, e o alias de cada conta, por exemplo @customer-1.

​

Diagrama

---

​

Passo a passo pela API

---

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Midaz	Chamada de API	POST /v2/organizations	Crie a organização com seu legalName e seu legalDocument. O Midaz responde 201 com o id da organização.
2	Sua instituição	Midaz	Chamada de API	POST /v2/organizations/{organization_id}/ledgers	Crie o ledger com um name. O Midaz responde 201 com o id do ledger.
3	Sua instituição	Midaz	Chamada de API	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets	Crie o ativo com seu name, seu type e seu code.
4	Midaz	Midaz	Etapa interna		O Midaz cria a conta externa @external/<code> do ativo quando ela ainda não existe.
5	Sua instituição	Midaz	Chamada de API	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts	Crie a conta com seu assetCode, seu type e seu alias. As transações encontram a conta pelo alias.
6	Midaz	Midaz	Etapa interna		O Midaz cria o saldo default da conta na mesma chamada.
7	Sua instituição	Midaz	Chamada de API	POST /v2/transactions/direct	Lance a transação com seu asset, seu amount, seus debits e seus credits. Cada perna indica o alias da conta, seu organizationId, seu ledgerId e seu amount. Envie o header X-Idempotency.
8	Midaz	Midaz	Etapa interna		O Midaz debita cada saldo de origem e credita cada saldo de destino. Todos os saldos mudam, ou nenhum deles muda.
9	Midaz	Sua instituição	Resposta da API		O Midaz responde 201 com a transação e suas operações. O status nesta resposta é CREATED.
10	Sua instituição	Midaz	Chamada de API	GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/{alias}/balances	Leia os saldos da conta.
11	Midaz	Sua instituição	Resposta da API		O Midaz devolve cada saldo da conta com seus valores available e onHold.

​

Regras

---

• Um débito é a conta de onde o dinheiro sai. Um crédito é a conta para onde o dinheiro entra. Os débitos e os créditos somam, cada um, o amount da transação.
• Para trazer valor para o ledger, debite a conta externa @external/<code> e credite a sua conta. Para enviar valor para fora, debite a sua conta e credite @external/<code>.
• Quando o modo do Tracer no ledger é enforce, o Midaz recusa a transação antes de mover qualquer saldo se o Tracer não a permitir.

​

Como saber que terminou

---

Leia a transação com GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}. O status dela é APPROVED. Os saldos das contas de origem e de destino mostram os novos valores.

​

O que pode dar errado

---

Situação	O que você vê	O que fazer
O ativo da conta não existe no ledger	404 com 0034	Crie o ativo e depois crie a conta.
Os débitos ou os créditos não somam o valor	422 com 0073	Corrija os valores e envie a transação de novo. O Midaz não moveu nada.
Um saldo de origem não cobre o seu débito	422 com 0018	Adicione fundos à origem ou lance um valor menor. O Midaz não moveu nada.
Você reutiliza uma chave de idempotência em outra requisição	409 com 0084	Use uma chave nova para cada transação nova.
Você envia a mesma requisição de novo antes de o Midaz guardar o resultado da primeira	409 com 0084	Mantenha a chave: a primeira requisição ainda pode lançar a transação. Envie a mesma requisição de novo mais tarde com a mesma chave X-Idempotency.
A resposta da transação não chega	Nenhuma resposta, ou um timeout	Não suponha que a transação falhou. Dentro do tempo do header X-TTL (300 segundos por padrão), envie a mesma requisição com a mesma chave X-Idempotency. Um 201 com X-Idempotency-Replayed: true devolve a primeira transação. Um 409 com 0084 significa que o Midaz ainda não tem o resultado guardado da primeira requisição: envie-a de novo mais tarde com a mesma chave. Depois desse tempo, leia as operações da conta de origem antes de enviar a transação de novo.

​

Relacionados

---

• Reservar um valor e depois confirmar ou cancelar
• Estornar uma transação
• Cobrar uma tarifa em uma transação
• Cadastrar um titular e abrir uma conta
• Lista de erros do Midaz