FAQ

APIs da Lerian

Esta seção responde a perguntas comuns sobre as APIs da Lerian.

Existe um número máximo de registros por página nas listagens da API? Posso aumentar esse limite?

Sim. No Midaz, o máximo padrão é 100 registros por página. Esse limite mantém o desempenho consistente e controla o volume de dados em cada requisição. Para aumentá-lo, defina a variável de ambiente MAX_PAGINATION_LIMIT na configuração do seu deploy. A maioria das listagens aceita páginas maiores depois que você reinicia a aplicação.Importante: uma página maior pode deixar o tempo de resposta mais lento, principalmente com bases de dados grandes. Teste em staging antes de mudar a produção.

Tenants na Lerian Cloud

Estas perguntas cobrem isolamento de dados e escopo de tenant na Lerian Cloud.

Meus dados ficam isolados dos de outras instituições no SaaS?

Sim. Os seus dados ficam isolados de todos os outros tenants, com credenciais próprias. A plataforma resolve o seu tenant a partir do JWT em cada requisição. Não há como acessar os dados de outro tenant pela API.

Preciso enviar um ID de tenant nas minhas requisições de API?

Não. O token de acesso JWT que você recebe durante a autenticação carrega o contexto do seu tenant. A plataforma o resolve automaticamente. Você não precisa incluir um identificador de tenant em headers ou corpos de requisição.

Posso ter múltiplas Organizações em um único tenant?

Sim. Um tenant pode conter múltiplas Organizações. Cada Organização tem seus próprios Ledgers, contas e transações. A plataforma limita o escopo de todas elas ao seu tenant automaticamente.

A API é diferente entre os deploys SaaS e self-hosted?

Não. A superfície da API é idêntica: mesmos endpoints, mesmos payloads, mesmas respostas. O SaaS exige autenticação em cada requisição, e seu token limita o escopo de todas as operações ao seu tenant.

Midaz

Estas perguntas cobrem Organizações, Ledgers, Contas, Transações e outros temas do Midaz.

Organizações

Organizações diferentes se comunicam entre si?

Cada Organização opera de forma independente. Uma transação cross-ledger pode mover valor entre Ledgers de Organizações diferentes no mesmo tenant.

Posso usar uma única licença em várias Organizações?

Veja Licença da Lerian para saber como cada licença se aplica às Organizações.

Uma Organização pode ter vários Plugins?

Sim. Uma Organização pode ter mais de um Plugin.

Uma Organização pode ter vários Ledgers?

Sim. Uma Organização pode gerenciar vários Ledgers.

Posso criar transações entre uma Organização Pai e uma Organização Filha?

Você pode criar uma Organização Pai e uma Organização Filha. Cada Organização mantém seu próprio Ledger e opera de forma independente. Para mover valor entre os Ledgers delas, envie uma transação cross-ledger. Todo Ledger participante deve definir settings.crossLedger.enabled como true, e nenhum pode ter accounting.validateRoutes definido como true. Você também pode orquestrar a transferência com estes passos:

No ledger de origem, crie uma transação da conta original (source) para a conta externa do ativo (distribute). Isso remove o valor do ledger de origem.

No ledger de destino, crie uma segunda transação. O source agora é a conta externa do ativo, e o destino é a conta que recebe (distribute).

Esse padrão move valor entre ledgers em Organizações diferentes.

Ledgers

Ledgers diferentes se comunicam entre si?

Os Ledgers mantêm livros separados. Uma transação cross-ledger move valor entre Ledgers que definem settings.crossLedger.enabled como true.

Como posso fazer transações entre Ledgers?

Envie uma requisição POST /v2/transactions/direct ou POST /v2/transactions/hold com pernas em cada Ledger. Todo Ledger participante deve definir settings.crossLedger.enabled como true. O Midaz cria uma transação balanceada por Ledger. Você também pode mover o valor por meio de uma Conta Externa em dois passos:

Ledger A -> Conta Externa.

Conta Externa -> Ledger B.

Preciso de um Ledger separado para cada Plugin?

Não. Um único Ledger pode aceitar vários Plugins. Por exemplo, um Ledger pode lidar com os Plugins Exchange e Pix ao mesmo tempo.

