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. 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 API 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.

Multi-tenancy e SaaS

Estas perguntas cobrem isolamento de dados, escopo de tenant e como funciona a multi-tenancy nos deploys da Lerian.

Meus dados ficam isolados dos de outros clientes no SaaS?

Sim. Cada tenant opera em um banco de dados separado. A plataforma resolve seu tenant a partir do JWT em cada requisição e o roteia para seu banco de dados isolado. Não há como acessar os dados de outro tenant pela API. Saiba mais sobre multi-tenancy.

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?

Não. Cada Organização opera de forma independente e não se comunica com as outras.

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

Não. Cada licença vincula a uma Organização. Para operar com várias Organizações, adquira uma licença separada para cada uma. A mesma regra vale para os Plugins.

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. As transações não podem mover valor diretamente entre ledgers. Você orquestra 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?

Não. Ledgers não se comunicam diretamente. Transferências entre Ledgers exigem orquestração.

Como posso fazer transações entre Ledgers?

Você deve orquestrar o processo e mover o valor por meio de uma Conta Externa. Isso envolve 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?

Não. Cada Ativo vincula a uma única Conta. 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.
commodities: 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 segment_id tem dois valores correspondentes de account_id. 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. Essa Conta Externa dá suporte a todas as transações que entram e saem do Ledger.

Uma Conta pode ser vinculada a vários Segmentos?

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

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 (que fica negativo) 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 Transação deve ter pelo menos duas Operações. Por exemplo, uma transferência 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 aos clientes 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?

A Entidade (entity_id) aceita IDs externos. O Midaz não aplica nenhuma validação sobre esse campo. Você pode usar os IDs que já existem no seu banco de dados e integrá-los ao seu sistema.

Idempotência

O que acontece se eu não enviar uma chave de idempotência?

O Midaz trata a requisição como nova toda vez. As novas tentativas podem então criar operações duplicadas.

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 o recurso Tipos de Conta, o campo type na API de Contas se torna obrigatório e 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 e categoriza cada transação de acordo com seu Plano de Contas. 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 os clientes possam focar no seu modelo de negócio. Os clientes não constroem nem gerenciam lógica de sistema fora do seu domínio.

Os plugins podem ser usados sem o Midaz?

Não. Os plugins operam apenas com o Midaz. Eles fornecem abstrações específicas e orquestram transações com base na estrutura do ledger.

Como os plugins são distribuídos?

Depois que você contrata um plugin, a Lerian o fornece e instala na sua infraestrutura (modelo on-premise), 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 três 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.
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. O Midaz v4 não tem um endpoint de nível superior /v2/fees ou /v2/estimates.

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. As versões standalone anteriores do plugin-fees seguem sua própria matriz de compatibilidade legada e não fazem parte do modelo de deploy do v4.

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",
  "ledgerId": "ldg_abc123",
  "segmentId": "seg_xyz456",
  "minimumAmount": "100.00",
  "maximumAmount": "50000.00",
  "transactionRoute": "PIX",
  "enable": true,
  "waivedAccounts": ["exempt-account-1", "exempt-account-2"],
  "fees": {
    "admin_fee": {
      "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.

Se você não definir maximumAmount, o package pode se aplicar sem limite superior. Confira as regras de validação da sua versão.

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

Sim. Defina o campo transactionRoute no package. O Fees Engine passa a considerar o package apenas para transações com essa rota, como "PIX", "TED" ou "BOLETO".

O que são waivedAccounts?

São aliases de conta que o package isenta de tarifas. Se o remetente ou o destinatário de uma transação for uma conta em waivedAccounts, o Fees Engine não aplica as tarifas do package a ela.

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

Esse package não cobra nenhuma transação que venha dessas contas ou vá para elas.

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`	Calcula o valor fixo e o percentual; 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 que combinem flat e percentage. O Fees Engine calcula os dois 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. Observe que 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, e o remetente paga a mais para cobrir a cobrança.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"
}

A última faixa deve ser sem limite (sem maxQuantity). Não pode haver lacunas nem sobreposições entre as faixas.

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": "seg_premium_clients"
  }
}

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.
A última faixa deve ser sem limite (sem maxQuantity).

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.

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. O Midaz v4 não tem um endpoint de nível superior /v2/fees ou /v2/estimates. O endpoint POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates, escopado ao ledger, continua disponível 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.

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 "Priority 1 must use originalAmount"?

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 "isDeductibleFrom requires originalAmount"?

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

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

Por que recebo "Flat fee value cannot exceed minimumAmount"?

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 "Percentage value cannot exceed 100"?

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 "Tiers must be contiguous"?

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" }

O que significa "Last tier must be unbounded"?

A última faixa do billing por volume deve ficar sem limite superior (sem maxQuantity). Isso mantém um preço para transações acima da faixa mais alta definida.

"accountTarget must have exactly one of: segmentId, portfolioId, aliases"

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

// ❌ Wrong
"accountTarget": {
  "segmentId": "seg_abc",
  "portfolioId": "port_xyz"
}

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

Existe um limite de aliases em accountTarget?

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

"flatFee requires exactly 1 calculation of type 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" }]
}

"percentual requires exactly 1 calculation of type percentage"

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

"maxBetweenTypes requires 2 or more calculations"

O maxBetweenTypes exige pelo menos 2 cálculos, porque precisa de valores para comparar. Informe pelo menos um flat e um percentage.

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)?
ledgerId: o package está vinculado ao ledger correto?
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 expõe endpoints de restauração por padrão. Entre em contato com a equipe da Lerian se precisar recuperar um registro excluído. Para a lista completa de códigos de erro, veja a referência de Códigos de Erro.

Midaz Core

CRM

Fees

APIs da Lerian

Multi-tenancy e SaaS

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

​Multi-tenancy e SaaS

​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

Multi-tenancy e SaaS

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