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

> Encontre respostas para perguntas frequentes sobre as APIs Lerian, multi-tenancy, isolamento em SaaS, paginação e configuração da plataforma.

## APIs Lerian

***

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

<Accordion title="Existe um número máximo de registros por página nas listagens da API? Posso aumentar esse limite?">
  Sim. Por padrão, o número máximo de registros por página é **100**. Esse limite garante um desempenho consistente e ajuda a gerenciar o volume de dados transferidos em cada requisição. No entanto, você pode aumentar esse valor configurando a variável de ambiente `MAX_PAGINATION_LIMIT` na configuração do seu deployment. Após a atualização e reinicialização da aplicação, a API aceitará tamanhos de página maiores.

  **Importante**: Aumentar o tamanho da página pode afetar os tempos de resposta, especialmente em ambientes que lidam com grandes volumes de dados. Sempre teste exaustivamente em staging antes de aplicar mudanças em produção.
</Accordion>

## Multi-tenancy e SaaS

***

Perguntas frequentes sobre isolamento de dados, escopo de tenant e como multi-tenancy funciona nos deployments 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 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](/pt/multi-tenancy).
  </Accordion>

  <Accordion title="Preciso passar um ID de tenant nas minhas requisições de API?">
    Não. O contexto do seu tenant está embutido no JWT access token que você recebe durante a autenticação. A plataforma resolve automaticamente — você não precisa incluir nenhum identificador de tenant em headers ou no corpo da requisição.
  </Accordion>

  <Accordion title="Posso ter múltiplas Organizations sob um único tenant?">
    Sim. Um tenant pode conter múltiplas Organizations, cada uma com seus próprios Ledgers, contas e transações. Todas são escopadas ao seu tenant automaticamente.
  </Accordion>

  <Accordion title="A API é diferente entre SaaS e deployments self-hosted?">
    Não. A superfície da API é idêntica — mesmos endpoints, mesmos payloads, mesmas respostas. A única diferença é que o SaaS exige autenticação em toda requisição, e o seu token automaticamente escopa todas as operações ao seu tenant.
  </Accordion>
</AccordionGroup>

## Midaz

***

Aqui, você encontrará as respostas para perguntas comuns sobre Organizations, Ledgers, Accounts, Transactions e mais no Midaz.

### Organizations

<AccordionGroup>
  <Accordion title="Diferentes Organizations se comunicam entre si?">
    Não, cada Organization opera de forma independente e não se comunica com as outras.
  </Accordion>

  <Accordion title="Posso usar uma única licença em múltiplas Organizations?">
    Não, cada licença está vinculada a uma Organization específica. Se você precisa de suporte para múltiplas Organizations, deve adquirir licenças separadas para cada uma. A mesma regra se aplica aos Plugins.
  </Accordion>

  <Accordion title="Uma Organization pode ter múltiplos Plugins?">
    Sim, uma Organization pode ter mais de um Plugin associado a ela.
  </Accordion>

  <Accordion title="Uma Organization pode ter múltiplos Ledgers?">
    Sim, uma Organization pode gerenciar múltiplos Ledgers.
  </Accordion>

  <Accordion title="Posso criar transações entre uma Parent Organization e uma Child Organization?">
    Embora você possa criar uma **Parent Organization** e uma **Child Organization**, cada **Organization** mantém seu próprio Ledger, operando de forma independente. Como transações não podem mover valor diretamente entre ledgers, você precisa orquestrar a transferência com os seguintes passos:

    <Steps>
      <Step>
        Inicie uma transação no ledger de origem, transferindo o valor da conta original (**source**) para a **external account** do asset (distribute). Isso remove o valor do ledger original.
      </Step>

      <Step>
        **Crie uma segunda transação** no ledger de destino, onde o **source** agora é a **external account** do asset, e o valor é alocado para a conta receptora (**distribute**).
      </Step>
    </Steps>

    Essa abordagem garante transferências de valor entre ledgers de diferentes organizations de forma transparente e controlada.
  </Accordion>
</AccordionGroup>

### Ledgers

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

  <Accordion title="Como posso fazer transações entre Ledgers?">
    Você deve orquestrar o processo e transferir o valor para uma External Account. Normalmente, isso envolve dois passos:

    <Steps>
      <Step>
        Ledger A -> External Account.
      </Step>

      <Step>
        External Account -> Ledger B.
      </Step>
    </Steps>
  </Accordion>

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

