FAQ

APIs Lerian

Esta seção responde perguntas comuns sobre as APIs da Lerian. Ela aborda comportamento geral, configuração e boas práticas em todos os serviços.

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, configure a variável de ambiente MAX_PAGINATION_LIMIT na configuração do seu deployment. A API aceita tamanhos de página maiores depois que você reinicia a aplicação.Importante: Um tamanho de página maior pode deixar os tempos de resposta mais lentos, especialmente com grandes volumes de dados. Teste em staging antes de alterar produção.

Multi-tenancy e SaaS

Estas perguntas abordam o isolamento de dados, o escopo de tenant e como o multi-tenancy funciona nos deployments 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 a direciona para o seu banco de dados isolado. Não há como acessar dados de outro tenant pela API. Saiba mais sobre multi-tenancy.

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

Não. O JWT access token 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 no corpo da requisição.

Posso ter múltiplas Organizations sob um único tenant?

Sim. Um tenant pode conter múltiplas Organizations. Cada Organization tem seus próprios Ledgers, contas e transações. A plataforma escopa todas ao seu tenant automaticamente.

A API é diferente entre SaaS e deployments self-hosted?

Não. A superfície da API é idêntica: mesmos endpoints, mesmos payloads, mesmas respostas. Apenas uma coisa difere. O SaaS exige autenticação em toda requisição, e o seu token escopa todas as operações ao seu tenant.

Midaz

Estas perguntas abordam Organizations, Ledgers, Accounts, Transactions e mais no Midaz.

Organizations

Diferentes Organizations se comunicam entre si?

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

Posso usar uma única licença em múltiplas Organizations?

Não. Cada licença se vincula a uma Organization. Para dar suporte a múltiplas Organizations, adquira uma licença separada para cada uma. A mesma regra se aplica aos Plugins.

Uma Organization pode ter múltiplos Plugins?

Sim. Uma Organization pode ter mais de um Plugin.

Uma Organization pode ter múltiplos Ledgers?

Sim. Uma Organization pode gerenciar múltiplos Ledgers.

Posso criar transações entre uma Parent Organization e uma Child Organization?

Você pode criar uma Parent Organization e uma Child Organization. Cada Organization mantém seu próprio Ledger e opera de forma independente. As transações não podem mover valor diretamente entre ledgers. Orquestre a transferência com estes passos:

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

No ledger de destino, crie uma segunda transação. O source agora é a external account do asset, e o destino é a conta receptora (distribute).

Esse padrão move valor entre ledgers de diferentes Organizations de forma controlada.

Ledgers

Diferentes Ledgers se comunicam entre si?

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

Como posso fazer transações entre Ledgers?

Você deve orquestrar o processo e mover o valor através de uma External Account. Isso envolve dois passos:

Ledger A -> External Account.

External Account -> Ledger B.

Preciso de um Ledger separado para cada Plugin?

Não. Um único Ledger pode suportar múltiplos Plugins. Por exemplo, um Ledger pode lidar com os Plugins de Exchange e Pix.

Assets

Um Asset pode ser vinculado a múltiplas Accounts?

Não. Cada Asset se vincula a uma única Account. Cada Asset também se vincula a uma External Account. O Midaz cria essa External Account automaticamente quando você cria o Asset.

Que tipos de Assets posso usar?

O Midaz suporta vários tipos de Assets:

currency: Moedas fiduciárias tradicionais como BRL, USD e EUR.
fiat: Um tipo alternativo para moedas fiduciárias; como currency, o código do Asset deve seguir a norma ISO 4217.
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

Como funciona um Portfolio?

Um Portfolio agrupa contas que pertencem à mesma entidade (CPF/CNPJ). Por exemplo, um CPF com dois valores de segment_id diferentes tem dois valores de account_id correspondentes. Você cria um Portfolio para esse CPF para vincular ambas as contas em uma única estrutura. Isso facilita encontrar e gerenciar as contas relacionadas.

Accounts

Uma Account pode ser associada a múltiplos Assets?

Não. Cada Account se vincula a um único Asset. Você não pode alterar esse vínculo.

O que é uma External Account?

Uma External Account recebe fundos de fora do Ledger. Ela traz dinheiro para dentro do sistema.

Como posso criar uma External Account?

