Skip to main content
Um workflow estruturado mantém cada transação clara, rastreável e auditável desde o início. Siga os passos abaixo em ordem. Eles configuram sua Organização, Ledgers, Ativos, Tipos de Conta e Contas.

​
Configurando e gerenciando Ledgers

Ao fazer onboarding no Midaz, siga estes passos:
Workflow para configurar e gerenciar ledgers ao fazer onboarding no Midaz

Figura 1. Workflow para configurar e gerenciar ledgers.

​
Passo 1: Configurar a Organização

Sua organização no Midaz representa seu banco ou entidade de negócio. Se você ainda não a criou, configure-a no Console ou na API. Confirme que os dados principais estão corretos, como a razão social e os identificadores.

​
Passo 2: Criar os Ledgers

Crie um Ledger sob sua organização para armazenar os registros financeiros. A maioria das configurações começa com um ledger principal para todas as operações voltadas ao cliente (por exemplo, “Main Banking Ledger”). No início ele não contém contas. Ele serve como a camada base para toda a atividade financeira.

​
Passo 3: Definir os tipos de Ativo

Registre os ativos que seu ledger aceita. Podem incluir moedas (por exemplo, BRL, USD), pontos ou tokens de cripto. Você usa esses ativos em toda a configuração de contas e transações. Você pode adicionar mais ativos conforme seu portfólio de produtos cresce.

​
Passo 4: Criar Tipos de Conta

Para aplicar regras de classificação de contas, defina seus Tipos de Conta. São categorias, por exemplo user_wallet, treasury ou revenue. Você as referencia depois na criação de contas ou na validação de transações.
Quando você habilita a validação de Tipo de Conta, cada nova conta deve usar um Tipo de Conta registrado. Por padrão, os Tipos de Conta são opcionais. Isso mantém a classificação consistente em todo o seu ledger.
Cada Tipo de Conta tem um keyValue. O keyValue deve ser único e alfanumérico, com traços e sublinhados permitidos. Você usa esses identificadores em fluxos de validação e em rotas de transação.

​
Passo 5: Configurar Rotas Contábeis

Use Rotas de Operação e a Rota de Transação (o recurso transactionRoute na API) para definir e aplicar a validação das suas transações.
  • Primeiro, crie as Rotas de Operação. Cada Rota de Operação valida uma perna da transação. Por exemplo, o débito deve vir de uma conta do tipo user_wallet, e o crédito deve ir para o alias @external/BRL.
  • Depois, crie a Rota de Transação. Ela combina as rotas de operação individuais em um fluxo completo. Um exemplo é uma transação de saque com validações específicas de débito e crédito.
Depois de configurar o roteamento e habilitar a validação no ledger, todas as transações devem corresponder à estrutura de roteamento definida. O Midaz rejeita qualquer transação que não corresponda.O campo route no payload da transação deve incluir o ID da Rota de Transação que você criou.

​
Passo 6: Gerenciar seus Ledgers

Mantenha seus ledgers organizados e escaláveis com as seguintes boas práticas:
  • Use o sistema RBAC do Midaz para atribuir permissões e controlar o acesso por ledger.
  • Planeje ledgers separados quando necessário, por exemplo “Testing”, “Internal” ou “Multi-entity”. Documente sua propriedade.
  • Revise e concilie os dados do ledger regularmente, especialmente ao integrar com sistemas externos de liquidação.
  • O Midaz aplica a lógica de partidas dobradas, então cada movimento é totalmente rastreável. Não altere saldos manualmente.

​
Configurando Contas, Portfólios e Segmentos

Esta seção mostra como estruturar os dados de clientes e os direitos de produto no Midaz.
Workflow para configurar contas, portfólios e segmentos para estruturar dados de clientes e direitos de produto no Midaz

Figura 2. Workflow para configurar Contas, Portfólios e Segmentos.

​
Passo 1: Criar um Portfólio de cliente

Crie um Portfólio para cada novo cliente. Os portfólios funcionam como os contêineres lógicos das contas. Vincule cada portfólio ao seu CRM ou sistema interno por meio de metadados (por exemplo, um Entity ID).