### Assets

<AccordionGroup>
  <Accordion title="Um Asset pode ser vinculado a múltiplas Accounts?">
    Não, cada Asset é vinculado a uma única Account. No entanto, cada Asset também será vinculado a uma External Account que é criada automaticamente quando o Asset é criado.
  </Accordion>

  <Accordion title="Que tipos de Assets posso usar?">
    O Midaz foi construído para flexibilidade, suportando uma ampla variedade de Assets:

    * *currency*: Moedas fiduciárias tradicionais como BRL, USD e EUR.
    * *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.
  </Accordion>
</AccordionGroup>

### Portfólios

<Accordion title="Como funciona um Portfolio?">
  Um **Portfolio** agrupa contas que pertencem à mesma entidade (**CPF/CNPJ**). Por exemplo, se um único CPF tem dois valores de `segment_id` diferentes, ele também terá dois valores de `account_id` correspondentes. Para simplificar a recuperação, um Portfolio é criado para esse CPF, vinculando ambas as contas em uma única estrutura. Isso garante acesso e gerenciamento mais fáceis das contas relacionadas.
</Accordion>

### Accounts

<AccordionGroup>
  <Accordion title="Uma Account pode ser associada a múltiplos Assets?">
    Não, cada Account é associada a um único Asset, e essa associação não pode ser alterada.
  </Accordion>

  <Accordion title="O que é uma External Account?">
    Uma External Account é usada para receber fundos de fora do Ledger, efetivamente trazendo dinheiro para dentro do sistema.
  </Accordion>

  <Accordion title="Como posso criar uma External Account?">
    O Midaz configura automaticamente uma **External Account** quando você cria um Asset, garantindo suporte contínuo para todas as transações que entram e saem do Ledger.
  </Accordion>

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

  <Accordion title="Existe um limite de quantas Accounts posso criar no Midaz?">
    Não. Você pode criar quantas Accounts sua configuração precisar. Sem limites, sem restrições — apenas a flexibilidade para escalar do seu jeito.
  </Accordion>

  <Accordion title="Qual é o processo para adicionar fundos a uma conta ou realizar um cash-in usando dinheiro vindo de fora do ambiente do Ledger (Midaz)?">
    Para entender o processo de recarga de saldo, vamos considerar os seguintes pontos:

    1. No Ledger do Midaz, quando um Asset (por exemplo, BRL) é criado, uma External Account associada a esse asset também é gerada.
    2. Essa External Account atua como um gateway entre o ecossistema Lerian e o mundo externo. Em outras palavras, ela serve como um espelho dos saldos mantidos pela instituição em sua conta PI, conta de liquidação, conta de reserva, ou até mesmo uma conta bancária tradicional ou conta de pagamento que detém os fundos reais.
    3. Para depositar fundos em uma conta de usuário com um Asset específico vindo de fora do Ledger do Midaz, o processo é o seguinte:
       * Inicie uma transação onde a origem é a External Account e o destino é a(s) conta(s) alvo.
       * Como resultado, a External Account será debitada pelo valor transferido (ficando negativa), enquanto a(s) conta(s) de destino serão creditadas de acordo, com base nos valores fornecidos no payload da transação.
  </Accordion>
</AccordionGroup>

### Transactions

<AccordionGroup>
  <Accordion title="Qual é a estrutura mínima de uma Transaction?">
    Uma Transaction deve ter pelo menos duas Operations. Por exemplo, transferir R\$ 100 da Account A para a Account B consiste em:

    * **Operation 1:** Debitar R\$ 100 da Account A.
    * **Operation 2:** Creditar R\$ 100 na Account B.
  </Accordion>

  <Accordion title="É possível gerar um comprovante de transferência em PDF contendo os detalhes de uma transação concluída?">
    A Lerian oferece aos clientes múltiplas opções para acessar comprovantes de transação:

    1. **Via APIs** – Recupere dados de transações através das nossas APIs, permitindo que você gere um comprovante visual no formato de sua escolha.
    2. **Usando o Reporter** – Extraia dados de transações e crie comprovantes visuais personalizados.
    3. **Através do Console** – Acesse informações de transações diretamente pelo Console da Lerian.
  </Accordion>
</AccordionGroup>

### Entities