O Midaz cria uma External Account automaticamente quando você cria um Asset. Essa External Account dá suporte a todas as transações que entram e saem do Ledger.

Uma Account pode ser vinculada a vários Segments?

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

Existe um limite de quantas Accounts posso criar no Midaz?

Não. Você pode criar quantas Accounts precisar. O Midaz não impõe nenhum limite ao número de Accounts.

Qual é o processo para adicionar fundos a uma conta ou realizar 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 Asset (por exemplo, BRL) no Ledger do Midaz, o Midaz também cria uma External Account para esse Asset.
Essa External Account 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 de reserva, ou uma conta bancária tradicional ou de pagamento.
Para depositar fundos de fora do Ledger do Midaz em uma conta de usuário, siga estes passos:
- Crie uma transação com a External Account como origem e as contas alvo como destino.
- O Midaz debita a External Account pelo valor (por isso ela fica negativa) e credita as contas de destino com base nos valores no payload da transação.

Transactions

Qual é a estrutura mínima de uma Transaction?

Uma Transaction deve ter pelo menos duas Operations. Por exemplo, uma transferência de R$ 100 da Account A para a Account B tem duas operações:

Operation 1: Debitar R$ 100 da Account A.
Operation 2: Creditar R$ 100 na Account B.

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

A Lerian oferece aos clientes várias formas de acessar os comprovantes de transação:

Via APIs — Recupere os dados da transação através das APIs e depois gere um comprovante visual no formato que você escolher.
Com o Reporter — Extraia os dados da transação e crie comprovantes visuais personalizados.
Através do Console — Acesse os dados da transação diretamente no Console da Lerian.

Entities

Como posso criar uma Entity?

A Entity (entity_id) aceita IDs externos. O Midaz não impõe nenhuma validação nesse 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 retentativas podem então criar operações duplicadas.

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

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

O que acontece se eu alterar o TTL em uma retentativa?

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

A resposta reproduzida será sempre idêntica?

Sim. Para uma requisição concluída, o Midaz retorna o mesmo resultado que armazenou 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 que você espelhe o Plano de Contas oficial da sua organização na plataforma. Você configura duas funcionalidades centrais:

Account Types — Crie as categorias lógicas do seu plano, como Ativos, Passivos, Receitas e Despesas. Atribua-as às contas no seu ledger. Quando você habilita a funcionalidade Account Types, o campo type na API de Accounts se torna obrigatório e deve corresponder a um valor registrado.
Rotas Contábeis — Use Operation Routes 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 que correspondam à sua lógica contábil.

Os Account Types 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 codifica regras na sua lógica de negócios.

Plugins

Plugins estendem o Midaz com integração e orquestração de processos. Eles fornecem abstrações para que você possa se concentrar no seu modelo de negócios em vez de lógica do sistema fora do seu domínio. As perguntas a seguir abordam como os plugins funcionam, como você faz o deployment deles e as opções disponíveis.

O que são Plugins?

Plugins são tecnologias que se integram ao ledger do Midaz. Eles simplificam a integração e orquestração de processos. Eles fornecem abstrações para que os clientes foquem no seu modelo de negócios. Os clientes não constroem nem gerenciam lógica do 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 a sua função.

Quais opções de plugins 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 dá suporte completo a eles.
Plugins do Marketplace: Os parceiros da Lerian criam esses plugins para nichos específicos de mercado. A Lerian ajuda a integrá-los ao Midaz. Os parceiros os oferecem e dão suporte diretamente.

Fees Engine

Estas perguntas abordam o Fees Engine. O Fees Engine é uma capacidade licenciada do Midaz executada dentro do processo unificado do ledger.

Conceitos Gerais

O que é o Fees Engine?

O Fees Engine faz parte do Midaz. Ele é executado no processo do ledger do Midaz para calcular taxas de transações financeiras. Configure-o e faça o deploy com o Midaz. Saiba mais na visão geral do Fees Engine. Ele opera em três domínios principais:

Pacotes de Taxas (/v2/organizations/{organization_id}/ledgers/{ledger_id}/packages): define as regras de cobrança por transação (taxa fixa, percentual, ou o maior entre os dois).
Billing Packages (/v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages): define cobranças periódicas por volume de transações ou por manutenção de contas.
Cálculo e estimativa: o Ledger avalia as taxas 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 o faturamento periódico. O Midaz v4 não tem endpoints de nível superior /v2/fees nem /v2/estimates.

