> ## 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. # Usando o Fees Engine > Use o Fees Engine para aplicar pacotes de tarifas por transação e pacotes de faturamento por período que correspondam aos seus ledgers, segmentos e rotas de transação. O Fees Engine aplica tarifas por transação e calcula cobranças de faturamento periódicas. Este guia cobre os dois fluxos: pacotes de tarifas (por transação) e pacotes de faturamento (por período). Não sabe qual usar? Os pacotes de tarifas aplicam cobranças no momento da transação. Os pacotes de faturamento calculam cobranças ao longo de um período (diário ou mensal) para o seu orquestrador executar. Você pode usar os dois simultaneamente. ## Pacotes de tarifas: fluxo por transação *** Os pacotes de tarifas aplicam cobranças de forma síncrona quando você cria uma transação. Esta seção mostra o processo, da configuração da tarifa até os resultados. ### Passo 1 - Crie seus pacotes de tarifas Primeiro, configure **pacotes de tarifas** que definem como o mecanismo aplica as tarifas. Use o endpoint [Criar um Pacote](/pt/reference/products/midaz/v2/create-package). Cada pacote contém um conjunto de regras de tarifa e critérios de correspondência. Você pode adaptar os pacotes a diferentes ledgers, segmentos e rotas de transação com estes campos: * **transactionRoute** - Identifica a natureza da transação, quando você precisa de correspondência no nível da rota. * **segmentId** - Agrupa clientes ou tipos de produto, quando você precisa de correspondência no nível do segmento. * **Escopo do ledger** - A URL da requisição identifica qual ledger registra a transação; não envie `ledgerId` no corpo do pacote. * Valor **mínimo** e **máximo** - Limites opcionais para a aplicação da tarifa. * **routeFrom** / **routeTo** - Definem como cada tarifa se move pelos fluxos contábeis. Essa flexibilidade permite aplicar tarifas distintas para cada cenário, de configurações baseadas em conta a configurações baseadas em valor. **Gerenciando pacotes** Os seguintes endpoints também estão disponíveis para você gerenciar os pacotes: * [Listar Pacotes](/pt/reference/products/midaz/v2/get-all-packages) - Lista todos os pacotes criados. * [Buscar um Pacote](/pt/reference/products/midaz/v2/get-package-by-id) - Busca informações de um pacote específico. * [Atualizar um Pacote](/pt/reference/products/midaz/v2/update-package) - Atualiza as informações de um pacote específico. * [Excluir um Pacote](/pt/reference/products/midaz/v2/delete-package) - Faz o soft delete de um pacote. ### (opcional) Passo 2 - Execute uma estimativa Para visualizar como um pacote de tarifas se comporta antes de confirmar uma transação real, use o endpoint [Estimar Tarifas de Transação](/pt/reference/products/midaz/v2/estimate-fee-calculation). Essa estimativa ajuda a validar: * Quais regras de tarifa se aplicam. * Como o pacote vai se comportar com os valores informados. * Se alguma isenção se aplica. ### Passo 3 - Crie uma transação Depois de configurar os pacotes, crie a transação com o endpoint [criar uma transação](/pt/reference/products/midaz/v1/create-transaction-json). Informe a mesma organização e o mesmo ledger na URL da requisição, e inclua os campos de correspondência configurados, como `transactionRoute` ou `segmentId`, para que o mecanismo possa avaliar o pacote correto. ### Passo 4 - O Fees Engine entra em ação O Fees Engine é executado no mesmo processo quando o Midaz cria a transação. Ele avalia se um pacote se aplica, com base em: * **transactionRoute**, quando configurado * **segmentId**, quando configurado * **Escopo do ledger a partir da URL da requisição** * Valor **mínimo** e **máximo** * **waivedAccounts**, quando configurado para isenções de tarifa O Fees Engine seleciona apenas um pacote por transação. ### Passo 5 - Verifique as isenções O sistema verifica: * Se o valor da transação está fora do intervalo permitido. * Se a conta de origem é isenta. Se qualquer uma das condições for verdadeira, o Fees Engine não aplica tarifas e a transação segue normalmente. ### Passo 6 - Cálculo e aplicação da tarifa Se um pacote se aplica, o Fees Engine: * Calcula os valores da tarifa com base no `applicationRule` selecionado. * Aplica as tarifas proporcionalmente entre as contas, se necessário. * Usa `isDeductibleFrom` para definir se adiciona ou deduz a tarifa. * Direciona as tarifas para o `creditAccount` correto com o `routeFrom` e o `routeTo` configurados. * Retorna o resultado completo da transação junto com o `packageAppliedID` nos metadados. ### Passo 7 - Atualizações no ledger Depois que o Fees Engine calcula as tarifas, o componente **Transactions** assume. Ele processa: * Débitos das contas de origem * Créditos para os destinos da tarifa * Detalhamento da tarifa por rota e conta O ledger armazena cada movimento para rastreabilidade e auditabilidade completas. ### Passo 8 - Revise e confirme Depois da execução, você pode: * Inspecionar a transação final e os valores por conta. * Confirmar qual pacote de tarifas foi aplicado. * Verificar todos os movimentos de tarifa por meio dos metadados e dos registros do ledger. ## Por que estimar uma transação? *** As estimativas permitem visualizar como um pacote de tarifas específico se comporta, sem executar uma transação real nem gravar no ledger. Use estimativas quando: * Você quer testar um pacote específico. * Você depura regras de tarifa ou limites. * Você quer validar isenções, intervalos de valor ou divisões proporcionais. * Você precisa de uma visualização antes de criar uma transação real. * Você constrói uma interface e quer mostrar tarifas estimadas. O Fees Engine oferece o endpoint [Estimar Tarifas de Transação](/pt/reference/products/midaz/v2/estimate-fee-calculation) para essa finalidade. Você informa um `packageId`, e o endpoint retorna o que aconteceria se **esse pacote exato** fosse aplicado. ### O que você obtém com uma estimativa? * Uma estimativa completa das regras de tarifa. * Quais contas o mecanismo cobraria. * Como o mecanismo dividiria a tarifa. * Nenhum impacto no ledger. Use estimativas quando você ainda não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma visualização clara da tarifa. ## Erros comuns *** O Fees Engine valida cada requisição quanto à consistência e à lógica correta da tarifa. Abaixo estão os problemas mais frequentes que você pode ver ao criar pacotes ou processar transações. | Code | Title | Message | | :------- | :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FEE-0002 | Campos ausentes na requisição | Sua requisição está sem um ou mais campos obrigatórios. Consulte a documentação para garantir que todos os campos necessários estejam incluídos na sua requisição. | | FEE-0012 | Entidade não encontrada | Nenhuma entidade foi encontrada para o ID informado. Use o ID correto da entidade que você está tentando gerenciar. | | FEE-0013 | Prioridade de tarifa inválida | O campo de prioridade nas tarifas é inválido. O campo não pode ser repetido. | | FEE-0015 | minimumAmount maior que maximumAmount | O valor de minimumAmount é maior que maximumAmount. | | FEE-0022 | Falha ao calcular a tarifa | Erro ao calcular a tarifa de uma transação. | | FEE-0024 | originalAmount é obrigatório quando priority é um | Para Priority igual a um, referenceAmount deve ser 'originalAmount' para a tarifa. | | FEE-0025 | Falha ao aplicar a regra: flatFee ou percentual | O applicationRule flatFee ou percentual deve ter exatamente 1 cálculo para a tarifa. | | FEE-0035 | Sobreposição do intervalo de valor do pacote | O maximumAmount e o minimumAmount do novo pacote se sobrepõem ao intervalo de valor de um pacote existente. | Quer a lista completa de códigos de erro? Você encontra na página [Lista de erros do Fees Engine](/pt/reference/products/midaz/v2/estimate-fee-calculation) na [Referência da API](/pt/reference/introduction). ## Pacotes de faturamento: fluxo por período *** Os pacotes de faturamento calculam cobranças com base no volume acumulado de transações ou na manutenção por conta ao longo de um período de faturamento. Diferente dos pacotes de tarifas, o seu orquestrador aciona o faturamento. Ele decide quando calcular e executa as cobranças resultantes. ### Passo 1: Crie os pacotes de faturamento Configure pacotes de faturamento que definem suas regras de cobrança periódica. Cada pacote é do tipo **volume** ou **manutenção**. **Exemplo de pacote de volume**, uma cobrança por Pix enviado com precificação em camadas: ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages Body: { "label": "Pix Send Monthly Billing", "description": "Monthly volume billing for Pix transactions", "type": "volume", "enable": true, "eventFilter": { "transactionRoute": "pix-send", "status": "APPROVED" }, "pricingModel": "tiered", "tiers": [ { "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" }, { "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" }, { "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" } ], "freeQuota": 10, "discountTiers": [ { "minQuantity": 200, "discountPercentage": "5.00" }, { "minQuantity": 400, "discountPercentage": "10.00" } ], "countMode": "perRoute", "assetCode": "BRL", "debitAccountAlias": "client-wallet", "creditAccountAlias": "fees-revenue" } ``` **Exemplo de pacote de manutenção**, uma tarifa mensal por conta PF ativa: ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages Body: { "label": "PF Account Maintenance", "description": "Monthly maintenance fee for active PF accounts", "type": "maintenance", "enable": true, "feeAmount": "9.90", "assetCode": "BRL", "maintenanceCreditAccount": "fees-maintenance-pf", "accountTarget": { "segmentId": "seg_pf_01HZ..." } } ``` ### Passo 2: Acione o cálculo do faturamento Chame `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` com o período de faturamento. A URL identifica o ledger. O mecanismo avalia todos os pacotes de faturamento ativos que correspondem aos critérios. ```json theme={null} POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate Body: { "period": "2026-03", "type": "volume" } ``` O campo `period` aceita três formatos: `YYYY-MM` (mensal), `YYYY-Www` (semanal, por exemplo, `2026-W13`), e `YYYY-MM-DD` (diário). O campo `type` é opcional. Use `"volume"` ou `"maintenance"` para restringir o cálculo a um tipo. Omita-o para calcular os dois tipos em uma única chamada. ### Passo 3: Receba os resultados do cálculo O mecanismo retorna um array de resultados. Cada resultado contém um `transactionPayload` pronto para enviar ao Midaz. Cada resultado inclui: * O pacote de faturamento que o gerou. * Os valores calculados com detalhamento completo (camadas aplicadas, descontos, cota gratuita subtraída). * Um payload de transação com `source.from` (lançamentos de débito) e `distribute.to` (lançamentos de crédito). * Metadados de auditoria estruturados para rastreabilidade. ### Passo 4: Execute as cobranças Envie cada `transactionPayload` para o Midaz via `POST /transactions/json` para criar as transações de faturamento reais. Esta etapa é responsabilidade do seu orquestrador: Flowker, um cron job, ou qualquer outro sistema. O mecanismo de faturamento calcula e retorna resultados. Ele não cria transações no Midaz. O seu orquestrador controla quando e como executa as cobranças. ### Passo 5: Revise e concilie Depois de executar as cobranças: * Verifique se as transações criadas no Midaz correspondem aos resultados do cálculo de faturamento. * Use os metadados de auditoria de cada resultado para a conciliação. * O cálculo de faturamento é stateless. Você pode executá-lo novamente para o mesmo período para verificar os resultados. ### Gerenciando pacotes de faturamento Use estes endpoints para gerenciar pacotes de faturamento existentes: * `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: Lista todos os pacotes de faturamento. * `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Busca um pacote de faturamento específico. * `PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Atualiza um pacote de faturamento (apenas `label`, `description`, `enable`). * `DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Faz o soft delete de um pacote de faturamento. Se algum pacote falhar durante o cálculo, a operação inteira falha e não retorna resultados parciais. O cálculo de faturamento segue uma política tudo ou nada. Corrija o pacote com falha e execute novamente.