<Accordion title="Como posso criar uma Entity?">
  Atualmente, a Entity (`entity_id`) está aberta para IDs externos, sem validação imposta pelo Midaz. Isso significa que você pode usar os IDs que já existem no seu banco de dados, integrando-os de forma transparente 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. Isso significa que retentativas podem resultar em operações duplicadas.
  </Accordion>

  <Accordion title="Posso reutilizar uma chave de idempotência em diferentes endpoints?">
    Não. As chaves devem ter escopo limitado a uma única operação e endpoint.
  </Accordion>

  <Accordion title="O que acontece se eu alterar o TTL em uma retentativa?">
    Apenas o TTL da primeira requisição é utilizado. Alterá-lo posteriormente não tem efeito.
  </Accordion>

  <Accordion title="A resposta reproduzida será sempre idêntica?">
    Sim. O Midaz reproduz a resposta completa, incluindo headers e body, para requisições concluídas.
  </Accordion>

  <Accordion title="Qual é o TTL padrão se eu não enviar X-TTL?">
    A janela padrão é de **300 segundos** (5 minutos), mas você pode personalizá-la até o limite permitido por endpoint.
  </Accordion>
</AccordionGroup>

### Contabilidade no Midaz

<Accordion title="Como posso refletir meu próprio Plano de Contas no Midaz?">
  R: O Midaz permite que você espelhe o **Plano de Contas** oficial da sua organização diretamente na plataforma, configurando duas funcionalidades centrais:

  * [Account Types](/pt/midaz/accounts) – Crie as categorias lógicas do seu plano (por exemplo, Ativos, Passivos, Receitas, Despesas) e atribua-as às contas no seu ledger. Quando a funcionalidade Account Types está habilitada, o campo type na API de Accounts se torna obrigatório e deve corresponder a um dos valores que você registrou.
  * [Rotas Contábeis](/pt/midaz/transaction-routing-entities) – Use Operation Routes para validar cada "perna" de uma transação (por exemplo, o débito deve vir de uma conta do tipo `user_wallet`) e Rotas Contábeis (o recurso `transactionRoute` na API) para definir padrões completos de transação que se alinham com sua lógica contábil.

  Combinando Account Types e Rotas Contábeis, você pode aplicar suas regras contábeis no nível do ledger — garantindo que cada transação seja validada e categorizada de acordo com seu Plano de Contas, sem codificar regras na sua lógica de negócios.
</Accordion>

## Plugins

***

Plugins estendem as capacidades do Midaz, permitindo integração e orquestração de processos de forma fluida. Projetados para remover complexidade, eles fornecem abstrações poderosas que permitem que você se concentre no seu modelo de negócios, garantindo eficiência e escalabilidade.

Explore as perguntas mais comuns sobre como os plugins funcionam, seu deployment e as opções disponíveis para aprimorar suas operações.

<AccordionGroup>
  <Accordion title="O que são Plugins?">
    Plugins são tecnologias integradas ao ledger do Midaz, projetadas para simplificar a integração e orquestração de processos. Eles fornecem abstrações que permitem aos clientes focar no seu modelo de negócios sem precisar construir ou gerenciar lógica essencial do sistema que está fora do seu domínio.
  </Accordion>

  <Accordion title="Os plugins podem ser usados sem o Midaz?">
    Não. Os plugins são projetados para operar exclusivamente com o Midaz. Eles fornecem abstrações específicas e orquestram transações com base na estrutura do ledger, garantindo integração precisa e eficiente.
  </Accordion>

  <Accordion title="Como os plugins são distribuídos?">
    Uma vez contratados, os plugins são fornecidos e instalados dentro da infraestrutura do cliente (modelo on-premise), junto com sua instância do Midaz. As aplicações se conectam de acordo com a funcionalidade específica de cada plugin.
  </Accordion>

  <Accordion title="Quais opções de plugins a Lerian oferece?">
    A Lerian oferece dois tipos de plugins, categorizados por sua origem:

    * **Plugins Nativos:** Desenvolvidos e totalmente integrados ao ledger do Midaz pela Lerian, esses plugins garantem suporte completo e integração fluida com a plataforma.
    * **Plugins do Marketplace:** Criados por parceiros da Lerian para atender nichos específicos de mercado, esses plugins estão disponíveis no marketplace. A Lerian facilita sua integração ao Midaz, mas sua oferta e suporte são gerenciados diretamente pelos respectivos parceiros.
  </Accordion>
</AccordionGroup>