Ativos

Um Ativo pode ser vinculado a várias Contas?

Sim. Muitas Contas podem usar o mesmo Ativo. Cada Ativo também vincula a uma Conta Externa. O Midaz cria essa Conta Externa automaticamente quando você cria o Ativo.

Quais tipos de Ativos posso usar?

O Midaz aceita vários tipos de Ativo:

currency: moedas fiduciárias tradicionais, como BRL, USD e EUR.
fiat: um tipo alternativo para moedas fiduciárias; assim como currency, o código do Ativo deve seguir a ISO 4217.
crypto: ativos digitais, como BTC, ETH e outras criptomoedas.
commodity: bens tangíveis, como ouro, soja e petróleo.
others: Ativos personalizados, incluindo pontos de fidelidade e títulos tokenizados.

Portfólios

Como funciona um Portfólio?

Um Portfólio agrupa contas que pertencem à mesma entidade (CPF/CNPJ). Por exemplo, um CPF com dois valores diferentes de segmentId tem duas contas correspondentes. Você cria um Portfólio para esse CPF para vincular as duas contas em uma única estrutura.

Contas

Uma Conta pode ser associada a vários Ativos?

Não. Cada Conta vincula a um único Ativo. Você não pode alterar esse vínculo.

O que é uma Conta Externa?

Uma Conta Externa recebe fundos de fora do Ledger. Ela traz dinheiro para dentro do sistema.

Como posso criar uma Conta Externa?

O Midaz cria uma Conta Externa automaticamente quando você cria um Ativo. Você também pode criar uma: envie type como external com um alias.

Uma Conta pode ser vinculada a vários Segmentos?

Não. Cada conta vincula a apenas um Segmento (segmentId).

Existe um limite para quantas Contas posso criar no Midaz?

Não. Você pode criar quantas Contas precisar. O Midaz não define limite para o número de Contas.

Qual é o processo para adicionar fundos a uma conta ou fazer um cash-in usando dinheiro vindo de fora do ambiente do Ledger (Midaz)?

O processo de recarga de saldo funciona assim:

Quando você cria um Ativo (por exemplo, BRL) no Ledger do Midaz, o Midaz também cria uma Conta Externa para esse Ativo.
Essa Conta Externa espelha os saldos que a instituição mantém fora do Midaz. Esses saldos podem estar em uma conta PI, uma conta de liquidação, uma conta Reservas Bancárias ou uma conta bancária ou de pagamento tradicional.
Para depositar fundos de fora do Ledger do Midaz em uma conta de usuário, siga estes passos:
- Crie uma transação com a Conta Externa como origem e as contas de destino como destino.
- O Midaz debita a Conta Externa pelo valor e credita as contas de destino pelos valores informados no payload da transação.

Transações

Qual é a estrutura mínima de uma Transação?

Uma transferência direta de R$ 100 da Conta A para a Conta B tem duas operações:

Operação 1: debitar R$ 100 da Conta A.
Operação 2: creditar R$ 100 na Conta B.

É possível gerar um comprovante de transferência em PDF com os detalhes de uma transação concluída?

A Lerian oferece às instituições várias formas de acessar comprovantes de transação:

Pelas APIs: recupere os dados da transação pelas APIs e gere um comprovante visual no formato que preferir.
Com o Reporter: extraia os dados da transação e crie comprovantes visuais personalizados.
Pelo Console: acesse os dados da transação diretamente no Console da Lerian.

Entidades

Como posso criar uma Entidade?

O campo entityId aceita IDs externos de até 256 caracteres. O Midaz não valida o formato deles. Você pode usar os IDs que já existem no seu banco de dados e integrá-los ao seu sistema.

Idempotência

Posso reutilizar uma chave de idempotência entre endpoints diferentes?

Não. Limite o escopo de cada chave a uma única operação e endpoint.

O que acontece se eu mudar o TTL em uma nova tentativa?

O Midaz usa apenas o TTL da primeira requisição. Uma mudança posterior não tem efeito.

A resposta reenviada sempre será idêntica?

