Pular para o conteúdo principal

​
APIs Lerian

Esta seção responde perguntas frequentes sobre as APIs da Lerian, abordando comportamento geral, configuração e boas práticas em todos os serviços.
Sim. Por padrão, o número máximo de registros por página é 100. Esse limite garante um desempenho consistente e ajuda a gerenciar o volume de dados transferidos em cada requisição. No entanto, você pode aumentar esse valor configurando a variável de ambiente MAX_PAGINATION_LIMIT na configuração do seu deployment. Após a atualização e reinicialização da aplicação, a API aceitará tamanhos de página maiores.Importante: Aumentar o tamanho da página pode afetar os tempos de resposta, especialmente em ambientes que lidam com grandes volumes de dados. Sempre teste exaustivamente em staging antes de aplicar mudanças em produção.

​
Midaz

Aqui, você encontrará as respostas para perguntas comuns sobre Organizations, Ledgers, Accounts, Transactions e mais no Midaz.

​
Organizations

Não, cada Organization opera de forma independente e não se comunica com as outras.
Não, cada licença está vinculada a uma Organization específica. Se você precisa de suporte para múltiplas Organizations, deve adquirir licenças separadas para cada uma. A mesma regra se aplica aos Plugins.
Sim, uma Organization pode ter mais de um Plugin associado a ela.
Sim, uma Organization pode gerenciar múltiplos Ledgers.
Embora você possa criar uma Parent Organization e uma Child Organization, cada Organization mantém seu próprio Ledger, operando de forma independente. Como transações não podem mover valor diretamente entre ledgers, você precisa orquestrar a transferência com os seguintes passos:
1
Inicie uma transação no ledger de origem, transferindo o valor da conta original (source) para a external account do asset (distribute). Isso remove o valor do ledger original.
2
Crie uma segunda transação no ledger de destino, onde o source agora é a external account do asset, e o valor é alocado para a conta receptora (distribute).
Essa abordagem garante transferências de valor entre ledgers de diferentes organizations de forma transparente e controlada.

​
Ledgers

Não, Ledgers não se comunicam diretamente. Transferências entre Ledgers requerem orquestração.
Você deve orquestrar o processo e transferir o valor para uma External Account. Normalmente, isso envolve dois passos:
1
Ledger A -> External Account.
2
External Account -> Ledger B.
Não, um único Ledger pode suportar múltiplos Plugins. Por exemplo, um Ledger pode lidar com os Plugins de Exchange e Pix simultaneamente.

​
Assets

Não, cada Asset é vinculado a uma única Account. No entanto, cada Asset também será vinculado a uma External Account que é criada automaticamente quando o Asset é criado.
O Midaz foi construído para flexibilidade, suportando uma ampla variedade de Assets:
  • currency: Moedas fiduciárias tradicionais como BRL, USD e EUR.
  • crypto: Ativos digitais como BTC, ETH e outras criptomoedas.
  • commodities: Bens tangíveis como ouro, soja e petróleo.
  • others: Assets personalizados, incluindo pontos de fidelidade e títulos tokenizados.

​
Portfólios

Um Portfolio agrupa contas que pertencem à mesma entidade (CPF/CNPJ). Por exemplo, se um único CPF tem dois valores de segment_id diferentes, ele também terá dois valores de account_id correspondentes. Para simplificar a recuperação, um Portfolio é criado para esse CPF, vinculando ambas as contas em uma única estrutura. Isso garante acesso e gerenciamento mais fáceis das contas relacionadas.

​
Accounts

Não, cada Account é associada a um único Asset, e essa associação não pode ser alterada.
Uma External Account é usada para receber fundos de fora do Ledger, efetivamente trazendo dinheiro para dentro do sistema.
O Midaz configura automaticamente uma External Account quando você cria um Asset, garantindo suporte contínuo para todas as transações que entram e saem do Ledger.
Não. Cada conta (account_id) pode ser vinculada a apenas um Segment (segment_id).
Não. Você pode criar quantas Accounts sua configuração precisar. Sem limites, sem restrições — apenas a flexibilidade para escalar do seu jeito.
Para entender o processo de recarga de saldo, vamos considerar os seguintes pontos:
  1. No Ledger do Midaz, quando um Asset (por exemplo, BRL) é criado, uma External Account associada a esse asset também é gerada.
  2. Essa External Account atua como um gateway entre o ecossistema Lerian e o mundo externo. Em outras palavras, ela serve como um espelho dos saldos mantidos pela instituição em sua conta PI, conta de liquidação, conta de reserva, ou até mesmo uma conta bancária tradicional ou conta de pagamento que detém os fundos reais.
  3. Para depositar fundos em uma conta de usuário com um Asset específico vindo de fora do Ledger do Midaz, o processo é o seguinte:
    • Inicie uma transação onde a origem é a External Account e o destino é a(s) conta(s) alvo.
    • Como resultado, a External Account será debitada pelo valor transferido (ficando negativa), enquanto a(s) conta(s) de destino serão creditadas de acordo, com base nos valores fornecidos no payload da transação.