## Fees Engine

***

Perguntas frequentes sobre o Fees Engine — parte da família de produtos Midaz, um serviço de cálculo de taxas sobre transações financeiras, implantado de forma independente sob a licença Enterprise.

### Conceitos Gerais

<AccordionGroup>
  <Accordion title="O que é o Fees Engine?">
    O Fees Engine faz parte da **família de produtos Midaz**. É um serviço de cálculo de taxas sobre transações financeiras — implantado de forma independente e disponível sob a licença Enterprise. Saiba mais na [visão geral do Fees Engine](/pt/midaz/fees/fees-engine-overview). Ele opera em três domínios principais:

    * **Pacotes de Taxas (`/v1/packages`):** define as regras de cobrança por transação (taxa fixa, percentual, ou o maior entre os dois).
    * **Billing Packages (`/v1/billing-packages`):** define cobranças periódicas por volume de transações ou por manutenção de contas.
    * **Cálculo e Estimativa (`/v1/fees` e `/v1/estimates`):** endpoints para calcular taxas em tempo real ou simular antes de confirmar.
  </Accordion>

  <Accordion title="Como o Fees Engine se encaixa no ecossistema Lerian?">
    O Fees Engine faz parte da família de produtos Midaz, implantado como um serviço independente sob a licença Enterprise. É um serviço de cálculo: com base em regras configuradas, determina quanto deve ser cobrado — e de quem — e devolve o resultado para que a sua aplicação o registre. Ele lê do Midaz, mas nunca escreve no ledger.
  </Accordion>

  <Accordion title="O que preciso enviar em toda requisição ao Fees Engine?">
    Todas as requisições exigem o header `X-Organization-Id` com o ID da sua organização no Midaz. Este é um header de escopo de organização específico do Fees Engine, não um identificador de tenant — o contexto do seu tenant continua sendo resolvido automaticamente pelo JWT. Quando o plugin de autenticação estiver ativo, também é necessário um Bearer token no header `Authorization`.

    ```
    X-Organization-Id: <seu-organization-id>
    Authorization: Bearer <seu-token>
    ```
  </Accordion>

  <Accordion title="O Fees Engine armazena dados em qual banco?">
    O Fees Engine usa **MongoDB** como backend de armazenamento. Deleções seguem o padrão de **soft-delete** — os registros não são removidos fisicamente, apenas marcados com `deletedAt`. Isso significa que registros "deletados" não aparecem nas listagens, mas podem ser auditados.
  </Accordion>

  <Accordion title="Qual a versão mínima do Midaz necessária para usar o Fees Engine?">
    **Midaz v3.6.0** ou superior. A versão atual do Fees Engine depende de APIs do módulo Transaction que só estão disponíveis a partir da v3.6.0. Versões anteriores do Midaz não são compatíveis.
  </Accordion>
</AccordionGroup>

### Pacotes de Taxas

<AccordionGroup>
  <Accordion title="O que é um Pacote de Taxas?">
    Um Pacote de Taxas (`Package`) é um conjunto de regras de cobrança agrupadas sob um `feeGroupLabel`. Cada pacote é vinculado a uma **Organização + Ledger** e, opcionalmente, a um **Segment**. Um pacote pode conter múltiplas taxas individuais (objetos `Fee`), cada uma com sua própria lógica de cálculo. Saiba mais sobre [Pacotes de Taxas](/pt/midaz/fees/using-fee-engine).
  </Accordion>

  <Accordion title="Como criar um Pacote de Taxas?">
    Envie um `POST /v1/packages` com o seguinte corpo. Veja a [referência da API Create Package](/pt/reference/midaz/plugins/fees-engine/create-package) para detalhes completos.

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

  <Accordion title="Um pacote pode ser desativado temporariamente?">
    Sim. Use o campo `enable: false` ao criar ou atualizar o pacote. Um pacote desativado não é considerado no cálculo de taxas, mesmo que o contexto da transação corresponda ao seu escopo.
  </Accordion>

  <Accordion title="Como funciona o escopo de um pacote (minimumAmount / maximumAmount)?">
    O pacote só é aplicado a transações cujo valor esteja dentro do intervalo `[minimumAmount, maximumAmount]`. Se a transação não se encaixar nesse intervalo, o pacote é ignorado.

    **Exemplo:** Um pacote com `minimumAmount: 100` e `maximumAmount: 5000` só cobrará taxas em transações entre R$ 100 e R$ 5.000.

    <Note>Se o `maximumAmount` não for definido, o pacote pode ser aplicado sem limite superior — verifique as regras de validação da sua versão.</Note>
  </Accordion>

  <Accordion title="Posso filtrar um pacote por rota de transação?">
    Sim. Use o campo `transactionRoute` no pacote. Quando definido, o pacote só será considerado em transações com aquela rota específica (ex: `"PIX"`, `"TED"`, `"BOLETO"`).
  </Accordion>

  <Accordion title="O que são waivedAccounts?">
    São aliases de contas **isentas** de taxas dentro daquele pacote. Se o remetente ou destinatário da transação for uma conta listada em `waivedAccounts`, as taxas do pacote não são aplicadas para ela.

    ```json theme={null}
    "waivedAccounts": ["conta-vip", "conta-funcionario"]
    ```

    Qualquer transação originada ou destinada a essas contas não será tarifada por este pacote.
  </Accordion>

  <Accordion title="Os endpoints de listagem têm paginação?">
    Sim. Os endpoints de listagem (`GET /v1/packages`, `GET /v1/billing-packages`) suportam os parâmetros de query `limit` e `page` para paginação.

    ```
    GET /v1/packages?limit=20&page=2
    ```
  </Accordion>