Como o Fees Engine se encaixa no ecossistema Lerian?

O Fees Engine é executado dentro do processo do ledger do Midaz. Quando um pacote de taxas configurado se aplica, o Midaz incorpora seus cálculos de taxas à transação. Ele usa casos de uso de consulta do ledger em vez de uma conexão HTTP externa ao Midaz.

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

Os endpoints de Fees têm escopo de organização pelo ID da organização na rota URL /v2. A plataforma resolve o contexto do tenant pela solicitação autenticada; envie o material de autorização exigido pela sua configuração do Access Manager.

Authorization: Bearer ***

O Fees Engine armazena dados em qual banco?

O Fees Engine usa MongoDB para armazenamento. As deleções seguem o padrão de soft-delete. O Fees Engine não remove os registros fisicamente. Em vez disso, ele os marca com deletedAt. Um registro deletado não aparece nas listagens, mas você ainda pode auditá-lo.

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

O Midaz v4 expõe Fees dentro do Ledger unificado em /v2. Releases standalone anteriores do plugin-fees seguem sua própria matriz de compatibilidade legada e não representam o modelo de implantação da v4.

Pacotes de Taxas

O que é um Pacote de Taxas?

Um Pacote de Taxas (Package) é um conjunto de regras de cobrança sob um feeGroupLabel. Cada pacote se vincula a uma Organização + Ledger e, opcionalmente, a um Segment. Um pacote pode conter várias taxas (objetos Fee), cada uma com sua própria lógica de cálculo. Saiba mais sobre Pacotes de Taxas.

Como criar um Pacote de Taxas?

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

{
  "feeGroupLabel": "Tarifas Conta Digital",
  "ledgerId": "ldg_abc123",
  "segmentId": "seg_xyz456",
  "minimumAmount": "100.00",
  "maximumAmount": "50000.00",
  "transactionRoute": "PIX",
  "enable": true,
  "waivedAccounts": ["conta-isenta-1", "conta-isenta-2"],
  "fees": {
    "taxa_admin": {
      "feeLabel": "Taxa Administrativa",
      "calculationModel": {
        "applicationRule": "percentual",
        "calculations": [
          { "type": "percentage", "value": "1.50" }
        ]
      },
      "referenceAmount": "originalAmount",
      "priority": 1,
      "isDeductibleFrom": true,
      "creditAccount": "conta-receita-taxas"
    }
  }
}

Um pacote pode ser desativado temporariamente?

Sim. Configure o campo enable como false quando você cria ou atualiza o pacote. O Fees Engine ignora um pacote desativado durante o cálculo de taxas, mesmo quando o contexto da transação corresponde ao seu escopo.

Como funciona o escopo de um pacote (minimumAmount / maximumAmount)?

O Fees Engine aplica o pacote apenas a transações cujo valor esteja dentro do intervalo [minimumAmount, maximumAmount]. Se o valor da transação ficar fora desse intervalo, o Fees Engine ignora o pacote.Exemplo: Um pacote com minimumAmount: 100 e maximumAmount: 5000 cobra taxas apenas em transações entre R

100 e R

5.000.

Se você não definir maximumAmount, o pacote pode ser aplicado sem limite superior. Verifique as regras de validação da sua versão.

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

Sim. Configure o campo transactionRoute no pacote. O Fees Engine então considera o pacote apenas para transações com aquela rota, como "PIX", "TED" ou "BOLETO".

O que são waivedAccounts?

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

"waivedAccounts": ["conta-vip", "conta-funcionario"]

Este pacote não cobra nenhuma transação que venha dessas contas ou se destine a 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) suportam os parâmetros de query limit e page para paginação.

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

Modelos de Cálculo

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

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

Regra	Descrição
`flatFee`	Taxa fixa em valor absoluto
`percentual`	Taxa percentual sobre o valor de referência
`maxBetweenTypes`	Calcula flat e percentual; aplica o maior resultado

Como configurar uma taxa fixa (flatFee)?

Use exatamente 1 cálculo do tipo flat:

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

Isso cobra R$ 5,00 fixos, independente do valor da transação.

Como configurar uma taxa percentual (percentual)?

