Pular para o conteúdo principal
Seja aplicando taxas em produção ou simulando-as antecipadamente, o Fees Engine oferece controle total e flexibilidade. Este guia acompanha você por todo o ciclo de vida, desde a criação de pacotes até a revisão dos resultados das taxas.
Não tem certeza se deve calcular ou simular? Vamos mostrar como escolher entre os dois com base no seu caso de uso.

​
Uso típico

Veja como o processo funciona, desde a configuração das taxas até a visualização dos resultados.

​
Passo 1 - Crie seus pacotes de taxas

Comece configurando pacotes de taxas que definem como as taxas são aplicadas. Para isso, use o endpoint Criar um Pacote. Cada pacote contém um conjunto de regras de taxas e critérios de correspondência. Você pode personalizar pacotes para diferentes segmentos ou ledgers usando:
  • transactionRoute – Identifica a natureza da transação.
  • segmentId – Agrupa clientes ou tipos de produto.
  • ledgerId – Define qual ledger registra a transação.
  • Valor mínimo e máximo – Limites opcionais para aplicação de taxas.
  • routeFrom / routeTo – Definem como cada taxa se move nos fluxos contábeis.
Essa flexibilidade permite aplicar taxas distintas por cenário, desde configurações baseadas em conta até baseadas em valor. Gerenciando Pacotes Os seguintes endpoints também estão disponíveis para você gerenciar os pacotes:

​
(opcional) Passo 2 - Execute uma simulação

Se você deseja visualizar como um pacote de taxas se comportaria antes de confirmar uma transação real, use o endpoint Simular Taxas de Transação. Essa simulação ajuda a validar:
  • Quais regras de taxas serão acionadas.
  • Como o pacote se comportará com os valores informados.
  • Se alguma isenção se aplica.

​
Passo 3 - Crie uma transação

Uma vez que os pacotes estejam configurados, acione a transação real usando o endpoint criar uma transação. Inclua o transactionRoute, segmentId e ledgerId apropriados para que o motor possa avaliar o pacote correspondente.

​
Passo 4 - O Fees Engine entra em ação

O Fees Engine automaticamente envia uma chamada para o endpoint Calcular Taxas para um Pacote e avalia se um pacote se aplica com base em:
  • transactionRoute
  • segmentId
  • ledgerId
  • Valor mínimo e máximo
  • waivedAccounts (para isenções de taxas)
Apenas um pacote é selecionado por transação.

​
Passo 5 - Verificar isenções

O sistema verifica:
  • Se o valor da transação está fora da faixa permitida.
  • Se a conta de origem é isenta.
Se qualquer uma das condições for atendida, nenhuma taxa é aplicada e a transação prossegue normalmente.

​
Passo 6 - Cálculo e aplicação de taxas

Se um pacote for aplicado, o Fees Engine:
  • Calcula os valores das taxas com base na applicationRule selecionada.
  • Aplica taxas proporcionalmente entre contas, se necessário.
  • Usa isDeductibleFrom para definir se a taxa é adicionada ou deduzida.
  • Roteia as taxas para a creditAccount correta usando os routeFrom e routeTo configurados.
  • Retorna o resultado completo da transação junto com o packageAppliedID nos metadados.

​
Passo 7 - Atualizações no ledger

Após o cálculo das taxas, o componente de Transações assume. Ele processa:
  • Débitos das contas de origem
  • Créditos para os destinos das taxas
  • Detalhamento das taxas por rota e conta
Cada movimentação é armazenada no ledger para rastreabilidade e auditabilidade completas.

​
Passo 8 - Revisar e confirmar

Após a execução, você pode:
  • Inspecionar a transação final e os valores por conta.
  • Confirmar o pacote de taxas que foi aplicado.
  • Verificar todas as movimentações de taxas via metadados e registros do ledger.

​
Por que simular uma transação?

Simulações permitem visualizar como um pacote de taxas específico se comporta, sem executar uma transação real ou gravar no ledger. Use simulações quando:
  • Você quiser testar um pacote específico.
  • Estiver depurando regras de taxas ou limites.
  • Quiser validar isenções, faixas de valor ou divisões proporcionais.
  • Precisar de uma prévia antes de criar uma transação real.
  • Estiver construindo uma interface e quiser mostrar taxas estimadas.
O Fees Engine fornece o endpoint Simular Taxas de Transação para esse propósito. Você só precisa passar um packageId e o endpoint retorna o que aconteceria se aquele pacote exato fosse aplicado.

​
O que você obtém com uma simulação?

  • Uma simulação completa das regras de taxas.
  • Quais contas seriam cobradas.
  • Como a taxa seria dividida.
  • Sem impacto no ledger.
Use simulações quando você não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma prévia clara das taxas.

​
Erros comuns

O Fees Engine valida cada requisição para garantir consistência e lógica correta de taxas. Abaixo estão os problemas mais frequentes que você pode encontrar ao criar pacotes ou processar transações.
CódigoTítuloMensagem
FEE-0002Missing fields in requestYour request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
FEE-0012Entity not foundNo entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
FEE-0013Invalid fee priorityThe priority field in fees is invalid. Field can not be repeated.
FEE-0015minimumAmount greater than maximumAmountminimumAmount value is greater than maximumAmount.
FEE-0022Failed to calculate feeError to make the calculation of a fee about a transaction.
FEE-0024originalAmount is required when priority is oneFor Priority equals to one, referenceAmount must be ‘originalAmount’ for fee.
FEE-0025Failed to apply rule: flatFee or percentualapplicationRule flatFee or percentual must have exactly 1 calculation for Fee.
FEE-0036Package amount range overlapThe maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.
Quer a lista completa de códigos de erro? Você encontra na página Lista de erros do Fees Engine na Referência da API.