</AccordionGroup>

### Modelos de Cálculo

<AccordionGroup>
  <Accordion title="Quais são os modelos de cálculo disponíveis?">
    O campo `applicationRule` dentro de `calculationModel` define como a taxa é calculada. Veja [Modelos de Cálculo](/pt/midaz/fees/fee-engine-calculation) 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 |
  </Accordion>

  <Accordion title="Como configurar uma taxa fixa (flatFee)?">
    Use exatamente **1 cálculo** do tipo `flat`:

    ```json theme={null}
    "calculationModel": {
      "applicationRule": "flatFee",
      "calculations": [
        { "type": "flat", "value": "5.00" }
      ]
    }
    ```

    Isso cobra R\$ 5,00 fixos, independente do valor da transação.
  </Accordion>

  <Accordion title="Como configurar uma taxa 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% sobre o valor de referência da transação.
  </Accordion>

  <Accordion title="Como funciona o maxBetweenTypes?">
    O `maxBetweenTypes` exige **2 ou mais cálculos** (combinando `flat` e `percentage`). O sistema calcula ambos e aplica o **maior valor resultante**.

    **Exemplo:** Taxa mínima de R\$ 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 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\*\*.
  </Accordion>

  <Accordion title="Posso misturar múltiplos percentuais no maxBetweenTypes?">
    Sim. Você pode incluir qualquer combinação de `flat` e `percentage` — o sistema avalia todos e aplica o maior. Porém, o `flatFee` e o `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** a taxa é calculada:

    * `originalAmount`: valor original da transação, **antes** de qualquer taxa ser aplicada.
    * `afterFeesAmount`: valor da transação **após** as taxas de maior prioridade já terem sido aplicadas.

    <Note>A taxa com `priority: 1` (a primeira a ser executada) **deve** usar `originalAmount`. Não há taxas anteriores para considerar.</Note>
  </Accordion>

  <Accordion title="O que é isDeductibleFrom e quando devo usá-lo?">
    Quando `isDeductibleFrom: true`, a taxa é **deduzida do valor enviado pelo remetente**. O destinatário recebe o valor já descontado da taxa, e o remetente paga a mais para cobrir a cobrança.

    Quando `false`, a taxa é cobrada **separadamente** (o remetente envia o valor cheio e a taxa é debitada à 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
  </Accordion>

  <Accordion title="Como funciona o campo priority?">
    O `priority` define a **ordem de execução** das taxas dentro de um pacote. Taxas com valor menor são executadas primeiro.

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

    Use prioridades para criar encadeamento de taxas — por exemplo, uma taxa administrativa calculada sobre o valor original, seguida de uma taxa de IOF calculada sobre o valor já com a taxa administrativa.
  </Accordion>

  <Accordion title="O que é creditAccount?">
    É o alias da conta no ledger para onde a receita da taxa será creditada. Cada taxa pode ter um `creditAccount` diferente — útil quando diferentes taxas precisam ser contabilizadas em centros de custo distintos.

    ```json theme={null}
    "creditAccount": "conta-receita-taxas-admin"
    ```
  </Accordion>

  <Accordion title="Para que servem routeFrom e routeTo dentro de uma taxa?">
    Esses campos definem as rotas das **pernas contábeis** geradas pela cobrança da taxa. São opcionais e permitem rastrear a origem e destino das movimentações de taxa no ledger com granularidade.
  </Accordion>
</AccordionGroup>

### Billing Packages

<AccordionGroup>
  <Accordion title="O que são Billing Packages?">
    São pacotes de cobrança **periódica**, independentes do cálculo de taxas por transação. Veja [exemplos de Billing Packages](/pt/midaz/fees/billing-package-examples) para casos de uso detalhados. 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.
  </Accordion>

  <Accordion title="Quando usar billing do tipo volume?">
    Use quando quiser cobrar clientes com base no **número de transações processadas** — 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.

    ```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": "conta-cliente",
      "creditAccountAlias": "conta-receita-volume"
    }
    ```

    <Note>O último tier deve ser **ilimitado** (sem `maxQuantity`). Não pode haver lacunas ou sobreposições entre tiers.</Note>
  </Accordion>

  <Accordion title="Quando usar billing do tipo maintenance?">
    Use quando quiser cobrar uma **taxa fixa periódica por conta** — por exemplo, uma mensalidade por conta ativa. Você especifica o escopo (`segmentId`, `portfolioId` ou `aliases`) e o valor da taxa.

    ```json theme={null}
    {
      "type": "maintenance",
      "feeAmount": "15.00",
      "assetCode": "BRL",
      "maintenanceCreditAccount": "conta-receita-manutencao",
      "accountTarget": {
        "segmentId": "seg_clientes_premium"
      }
    }
    ```

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

  <Accordion title="Como funcionam os tiers no billing de volume?">
    Os tiers definem a **faixa de preço por unidade** conforme o volume aumenta. Regras obrigatórias:

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

    **Exemplo de tiers corretos:**

    ```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** — um número de transações que não são cobradas antes de os tiers começarem a ser aplicados. Útil para modelos de precificação com um volume mínimo incluso.

    **Exemplo:** `freeQuota: 100` significa que as primeiras 100 transações do período não são tarifadas.
  </Accordion>

  <Accordion title="O que são discountTiers?">
    São faixas de desconto aplicáveis ao billing de volume. Permitem reduzir o valor cobrado com base em critérios adicionais, complementando a lógica dos `tiers` principais.
  </Accordion>

  <Accordion title="O que é countMode no billing de volume?">
    Define **como as transações são contadas**:

    * `perRoute`: conta transações por rota (ex: total de PIX aprovados).
    * `perAccount`: conta transações por conta individualmente.
  </Accordion>