​
Transactions

Uma Transaction deve ter pelo menos duas Operations. Por exemplo, transferir R$ 100 da Account A para a Account B consiste em:
  • Operation 1: Debitar R$ 100 da Account A.
  • Operation 2: Creditar R$ 100 na Account B.
A Lerian oferece aos clientes múltiplas opções para acessar comprovantes de transação:
  1. Via APIs – Recupere dados de transações através das nossas APIs, permitindo que você gere um comprovante visual no formato de sua escolha.
  2. Usando o Reporter – Extraia dados de transações e crie comprovantes visuais personalizados.
  3. Através do Console – Acesse informações de transações diretamente pelo Console da Lerian.

​
Entities

Atualmente, a Entity (entity_id) está aberta para IDs externos, sem validação imposta pelo Midaz. Isso significa que você pode usar os IDs que já existem no seu banco de dados, integrando-os de forma transparente ao seu sistema.

​
Idempotência

O Midaz trata a requisição como nova toda vez. Isso significa que retentativas podem resultar em operações duplicadas.
Não. As chaves devem ter escopo limitado a uma única operação e endpoint.
Apenas o TTL da primeira requisição é utilizado. Alterá-lo posteriormente não tem efeito.
Sim. O Midaz reproduz a resposta completa, incluindo headers e body, para requisições concluídas.
A janela padrão é de 300 segundos (5 minutos), mas você pode personalizá-la até o limite permitido por endpoint.

​
Contabilidade no Midaz

R: O Midaz permite que você espelhe o Plano de Contas oficial da sua organização diretamente na plataforma, configurando duas funcionalidades centrais:
  • Account Types – Crie as categorias lógicas do seu plano (por exemplo, Ativos, Passivos, Receitas, Despesas) e atribua-as às contas no seu ledger. Quando a funcionalidade Account Types está habilitada, o campo type na API de Accounts se torna obrigatório e deve corresponder a um dos valores que você registrou.
  • Transaction Routing – Use Operation Routes para validar cada “perna” de uma transação (por exemplo, o débito deve vir de uma conta do tipo user_wallet) e Transaction Routes para definir padrões completos de transação que se alinham com sua lógica contábil.
Combinando Account Types e Transaction Routing, você pode aplicar suas regras contábeis no nível do ledger — garantindo que cada transação seja validada e categorizada de acordo com seu Plano de Contas, sem codificar regras na sua lógica de negócios.

​
Plugins

Plugins estendem as capacidades do Midaz, permitindo integração e orquestração de processos de forma fluida. Projetados para remover complexidade, eles fornecem abstrações poderosas que permitem que você se concentre no seu modelo de negócios, garantindo eficiência e escalabilidade. Explore as perguntas mais comuns sobre como os plugins funcionam, seu deployment e as opções disponíveis para aprimorar suas operações.
Plugins são tecnologias integradas ao ledger do Midaz, projetadas para simplificar a integração e orquestração de processos. Eles fornecem abstrações que permitem aos clientes focar no seu modelo de negócios sem precisar construir ou gerenciar lógica essencial do sistema que está fora do seu domínio.
Não. Os plugins são projetados para operar exclusivamente com o Midaz. Eles fornecem abstrações específicas e orquestram transações com base na estrutura do ledger, garantindo integração precisa e eficiente.
Uma vez contratados, os plugins são fornecidos e instalados dentro da infraestrutura do cliente (modelo on-premise), junto com sua instância do Midaz. As aplicações se conectam de acordo com a funcionalidade específica de cada plugin.
A Lerian oferece dois tipos de plugins, categorizados por sua origem:
  • Plugins Nativos: Desenvolvidos e totalmente integrados ao ledger do Midaz pela Lerian, esses plugins garantem suporte completo e integração fluida com a plataforma.
  • Plugins do Marketplace: Criados por parceiros da Lerian para atender nichos específicos de mercado, esses plugins estão disponíveis no marketplace. A Lerian facilita sua integração ao Midaz, mas sua oferta e suporte são gerenciados diretamente pelos respectivos parceiros.