Use exatamente 1 cálculo do tipo percentage:

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

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

Como funciona o maxBetweenTypes?

O maxBetweenTypes exige 2 ou mais cálculos que combinam flat e percentage. O Fees Engine calcula ambos e aplica o maior resultado.Exemplo: Taxa mínima de R$ 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 R

200: 1% = R

2,00 vs. R

3,00 fixo → cobra **R

3,00**. Para uma transação de R

500: 1% = R

5,00 vs. R

3,00 fixo → cobra **R

5,00**.

Posso misturar múltiplos 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 o flatFee e o 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 taxa:

originalAmount: o valor original da transação, antes de qualquer taxa.
afterFeesAmount: o valor da transação após a aplicação das taxas de maior prioridade.

A taxa com priority: 1 é executada primeiro, por isso deve usar originalAmount. Não há taxas anteriores para considerar.

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

Quando isDeductibleFrom: true, o Fees Engine deduz a taxa do valor que o remetente envia. O destinatário recebe o valor descontado, e o remetente paga a mais para cobrir a cobrança.Quando false, o Fees Engine cobra a taxa separadamente. O remetente envia o valor cheio, e o Fees Engine debita a taxa à parte.Restrições:

isDeductibleFrom: true exige referenceAmount: originalAmount
Se o tipo for percentage: o valor não pode ultrapassar 100
Se o tipo for flat: o valor não pode ultrapassar o minimumAmount do pacote

Como funciona o campo priority?

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

priority: 1 → executada primeiro (obrigatoriamente usa originalAmount)
priority: 2 → executada depois, podendo usar afterFeesAmount

Use prioridades para encadear taxas. Por exemplo, execute uma taxa administrativa sobre o valor original. Depois execute uma taxa de IOF sobre o valor posterior à taxa administrativa.

O que é creditAccount?

É o alias da conta no ledger que recebe a receita da taxa. Cada taxa pode ter um creditAccount diferente. Isso ajuda quando diferentes taxas pertencem a centros de custo distintos.

"creditAccount": "conta-receita-taxas-admin"

Para que servem routeFrom e routeTo dentro de uma taxa?

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

Billing Packages

O que são Billing Packages?

Os Billing Packages são pacotes de cobrança periódica, independentes do cálculo de taxas por transação. Veja exemplos de Billing Packages para casos de uso. Existem dois tipos:

volume: cobra com base na quantidade de transações em um período, com precificação em faixas (tiers).
maintenance: cobra uma taxa fixa por conta em um determinado escopo.

Quando usar billing do tipo volume?

Use o billing de volume para cobrar clientes com base no número de transações processadas. É um modelo comum em plataformas de pagamento com precificação por volume. Você define faixas de preço (tiers) 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": "conta-cliente",
  "creditAccountAlias": "conta-receita-volume"
}

O último tier deve ser ilimitado (sem maxQuantity). Não pode haver lacunas ou sobreposições entre tiers.

Quando usar billing do tipo maintenance?

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

{
  "type": "maintenance",
  "feeAmount": "15.00",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "conta-receita-manutencao",
  "accountTarget": {
    "segmentId": "seg_clientes_premium"
  }
}

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

Como funcionam os tiers no billing de volume?

Os tiers definem a faixa de preço por unidade conforme o volume aumenta. As regras são:

Devem ser contíguos — sem lacunas entre faixas (minQuantity do próximo = maxQuantity do anterior + 1).
Não podem ter sobreposição.
O último tier deve ser ilimitado (sem maxQuantity).

Exemplo de tiers corretos:

"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 determinado de transações antes de os tiers serem aplicados. Isso ajuda os modelos de precificação com um volume mínimo incluso.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 de volume. Elas reduzem o valor cobrado com base em critérios adicionais. Elas complementam a lógica dos tiers principais.

O que é countMode no billing de volume?

Define como o Fees Engine conta as transações:

perRoute: conta transações por rota (ex: total de PIX aprovados).
perAccount: conta transações por conta individualmente.

Cálculo de taxas e billing

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

As taxas são avaliadas no fluxo de transação do Ledger quando um pacote correspondente se aplica. O Midaz v4 não tem endpoints de nível superior /v2/fees nem /v2/estimates; o endpoint com escopo de ledger POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates continua disponível para a prévia específica de um pacote.