</AccordionGroup>

### Cálculo e Estimativa de Taxas

<AccordionGroup>
  <Accordion title="Qual a diferença entre /v1/fees e /v1/estimates?">
    | Endpoint             | Quando usar                                                                                                                                                                                                                                             |
    | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `POST /v1/fees`      | Calcular a taxa **real** de uma transação em curso. O sistema busca automaticamente os pacotes aplicáveis com base no ledger, segment, rota e valor. Veja a [referência da API Calculate Fees](/pt/reference/midaz/plugins/fees-engine/calculate-fees). |
    | `POST /v1/estimates` | **Simular** a taxa de um pacote específico antes de confirmar a transação. Útil para mostrar ao usuário final o custo antes de executar. Veja a [referência da API Simulate Fees](/pt/reference/midaz/plugins/fees-engine/simulate-fees).               |
  </Accordion>

  <Accordion title="Como funciona o /v1/fees?">
    O endpoint recebe os dados da transação e o sistema **busca automaticamente** os pacotes que se aplicam, considerando:

    * `ledgerId` — obrigatório
    * `segmentId` — opcional
    * `transactionRoute` — opcional
    * Valor da transação — comparado com `minimumAmount`/`maximumAmount` do pacote

    As taxas de todos os pacotes correspondentes são calculadas e retornadas.
  </Accordion>

  <Accordion title="E o /v1/estimates?">
    O `/v1/estimates` permite simular a taxa de um **pacote específico** (`packageId`), sem precisar de uma transação real. Ideal para:

    * Exibir o custo estimado para o usuário antes de confirmar.
    * Testar configurações de pacotes recém-criados.
    * Construir simuladores de tarifas no seu produto.
  </Accordion>

  <Accordion title="Posso usar /v1/estimates em produção para mostrar tarifas ao usuário final?">
    Sim. O `/v1/estimates` é um endpoint de leitura — não altera estado, não registra transações. É seguro usar em fluxos de UX para mostrar o custo antes da confirmação.
  </Accordion>

  <Accordion title="Como calcular o billing?">
    Após configurar os Billing Packages, use o endpoint:

    ```
    POST /v1/billing/calculate
    ```

    Esse endpoint processa as regras configuradas e gera as cobranças para o período informado. Veja a [referência da API Calculate Billing](/pt/reference/midaz/plugins/fees-engine/calculate-billing).
  </Accordion>