Sim. Para uma requisição concluída, o Midaz retorna o mesmo resultado armazenado da primeira requisição. Ele também define o header X-Idempotency-Replayed como true.

Qual é o TTL padrão se eu não enviar X-TTL?

O TTL padrão é de 300 segundos (5 minutos). Envie o header X-TTL para definir um valor personalizado em segundos.

Contabilidade no Midaz

Como posso refletir meu próprio Plano de Contas no Midaz?

O Midaz permite espelhar o Plano de Contas oficial da sua organização na plataforma. Você configura dois recursos principais:

Tipos de Conta: crie as categorias lógicas do seu plano de contas, como Ativos, Passivos, Receitas e Despesas. Atribua-as às contas do seu ledger. Quando você habilita a validação de tipo de conta (validateAccountType), o campo type na API de Contas deve corresponder a um valor registrado.
Rotas Contábeis: use Rotas de Operação para validar cada perna de uma transação. Por exemplo, um débito deve vir de uma conta do tipo user_wallet. Use Rotas Contábeis (o recurso transactionRoute na API) para definir padrões completos de transação alinhados à sua lógica contábil.

Os Tipos de Conta e as Rotas Contábeis, juntos, aplicam suas regras contábeis no nível do ledger. O Midaz valida cada transação de acordo com seu Plano de Contas quando você habilita a validação de rotas (validateRoutes). Você não grava as regras diretamente no código da sua lógica de negócio.

Plugins

Os Plugins estendem o Midaz com integração e orquestração de processos. Eles fornecem abstrações para que você possa focar no seu modelo de negócio, e não na lógica de sistemas fora do seu domínio. As perguntas abaixo cobrem como os plugins funcionam, como você faz o deploy deles e quais opções estão disponíveis.

O que são os Plugins?

Plugins são tecnologias que se integram ao ledger do Midaz. Eles simplificam a integração e a orquestração de processos. Eles fornecem abstrações para que as instituições possam focar no seu modelo de negócio. As instituições não constroem nem gerenciam lógica de sistema fora do seu domínio.

Como os plugins são distribuídos?

Depois que você contrata um plugin, a Lerian o fornece. No modelo BYOC, o plugin roda na sua infraestrutura, ao lado da sua instância do Midaz. As aplicações se conectam a cada plugin de acordo com sua função.

Quais opções de plugin a Lerian oferece?

A Lerian oferece dois tipos de plugins, agrupados por origem:

Plugins Nativos: a Lerian desenvolve e integra esses plugins ao ledger do Midaz. A Lerian oferece suporte completo a eles.
Plugins de Marketplace: os parceiros da Lerian criam esses plugins para nichos de mercado específicos. A Lerian ajuda a integrá-los ao Midaz. Os parceiros os fornecem e dão suporte diretamente.

Fees Engine

Estas perguntas cobrem o Fees Engine. O Fees Engine é um recurso licenciado do Midaz que roda dentro do processo unificado do ledger.

Conceitos Gerais

O que é o Fees Engine?

O Fees Engine é parte do Midaz. Ele roda no processo do ledger do Midaz para calcular tarifas de transações financeiras. Configure e faça o deploy dele junto com o Midaz. Saiba mais na visão geral do Fees Engine. Ele funciona em quatro domínios principais:

Fee Packages (/v2/organizations/{organization_id}/ledgers/{ledger_id}/packages): define regras de cobrança por transação (tarifa fixa, percentual ou o que for maior).
Billing Packages (/v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages): define cobranças periódicas com base no volume de transações ou na manutenção de contas.
Planos de tarifas (/v2/organizations/{organization_id}/ledgers/{ledger_id}/account-plans): define tarifas que você atribui a contas, com uma cota gratuita por mês calendário. Veja Planos de tarifas.
Cálculo e estimativa: o Ledger avalia as tarifas durante o fluxo da transação. Use POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates para uma prévia específica de um pacote e POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate para cobrança periódica.

Como o Fees Engine se encaixa no ecossistema da Lerian?

O Fees Engine roda dentro do processo do ledger do Midaz. Quando um Fee Package configurado se aplica, o Midaz incorpora o cálculo da tarifa à transação. Ele usa casos de uso de consulta do ledger em vez de uma conexão HTTP externa com o Midaz.

