> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # FAQ > Respostas a perguntas comuns sobre Lerian e Midaz: limites de paginação da API, isolamento de dados no SaaS, escopo de tenant via JWT e configuração de plataforma com múltiplas Organizações. ## APIs da Lerian *** Esta seção responde a perguntas comuns sobre as APIs da Lerian. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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 > [accordion] 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. > [accordion] Posso usar uma única licença em várias Organizações? > > Veja [Licença da Lerian](https://docs.lerian.studio/pt/start-here/evaluate-and-deploy/lerians-license.md) para saber como cada licença se aplica às Organizações. > [accordion] Uma Organização pode ter vários Plugins? > > Sim. Uma Organização pode ter mais de um Plugin. > [accordion] Uma Organização pode ter vários Ledgers? > > Sim. Uma Organização pode gerenciar vários Ledgers. > [accordion] 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: > > **Step 1** > > 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. > > **Step 2** > > 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 > [accordion] 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`. > [accordion] 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: > > **Step 1** > > Ledger A -> Conta Externa. > > **Step 2** > > Conta Externa -> Ledger B. > [accordion] 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 > [accordion] 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. > [accordion] 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 > [accordion] 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 > [accordion] 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. > [accordion] O que é uma Conta Externa? > > Uma Conta Externa recebe fundos de fora do Ledger. Ela traz dinheiro para dentro do sistema. > [accordion] 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`. > [accordion] Uma Conta pode ser vinculada a vários Segmentos? > > Não. Cada conta vincula a apenas um Segmento (`segmentId`). > [accordion] 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. > [accordion] 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: > > 1. Quando você cria um Ativo (por exemplo, BRL) no Ledger do Midaz, o Midaz também cria uma Conta Externa para esse Ativo. > 2. 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. > 3. 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 > [accordion] 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. > [accordion] É 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: > > 1. **Pelas APIs**: recupere os dados da transação pelas APIs e gere um comprovante visual no formato que preferir. > 2. **Com o Reporter**: extraia os dados da transação e crie comprovantes visuais personalizados. > 3. **Pelo Console**: acesse os dados da transação diretamente no Console da Lerian. ### Entidades > [accordion] 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 > [accordion] 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. > [accordion] 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. > [accordion] 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`. > [accordion] 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 > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/accounts.md): 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](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md): 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. > [accordion] 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. > [accordion] Como os plugins são distribuídos? > > Depois que você contrata um plugin, a Lerian o fornece. No [modelo BYOC](https://docs.lerian.studio/pt/start-here/evaluate-and-deploy/deployment-models.md), 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. > [accordion] 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 > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-overview.md). 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](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md). > * **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. > [accordion] 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. > [accordion] 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 *** > ``` > [accordion] 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. > [accordion] 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 > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/fees/using-fee-engine.md). > [accordion] 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](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-package.md) para todos os detalhes. > > ```json theme={null} > { > "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" > } > } > } > ``` > [accordion] 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. > [accordion] 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. > [accordion] 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`. > [accordion] 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. > > ```json theme={null} > "waivedAccounts": ["vip-account", "employee-account"] > ``` > > Esse package não cobra essas contas. > [accordion] 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 > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/fees/fee-engine-calculation.md) 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 | > [accordion] Como configuro uma tarifa fixa (flatFee)? > > Use exatamente **1 cálculo** do tipo `flat`: > > ```json theme={null} > "calculationModel": { > "applicationRule": "flatFee", > "calculations": [ > { "type": "flat", "value": "5.00" } > ] > } > ``` > > Isso cobra um valor fixo de 5,00, independentemente do valor da transação. > [accordion] Como configuro uma tarifa percentual (percentual)? > > Use exatamente **1 cálculo** do tipo `percentage`: > > ```json theme={null} > "calculationModel": { > "applicationRule": "percentual", > "calculations": [ > { "type": "percentage", "value": "2.50" } > ] > } > ``` > > Isso cobra 2,5% do valor de referência da transação. > [accordion] 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: > > ```json theme={null} > "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**. > [accordion] 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 > [accordion] 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. > > > [!NOTE] > > > > A tarifa com `priority: 1` roda primeiro, então ela **deve** usar `originalAmount`. Não existem tarifas anteriores para considerar. > [accordion] 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 > [accordion] 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. > [accordion] 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. > > ```json theme={null} > "creditAccount": "admin-fee-revenue-account" > ``` > [accordion] 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 > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/fees/billing-package-examples.md) 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. > [accordion] 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. > > ```json theme={null} > { > "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" > } > ``` > [accordion] 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. > > ```json theme={null} > { > "type": "maintenance", > "feeAmount": "15.00", > "assetCode": "BRL", > "maintenanceCreditAccount": "maintenance-revenue-account", > "accountTarget": { > "segmentId": "{segment_id}" > } > } > ``` > > > [!NOTE] > > > > O `accountTarget` deve ter exatamente **um** dos três campos: `segmentId`, `portfolioId` ou `aliases` (máximo de 100 aliases). > [accordion] 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: > > 1. Devem ser **contíguas**: sem lacunas entre as faixas (`minQuantity` da próxima = `maxQuantity` da anterior + 1). > 2. Não podem se **sobrepor**. > 3. 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:** > > ```json theme={null} > "tiers": [ > { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" }, > { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.60" }, > { "minQuantity": 2001, "unitPrice": "0.40" } > ] > ``` > [accordion] 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](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md#free-quota). > [accordion] 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. > [accordion] 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 > [accordion] 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. > [accordion] 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`. > [accordion] 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 > [accordion] 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:** > > ```json theme={null} > { > "priority": 1, > "referenceAmount": "originalAmount" > } > ``` > [accordion] Como corrijo o erro 0205 "originalAmount is required when isDeductibleFrom is true"? > > Tarifas com `isDeductibleFrom: true` apenas podem usar `referenceAmount: "originalAmount"`. Atualize o campo: > > ```json theme={null} > { > "isDeductibleFrom": true, > "referenceAmount": "originalAmount" > } > ``` > [accordion] 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. > [accordion] 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. > [accordion] 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. > > ```json theme={null} > // ❌ 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" } > ``` > [accordion] 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: > > ```json theme={null} > // ❌ Wrong > "accountTarget": { > "segmentId": "{segment_id}", > "portfolioId": "{portfolio_id}" > } > > // ✅ Correct > "accountTarget": { > "segmentId": "{segment_id}" > } > ``` > [accordion] Existe um limite de aliases em accountTarget? > > Sim. O campo `aliases` aceita no máximo **100 aliases** por Billing Package de manutenção. > [accordion] 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`. > > ```json theme={null} > // ✅ Correct > "calculationModel": { > "applicationRule": "flatFee", > "calculations": [{ "type": "flat", "value": "10.00" }] > } > ``` > [accordion] 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`. > [accordion] Erro 0201: "applicationRule maxBetweenTypes must have more than 1 calculation" > > O `maxBetweenTypes` exige pelo menos 2 cálculos, porque precisa de valores para comparar. > [accordion] O que devo verificar quando o package não é aplicado à transação? > > Checklist de diagnóstico (veja também [Boas Práticas](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-best-practices.md)): > > * **`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? > [accordion] 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.