</AccordionGroup>

### Erros Comuns

<AccordionGroup>
  <Accordion title="&#x22;Priority 1 must use originalAmount&#x22; — o que significa?">
    A taxa de `priority: 1` deve obrigatoriamente ter `referenceAmount: "originalAmount"`. Isso ocorre porque ela é a primeira a ser calculada — não há taxas anteriores sobre as quais basear o cálculo.

    **Correção:**

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

  <Accordion title="&#x22;isDeductibleFrom requires originalAmount&#x22; — como resolver?">
    Taxas com `isDeductibleFrom: true` só podem usar `referenceAmount: "originalAmount"`. Altere o campo:

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

  <Accordion title="&#x22;Flat fee value cannot exceed minimumAmount&#x22; — por quê?">
    Quando `isDeductibleFrom: true` e o tipo é `flat`, o valor da taxa não pode ser maior que o `minimumAmount` do pacote. Isso evita cenários onde a taxa supera o valor mínimo da própria transação.

    **Exemplo:** Se `minimumAmount: 100`, a taxa flat não pode ser maior que R\$ 100.
  </Accordion>

  <Accordion title="&#x22;Percentage value cannot exceed 100&#x22; — quando ocorre?">
    Esse erro ocorre quando `isDeductibleFrom: true` e o tipo é `percentage` com valor acima de 100. Uma taxa percentual dedutível de 100% zeraria o valor da transação — valores acima disso são inválidos.
  </Accordion>

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

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

  <Accordion title="&#x22;Last tier must be unbounded&#x22; — o que isso significa?">
    O último tier no billing de volume precisa ser **sem limite superior** (sem `maxQuantity`). Isso garante que transações acima da maior faixa definida ainda sejam precificadas.
  </Accordion>

  <Accordion title="&#x22;accountTarget must have exactly one of: segmentId, portfolioId, aliases&#x22;">
    No billing do tipo `maintenance`, o campo `accountTarget` aceita apenas **uma** das três opções. Não combine campos:

    ```json theme={null}
    // ❌ Errado
    "accountTarget": {
      "segmentId": "seg_abc",
      "portfolioId": "port_xyz"
    }

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

  <Accordion title="&#x22;aliases&#x22; no accountTarget tem algum limite?">
    Sim. O campo `aliases` aceita no máximo **100 aliases** por Billing Package do tipo `maintenance`.
  </Accordion>

  <Accordion title="&#x22;flatFee requires exactly 1 calculation of type flat&#x22;">
    O `applicationRule: "flatFee"` aceita exatamente 1 cálculo, e esse cálculo deve ser do tipo `flat`. Não use `percentage` com `flatFee`.

    ```json theme={null}
    // ✅ Correto
    "calculationModel": {
      "applicationRule": "flatFee",
      "calculations": [{ "type": "flat", "value": "10.00" }]
    }
    ```
  </Accordion>

  <Accordion title="&#x22;percentual requires exactly 1 calculation of type percentage&#x22;">
    Análogo ao `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 para funcionar — ele precisa de valores para comparar. Forneça ao menos um `flat` e um `percentage`.
  </Accordion>

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

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

  <Accordion title="Um registro deletado pode ser recuperado?">
    Tecnicamente, os registros são soft-deleted (marcados com `deletedAt`) e não são removidos do banco. No entanto, a API não expõe endpoints de restauração por padrão. Consulte a equipe Lerian caso precise recuperar um registro deletado acidentalmente. Para a lista completa de códigos de erro, veja a [referência de Códigos de Erro](/pt/reference/midaz/plugins/fees-engine/fee-engine-error-list).
  </Accordion>
</AccordionGroup>