O que preciso enviar em toda requisição ao Fees Engine?

Os endpoints de Fees têm escopo por organização, definido pelo ID da organização no caminho da URL /v2. A plataforma resolve o contexto do tenant a partir da requisição autenticada; envie o material de autorização exigido pela configuração do seu Access Manager.

Authorization: Bearer ***

Qual banco de dados o Fees Engine usa para armazenamento?

O Fees Engine usa o MongoDB para armazenamento. As exclusões seguem o padrão de soft delete. O Fees Engine não remove os registros fisicamente. Ele os marca com deletedAt. Um registro excluído não aparece nas listagens, mas você ainda pode auditá-lo.

Qual versão do Midaz oferece o módulo Fees integrado?

O Midaz v4 expõe o Fees dentro do Ledger unificado em /v2.

Fee Packages

O que é um Fee Package?

Um Fee Package (Package) é um conjunto de regras de cobrança sob um mesmo feeGroupLabel. Cada package vincula a uma Organização + Ledger e, opcionalmente, a um Segmento. Um package pode conter várias tarifas (objetos Fee), cada uma com sua própria lógica de cálculo. Saiba mais sobre Fee Packages.

Como crio um Fee Package?

Envie um POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages com o corpo a seguir. Veja a referência da API Create Package para todos os detalhes.

{
  "feeGroupLabel": "Digital Account Fees",
  "segmentId": "{segment_id}",
  "minimumAmount": "100.00",
  "maximumAmount": "50000.00",
  "transactionRoute": "{transaction_route_id}",
  "enable": true,
  "waivedAccounts": ["exempt-account-1", "exempt-account-2"],
  "fees": {
    "adminFee": {
      "feeLabel": "Administrative Fee",
      "calculationModel": {
        "applicationRule": "percentual",
        "calculations": [
          { "type": "percentage", "value": "1.50" }
        ]
      },
      "referenceAmount": "originalAmount",
      "priority": 1,
      "isDeductibleFrom": true,
      "creditAccount": "fee-revenue-account"
    }
  }
}

Um package pode ser desativado temporariamente?

Sim. Defina o campo enable como false ao criar ou atualizar o package. O Fees Engine ignora um package desativado durante o cálculo de tarifas, mesmo quando o contexto da transação corresponde ao seu escopo.

Como funciona o escopo do package (minimumAmount / maximumAmount)?

O Fees Engine aplica o package apenas a transações cujo valor está dentro do intervalo [minimumAmount, maximumAmount]. Se o valor da transação estiver fora desse intervalo, o Fees Engine ignora o package.Exemplo: um package com minimumAmount: 100 e maximumAmount: 5000 cobra tarifas apenas em transações entre 100 e 5.000.

Posso filtrar um package por rota de transação?

Sim. Defina o campo transactionRoute com o ID de uma rota de transação. O Fees Engine passa a considerar o package apenas para transações que carregam esse routeId.

O que são waivedAccounts?

São aliases de conta que o package isenta de tarifas. Quando todas as contas de origem de uma transação estão em waivedAccounts, o Fees Engine não aplica as tarifas do package. Uma conta isenta não paga tarifa do package.

"waivedAccounts": ["vip-account", "employee-account"]

Esse package não cobra essas contas.

Os endpoints de listagem têm paginação?

Sim. Os endpoints de listagem (GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages, GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages) aceitam os parâmetros de consulta limit e page para paginação.

GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages?limit=20&page=2

Modelos de Cálculo

Quais modelos de cálculo estão disponíveis?

O campo applicationRule dentro de calculationModel define como o Fees Engine calcula a tarifa. Veja Modelos de Cálculo para todos os detalhes. Há três opções:

Regra	Descrição
`flatFee`	Tarifa de valor fixo
`percentual`	Tarifa percentual com base no valor de referência
`maxBetweenTypes`	Avalia 2 ou mais cálculos; aplica o maior resultado

Como configuro uma tarifa fixa (flatFee)?

Use exatamente 1 cálculo do tipo flat:

"calculationModel": {
  "applicationRule": "flatFee",
  "calculations": [
    { "type": "flat", "value": "5.00" }
  ]
}

Isso cobra um valor fixo de 5,00, independentemente do valor da transação.

Como configuro uma tarifa percentual (percentual)?

Use exatamente 1 cálculo do tipo percentage:

"calculationModel": {
  "applicationRule": "percentual",
  "calculations": [
    { "type": "percentage", "value": "2.50" }
  ]
}

Isso cobra 2,5% do valor de referência da transação.

Como funciona o maxBetweenTypes?

O maxBetweenTypes exige 2 ou mais cálculos. O Fees Engine calcula cada um e aplica o maior resultado.Exemplo: tarifa mínima de 3,00 ou 1% do valor, o que for maior:

"calculationModel": {
  "applicationRule": "maxBetweenTypes",
  "calculations": [
    { "type": "flat", "value": "3.00" },
    { "type": "percentage", "value": "1.00" }
  ]
}

Para uma transação de 200: 1% = 2,00 vs. 3,00 fixo → cobra 3,00. Para uma transação de 500: 1% = 5,00 vs. 3,00 fixo → cobra 5,00.

Posso combinar vários percentuais no maxBetweenTypes?

Sim. Você pode incluir qualquer combinação de flat e percentage. O Fees Engine avalia todos e aplica o maior. flatFee e percentual exigem exatamente 1 cálculo. Apenas o maxBetweenTypes aceita 2 ou mais.

Campos Importantes

O que é referenceAmount e como ele afeta o cálculo?

O referenceAmount define sobre qual valor o Fees Engine calcula a tarifa:

originalAmount: o valor original da transação, antes de qualquer tarifa.
afterFeesAmount: o valor da transação depois que as tarifas de prioridade mais alta se aplicam.

A tarifa com priority: 1 roda primeiro, então ela deve usar originalAmount. Não existem tarifas anteriores para considerar.

O que é isDeductibleFrom e quando devo usá-lo?

Quando isDeductibleFrom: true, o Fees Engine deduz a tarifa do valor que o remetente envia. O destinatário recebe o valor com desconto.Quando false, o Fees Engine cobra a tarifa separadamente. O remetente envia o valor total, e o Fees Engine debita a tarifa à parte.Restrições:

isDeductibleFrom: true exige referenceAmount: originalAmount
Se o tipo for percentage: o valor não pode passar de 100
Se o tipo for flat: o valor não pode passar do minimumAmount do package

Como funciona o campo priority?

O priority define a ordem de execução das tarifas dentro de um package. O Fees Engine executa os valores menores primeiro.

priority: 1 → executada primeiro (deve usar originalAmount)
priority: 2 → executada depois, pode usar afterFeesAmount

Use prioridades para encadear tarifas. Por exemplo, rode uma tarifa administrativa sobre o valor original. Depois, rode uma tarifa de IOF sobre o valor após a tarifa administrativa.

O que é creditAccount?

É o alias da conta do ledger que recebe a receita da tarifa. Cada tarifa pode ter um creditAccount diferente. Isso ajuda quando tarifas diferentes pertencem a centros de custo diferentes.

"creditAccount": "admin-fee-revenue-account"

O que são routeFrom e routeTo dentro de uma tarifa?

Esses campos definem as rotas das pernas contábeis que a cobrança da tarifa gera. Eles são opcionais. Eles permitem rastrear a origem e o destino das movimentações de tarifa no ledger.

Billing Packages

O que são Billing Packages?

Billing Packages são pacotes de cobrança periódica, independentes do cálculo de tarifa por transação. Veja Exemplos de Billing Package para casos de uso. Há dois tipos:

volume: cobra com base no número de transações em um período, com preços em camadas.
maintenance: cobra uma tarifa fixa por conta em um escopo definido.

Quando devo usar o billing por volume?

Use o billing por volume para cobrar clientes pelo número de transações processadas. Esse é um modelo comum para plataformas de pagamento com preços baseados em volume. Você define faixas de preço que se aplicam conforme o volume cresce.