​
Passo 2: Configurar as Contas do cliente

Cada produto financeiro ou ativo que o cliente possui se torna uma Conta separada sob o portfólio dele.
  • Uma conta corrente em BRL e uma conta poupança em USD são contas separadas.
  • Se você habilitar os Tipos de Conta, o campo type deve corresponder a um dos valores pré-registrados.
  • Use aliases de conta para simplificar as operações posteriores.
Os Tipos de Conta padronizam a categorização de contas em todo o seu ecossistema. Eles melhoram o roteamento, os relatórios e as integrações.

​
Passo 3: Aplicar segmentação

Use Segmentos para categorizar portfólios ou contas (por exemplo, standard, vip, enterprise). Essas tags acionam lógica dinâmica com base na segmentação de clientes, como isenções de tarifa ou juros escalonados.

​
Passo 4: Criar subcontas (opcional)

Para organizações ou casos especiais, você pode configurar subcontas. Use convenções de nomenclatura claras para manter a rastreabilidade (por exemplo, “Acme USD - Payroll”).

​
Passo 5: Definir o saldo inicial

Use a API de Transações para adicionar o saldo de abertura. Isso mantém a rastreabilidade e a conformidade com as partidas dobradas:
  • Debite a fonte de fundos.
  • Credite a nova conta.
  • Não atualize saldos manualmente. O Midaz rastreia cada valor por meio de transações.

​
Passo 6: Verificar e revisar

Antes de executar operações, verifique o seguinte:
  • Confirme que cada conta tem os ativos e tipos corretos.
  • Valide os saldos das contas.
  • Verifique se você aplicou a segmentação.
  • Confirme a configuração na API ou no Console.

​
Passo 7: Gestão contínua de Contas

Gerencie as operações de ciclo de vida pela API ou pelo Console para manter a integridade do sistema:
  • Atualize os detalhes da conta conforme necessário.
  • Feche contas apenas quando o saldo chegar a zero.
  • Reclassifique portfólios/contas se a segmentação mudar.

​
Implementando a gestão de transações por partidas dobradas

O Midaz garante a integridade do ledger por meio da aplicação estrita da lógica de partidas dobradas. Toda transação deve conter pelo menos uma operação de débito e uma de crédito.
Workflow para implementar a gestão de transações por partidas dobradas, em que toda transação carrega pelo menos uma operação de débito e uma de crédito

Figura 3. Workflow para implementar a gestão de transações por partidas dobradas

​
Passo 1: Estruturar a transação

Estruture seu objeto de Transação:
  • Depois de configurar sua Rota de Transação, insira o ID dela no campo route do payload da sua transação.
  • Defina as contas de origem e destino, com os detalhes de ativo e valor.
  • Adicione metadados descritivos para manter a rastreabilidade e a clareza.

​
Passo 2: Escolher seu método de integração

Use a API de Transações para criação programática de transações.

​
Passo 3: Aplicar a validação de partidas dobradas

O Midaz verifica se a soma dos créditos corresponde à soma dos débitos. O Midaz rejeita uma transação que tenha uma divergência ou uma violação estrutural.

​
Passo 4: Implementar idempotência

Use chaves de idempotência para evitar duplicatas causadas por novas tentativas de rede. O Midaz reconhece uma chave repetida e reproduz a resposta original em vez de processar a requisição duas vezes.

​
Passo 5: Rastrear e conciliar transações

Use as ferramentas integradas para:
  • Rastrear transações enviadas e registradas.
  • Auditar metadados e timestamps.
  • Conciliar lotes de transações para conformidade.

​
Passo 6: Enviar correções por estornos

Não edite nem exclua transações. Envie um estorno em vez disso. O Midaz vincula cada estorno à sua transação original para rastreabilidade completa.

​
Passo 7: Otimizar fluxos complexos

Use transações com múltiplas operações para:
  • Processar acúmulos de juros.
  • Executar pagamentos em lote.
  • Lidar com fluxos condicionais com lógica de roteamento.
O Midaz mantém a atomicidade em todas as pernas. Ou a transação inteira é registrada, ou nenhuma é.