> ## 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 title="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.
</Accordion>

## Multi-tenancy e SaaS

***

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

<AccordionGroup>
  <Accordion title="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](/pt/platform/multi-tenancy).
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Midaz

***

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

### Organizações

<AccordionGroup>
  <Accordion title="Organizações diferentes se comunicam entre si?">
    Não. Cada Organização opera de forma independente e não se comunica com as outras.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Uma Organização pode ter vários Plugins?">
    Sim. Uma Organização pode ter mais de um Plugin.
  </Accordion>

  <Accordion title="Uma Organização pode ter vários Ledgers?">
    Sim. Uma Organização pode gerenciar vários Ledgers.
  </Accordion>

  <Accordion title="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:

    <Steps>
      <Step>
        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>

      <Step>
        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**).
      </Step>
    </Steps>

    Esse padrão move valor entre ledgers em Organizações diferentes.
  </Accordion>
</AccordionGroup>

### Ledgers

<AccordionGroup>
  <Accordion title="Ledgers diferentes se comunicam entre si?">
    Não. Ledgers não se comunicam diretamente. Transferências entre Ledgers exigem orquestração.
  </Accordion>

  <Accordion title="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:

    <Steps>
      <Step>
        Ledger A -> Conta Externa.
      </Step>

      <Step>
        Conta Externa -> Ledger B.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Ativos

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Portfólios

<Accordion title="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.
</Accordion>

### Contas

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="O que é uma Conta Externa?">
    Uma Conta Externa recebe fundos de fora do Ledger. Ela traz dinheiro para dentro do sistema.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Uma Conta pode ser vinculada a vários Segmentos?">
    Não. Cada conta (`account_id`) vincula a apenas um Segmento (`segment_id`).
  </Accordion>

  <Accordion title="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>

  <Accordion title="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 (que fica negativo) e credita as contas de destino pelos valores informados no payload da transação.
  </Accordion>
</AccordionGroup>

### Transações

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="É 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:

    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.
  </Accordion>
</AccordionGroup>

### Entidades

<Accordion title="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.
</Accordion>

### Idempotência

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Contabilidade no Midaz

<Accordion title="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](/pt/products/midaz/accounts): 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](/pt/products/midaz/transaction-routing-entities): 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.
</Accordion>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="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](/pt/products/midaz/fees/fees-engine-overview). 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`.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Fee Packages

<AccordionGroup>
  <Accordion title="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](/pt/products/midaz/fees/using-fee-engine).
  </Accordion>

  <Accordion title="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](/pt/reference/products/midaz/v2/create-package) para todos os detalhes.

    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="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>

  <Accordion title="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.

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

  <Accordion title="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"`.
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    "waivedAccounts": ["vip-account", "employee-account"]
    ```

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

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

### Modelos de Cálculo

<AccordionGroup>
  <Accordion title="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](/pt/products/midaz/fees/fee-engine-calculation) 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 |
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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:

    ```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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Campos Importantes

<AccordionGroup>
  <Accordion title="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.</Note>
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Billing Packages

<AccordionGroup>
  <Accordion title="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](/pt/products/midaz/fees/billing-package-examples) 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>

  <Accordion title="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"
    }
    ```

    <Note>A última faixa deve ser **sem limite** (sem `maxQuantity`). Não pode haver lacunas nem sobreposições entre as faixas.</Note>
  </Accordion>

  <Accordion title="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": "seg_premium_clients"
      }
    }
    ```

    <Note>O `accountTarget` deve ter exatamente **um** dos três campos: `segmentId`, `portfolioId` ou `aliases` (máximo de 100 aliases).</Note>
  </Accordion>

  <Accordion title="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. A **última faixa deve ser sem limite** (sem `maxQuantity`).

    **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>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Cálculo e cobrança de tarifas

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Erros Comuns

<AccordionGroup>
  <Accordion title="O que significa &#x22;Priority 1 must use originalAmount&#x22;?">
    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>

  <Accordion title="Como corrijo &#x22;isDeductibleFrom requires originalAmount&#x22;?">
    Tarifas com `isDeductibleFrom: true` apenas podem usar `referenceAmount: "originalAmount"`. Atualize o campo:

    ```json theme={null}
    {
      "isDeductibleFrom": true,
      "referenceAmount": "originalAmount"
    }
    ```
  </Accordion>

  <Accordion title="Por que recebo &#x22;Flat fee value cannot exceed minimumAmount&#x22;?">
    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>

  <Accordion title="Quando ocorre &#x22;Percentage value cannot exceed 100&#x22;?">
    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>

  <Accordion title="Como corrijo &#x22;Tiers must be contiguous&#x22;?">
    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>

  <Accordion title="O que significa &#x22;Last tier must be unbounded&#x22;?">
    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.
  </Accordion>

  <Accordion title="&#x22;accountTarget must have exactly one of: segmentId, portfolioId, aliases&#x22;">
    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": "seg_abc",
      "portfolioId": "port_xyz"
    }

    // ✅ Correct
    "accountTarget": {
      "segmentId": "seg_abc"
    }
    ```
  </Accordion>

  <Accordion title="Existe um limite de aliases em accountTarget?">
    Sim. O campo `aliases` aceita no máximo **100 aliases** por Billing Package de manutenção.
  </Accordion>

  <Accordion title="&#x22;flatFee requires exactly 1 calculation of type flat&#x22;">
    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>

  <Accordion title="&#x22;percentual requires exactly 1 calculation of type percentage&#x22;">
    Assim como o `flatFee`, o `applicationRule: "percentual"` aceita exatamente 1 cálculo do tipo `percentage`.
  </Accordion>

  <Accordion title="&#x22;maxBetweenTypes requires 2 or more calculations&#x22;">
    O `maxBetweenTypes` exige pelo menos 2 cálculos, porque precisa de valores para comparar. Informe pelo menos um `flat` e um `percentage`.
  </Accordion>

  <Accordion title="O que devo verificar quando o package não é aplicado à transação?">
    Checklist de diagnóstico (veja também [Boas Práticas](/pt/products/midaz/fees/fees-engine-best-practices)):

    * **`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?
  </Accordion>

  <Accordion title="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](/pt/reference/products/midaz/v2/estimate-fee-calculation).
  </Accordion>
</AccordionGroup>