{
  "type": "volume",
  "eventFilter": {
    "transactionRoute": "PIX",
    "status": "approved"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 0, "maxQuantity": 1000, "unitPrice": "0.50" },
    { "minQuantity": 1001, "unitPrice": "0.30" }
  ],
  "assetCode": "BRL",
  "debitAccountAlias": "client-account",
  "creditAccountAlias": "volume-revenue-account"
}

Quando devo usar o billing de manutenção?

Use o billing de manutenção para cobrar uma tarifa periódica fixa por conta. Por exemplo, cobre uma tarifa mensal por conta ativa. Você especifica o escopo (segmentId, portfolioId ou aliases) e o valor da tarifa.

{
  "type": "maintenance",
  "feeAmount": "15.00",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "maintenance-revenue-account",
  "accountTarget": {
    "segmentId": "{segment_id}"
  }
}

O accountTarget deve ter exatamente um dos três campos: segmentId, portfolioId ou aliases (máximo de 100 aliases).

Como funcionam as faixas (tiers) no billing por volume?

As faixas definem o preço unitário por faixa conforme o volume aumenta. As regras são:

Devem ser contíguas: sem lacunas entre as faixas (minQuantity da próxima = maxQuantity da anterior + 1).
Não podem se sobrepor.
Quando há várias faixas, a última deve omitir maxQuantity. Uma faixa única com limite superior é aceita. Uma contagem faturável positiva fora dessa faixa faz a chamada inteira de cálculo falhar.

Exemplo de faixas corretas:

"tiers": [
  { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
  { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.60" },
  { "minQuantity": 2001, "unitPrice": "0.40" }
]

O que é freeQuota?

É uma franquia gratuita. O Fees Engine não cobra um número fixo de transações antes de as faixas se aplicarem. Isso ajuda modelos de precificação com um volume mínimo incluído.Exemplo: freeQuota: 100 significa que o Fees Engine não cobra as primeiras 100 transações do período.Uma tarifa de plano de tarifas tem o próprio freeQuota, contado por conta e mês calendário. Veja Cota gratuita.

O que são discountTiers?

São faixas de desconto para o billing por volume. Elas reduzem o valor cobrado com base em critérios extras. Elas complementam a lógica das tiers principais.

O que é countMode no billing por volume?

Ele define como o Fees Engine conta as transações:

perRoute: conta as transações por rota (por exemplo, total de Pix aprovados).
perAccount: conta as transações por conta individual.

Cálculo e cobrança de tarifas

Como as tarifas de transação são calculadas no Midaz v4?

O Ledger avalia as tarifas no fluxo da transação quando um package correspondente se aplica. Uma conta de origem com um plano de tarifas ativo paga as tarifas do plano dela em vez disso. Use POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates para uma prévia específica de um package.

Quais endpoints do v4 configuram tarifas?

Configure os Fee Packages de transação em /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages e os Billing Packages periódicos em /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages. Configure os planos de tarifas em /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-plans e atribua um a uma conta em /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/account-plan.

Como calculo o billing periódico?

Chame POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate depois de configurar os Billing Packages. Isso processa as regras configuradas para esse Ledger.

Erros Comuns

O que significa o erro 0188 "originalAmount is required when priority is one"?

A tarifa com priority: 1 deve ter referenceAmount: "originalAmount". Ela é a primeira tarifa a rodar, então não existem tarifas anteriores para basear o cálculo.Correção:

{
  "priority": 1,
  "referenceAmount": "originalAmount"
}

Como corrijo o erro 0205 "originalAmount is required when isDeductibleFrom is true"?

Tarifas com isDeductibleFrom: true apenas podem usar referenceAmount: "originalAmount". Atualize o campo:

{
  "isDeductibleFrom": true,
  "referenceAmount": "originalAmount"
}

Por que recebo o erro 0208 "calculation value flat invalid"?

Quando isDeductibleFrom: true e o tipo é flat, o valor da tarifa não pode passar do minimumAmount do package. Isso evita uma tarifa maior do que o valor mínimo da transação.Exemplo: se minimumAmount: 100, a tarifa fixa não pode passar de 100.

Quando ocorre o erro 0207 "calculation value percentage invalid"?

Esse erro ocorre quando isDeductibleFrom: true, o tipo é percentage e o valor é maior que 100. Uma tarifa percentual dedutível de 100% zeraria a transação. Valores acima de 100 são inválidos.

Como corrijo o erro 0218 "tiers have a gap"?

As faixas do billing por volume devem cobrir todos os intervalos sem lacunas. Confira se o minQuantity de cada faixa é exatamente maxQuantity + 1 da faixa anterior.

// ❌ Wrong — gap between 500 and 600
{ "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
{ "minQuantity": 600, "unitPrice": "0.40" }

// ✅ Correct
{ "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
{ "minQuantity": 501, "unitPrice": "0.40" }

Erro 0229: "Exactly one of segmentId, portfolioId, or aliases must be provided"

No billing de manutenção, o campo accountTarget aceita apenas um dos três valores. Não combine campos:

// ❌ Wrong
"accountTarget": {
  "segmentId": "{segment_id}",
  "portfolioId": "{portfolio_id}"
}

// ✅ Correct
"accountTarget": {
  "segmentId": "{segment_id}"
}

Existe um limite de aliases em accountTarget?

Sim. O campo aliases aceita no máximo 100 aliases por Billing Package de manutenção.

Erros 0189 e 0191: flatFee precisa de exatamente 1 cálculo do tipo flat

O applicationRule: "flatFee" aceita exatamente 1 cálculo, e ele deve ser do tipo flat. Não use percentage com flatFee.

// ✅ Correct
"calculationModel": {
  "applicationRule": "flatFee",
  "calculations": [{ "type": "flat", "value": "10.00" }]
}

Erros 0189 e 0190: percentual precisa de exatamente 1 cálculo do tipo percentage

Assim como o flatFee, o applicationRule: "percentual" aceita exatamente 1 cálculo do tipo percentage.

Erro 0201: "applicationRule maxBetweenTypes must have more than 1 calculation"

O maxBetweenTypes exige pelo menos 2 cálculos, porque precisa de valores para comparar.

O que devo verificar quando o package não é aplicado à transação?

Checklist de diagnóstico (veja também Boas Práticas):

enable: o package está ativo (enable: true)?
Ledger: você criou o package no ledger da transação?
minimumAmount / maximumAmount: o valor da transação está dentro do intervalo?
transactionRoute: se o package tem transactionRoute, a transação usa a mesma rota?
segmentId: se o package é escopado a um segmento, a conta pertence a ele?
waivedAccounts: a conta está listada como isenta?

Um registro excluído pode ser recuperado?

O Fees Engine faz soft delete dos registros. Ele os marca com deletedAt e não os remove do banco de dados. A API não tem endpoint de restauração. Entre em contato com a equipe da Lerian se precisar recuperar um registro excluído.

Midaz Core

CRM

Fees

APIs da Lerian

Tenants na Lerian Cloud

Midaz

Organizações

Ledgers

Ativos

Portfólios

Contas

Transações

Entidades

Idempotência

Contabilidade no Midaz

Plugins

Fees Engine

Conceitos Gerais

Fee Packages

Modelos de Cálculo

Campos Importantes

Billing Packages

Cálculo e cobrança de tarifas

Erros Comuns

​APIs da Lerian

​Tenants na Lerian Cloud

​Midaz

​Organizações

​Ledgers

​Ativos

​Portfólios

​Contas

​Transações

​Entidades

​Idempotência

​Contabilidade no Midaz

​Plugins

​Fees Engine

​Conceitos Gerais

​Fee Packages

​Modelos de Cálculo

​Campos Importantes

​Billing Packages

​Cálculo e cobrança de tarifas

​Erros Comuns

APIs da Lerian

Tenants na Lerian Cloud

Midaz

Organizações

Ledgers

Ativos

Portfólios

Contas

Transações

Entidades

Idempotência

Contabilidade no Midaz

Plugins

Fees Engine

Conceitos Gerais

Fee Packages

Modelos de Cálculo

Campos Importantes

Billing Packages

Cálculo e cobrança de tarifas

Erros Comuns