Quais endpoints v4 configuram o Fees?

Configure pacotes de taxas de transação em /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages e pacotes de billing 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 pacotes de billing. Ele processa as regras configuradas para esse Ledger.

Erros Comuns

"Priority 1 must use originalAmount" — o que significa?

A taxa de priority: 1 deve ter referenceAmount: "originalAmount". Ela é a primeira taxa a ser executada, por isso não há taxas anteriores sobre as quais basear o cálculo.Correção:

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

"isDeductibleFrom requires originalAmount" — como resolver?

Taxas com isDeductibleFrom: true só podem usar referenceAmount: "originalAmount". Altere o campo:

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

"Flat fee value cannot exceed minimumAmount" — por quê?

Quando isDeductibleFrom: true e o tipo é flat, o valor da taxa não pode exceder o minimumAmount do pacote. Isso evita uma taxa maior que o valor mínimo da transação.Exemplo: Se minimumAmount: 100, a taxa flat não pode ser maior que R$ 100.

"Percentage value cannot exceed 100" — quando ocorre?

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

"Tiers must be contiguous" — como corrigir?

Os tiers de billing de volume devem cobrir todas as faixas sem lacunas. Verifique se o minQuantity de cada tier é exatamente maxQuantity + 1 do tier anterior.

// ❌ Errado — lacuna entre 500 e 600
{ "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
{ "minQuantity": 600, "unitPrice": "0.40" }

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

"Last tier must be unbounded" — o que isso significa?

O último tier no billing de volume precisa ser sem limite superior (sem maxQuantity). Isso mantém um preço nas transações acima da maior faixa definida.

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

No billing do tipo maintenance, o campo accountTarget aceita apenas uma das três opções. Não combine campos:

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

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

"aliases" no accountTarget tem algum limite?

Sim. O campo aliases aceita no máximo 100 aliases por Billing Package do tipo maintenance.

"flatFee requires exactly 1 calculation of type flat"

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

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

"percentual requires exactly 1 calculation of type percentage"

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 para funcionar — ele precisa de valores para comparar. Forneça ao menos um flat e um percentage.

O pacote não está sendo aplicado à transação — o que verificar?

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

enable: o pacote está ativo (enable: true)?
ledgerId: o pacote está vinculado ao ledger correto?
minimumAmount / maximumAmount: o valor da transação está dentro do intervalo?
transactionRoute: se o pacote tem transactionRoute, a transação usa a mesma rota?
segmentId: se o pacote está vinculado a um segmento específico, a conta pertence a ele?
waivedAccounts: a conta não está listada como isenta?

Um registro deletado pode ser recuperado?

O Fees Engine faz soft-delete dos registros. Ele os marca com deletedAt e não os remove do banco. A API não expõe endpoints de restauração por padrão. Consulte a equipe Lerian caso precise recuperar um registro deletado. Para a lista completa de códigos de erro, veja a referência de Códigos de Erro.

Midaz Core

CRM

Fees

APIs Lerian

Multi-tenancy e SaaS

Midaz

Organizations

Ledgers

Assets

Portfólios

Accounts

Transactions

Entities

Idempotência

Contabilidade no Midaz

Plugins

Fees Engine

Conceitos Gerais

Pacotes de Taxas

Modelos de Cálculo

Campos Importantes

Billing Packages

Cálculo de taxas e billing

Erros Comuns

​APIs Lerian

​Multi-tenancy e SaaS

​Midaz

​Organizations

​Ledgers

​Assets

​Portfólios

​Accounts

​Transactions

​Entities

​Idempotência

​Contabilidade no Midaz

​Plugins

​Fees Engine

​Conceitos Gerais

​Pacotes de Taxas

​Modelos de Cálculo

​Campos Importantes

​Billing Packages

​Cálculo de taxas e billing

​Erros Comuns

APIs Lerian

Multi-tenancy e SaaS

Midaz

Organizations

Ledgers

Assets

Portfólios

Accounts

Transactions

Entities

Idempotência

Contabilidade no Midaz

Plugins

Fees Engine

Conceitos Gerais

Pacotes de Taxas

Modelos de Cálculo

Campos Importantes

Billing Packages

Cálculo de taxas e billing

Erros Comuns