Regras de tarifa

O tratamento de tarifas no Matcher é dividido em duas entidades:

Uma tabela de tarifas define quanto de tarifa calcular: a moeda, o arredondamento e um ou mais itens de tarifa (fixo, percentual, escalonado ou baseado em expressão).
Uma regra de tarifa decide quando uma tabela de tarifas se aplica. Ela pertence a um contexto de conciliação, aponta para um lado da correspondência e carrega predicados que os metadados de uma transação devem satisfazer. Quando os predicados batem, a regra seleciona a tabela de tarifas dela.

Modelar as tarifas esperadas assim permite ao Matcher considerar encargos previsíveis antes de comparar transações. Isso vale quando você habilita a normalização de tarifa e as moedas da transação e da tabela coincidem.

O que o tratamento de tarifas resolve

A conciliação falha quando um lado de uma transação inclui tarifas ou encargos que o outro lado não registra. Um gateway de pagamento desconta uma tarifa de processamento antes de liquidar. Um banco cobra uma tarifa de transferência. Um adquirente compensa tarifas contra os repasses. Sem tarifas modeladas, o Matcher trata essas diferenças como divergências de valor e gera exceções, mesmo quando você espera e documenta a diferença. As tabelas de tarifas descrevem o encargo, e as regras de tarifa escolhem quando usá-lo durante a normalização de tarifa habilitada.

Como as regras e as tabelas se encaixam

Uma regra de tarifa não contém o valor nem o cálculo da tarifa. Ela referencia uma tabela de tarifas por ID e a aplica às transações que os predicados dela selecionam.

Você cria uma tabela de tarifas uma vez no nível do tenant. Muitas regras em muitos contextos podem reusá-la.
Você cria uma regra de tarifa dentro de um contexto. Ela define um side, um feeScheduleId, uma priority e uma lista de predicates.
Quando o Matcher processa um contexto com a normalização de tarifa habilitada, ele avalia as regras de tarifa do lado relevante em ordem de priority (a menor primeiro). A primeira regra que bate seleciona a tabela referenciada.

Essa separação significa que você muda como uma tabela de tarifas calcula uma tarifa editando a tabela. Você muda quando a tarifa se aplica editando a regra. Nenhuma das edições toca na outra.

Uma regra de tarifa sozinha não muda os valores de comparação. A avaliação de regras de tarifa afeta a conciliação de tarifas apenas quando o contexto define feeNormalization como NET ou GROSS, o lado relevante tem regras e as moedas da transação e da tabela coincidem.

Estrutura da regra de tarifa

Uma regra de tarifa pertence a um contexto e tem os campos a seguir.

Campo	Tipo	Descrição
`side`	Enum	A qual lado da correspondência a regra se aplica: `LEFT`, `RIGHT` ou `ANY`. `ANY` combina com transações de qualquer um dos lados.
`feeScheduleId`	UUID	A tabela de tarifas que esta regra aplica quando os predicados dela batem.
`name`	String	Nome legível da regra de tarifa.
`priority`	Integer	Prioridade de avaliação; números menores são avaliados primeiro. Deve ser única dentro do contexto. As regras `LEFT`, `RIGHT` e `ANY` compartilham o mesmo espaço de prioridade.
`predicates`	Array	Predicados (combinados com AND) que os metadados de uma transação devem satisfazer para esta regra se aplicar.

Predicados

Cada predicado testa um campo de metadados da transação com um operador.

Campo	Descrição
`field`	O campo de metadados da transação que o predicado testa (por exemplo `institution`).
`operator`	O operador de comparação (veja abaixo).
`value`	Valor único de comparação, usado por `EQUALS`, `NEQ` e pelos comparadores numéricos.
`values`	Lista de valores candidatos, usada por `IN` e `BETWEEN`.

Operadores disponíveis:

Operador	Significado
`EQUALS`	Igualdade de string sem diferenciar maiúsculas, com um único `value`.
`NEQ`	Para um campo presente, desigualdade numérica quando os dois valores convertem para decimais; caso contrário, desigualdade de string sem diferenciar maiúsculas.
`IN`	Combina com qualquer entrada em `values`.
`EXISTS`	Afirma que o campo está presente (sem precisar de valor).
`GT` / `GTE` / `LT` / `LTE`	Comparação numérica do campo contra um único `value` decimal.
`BETWEEN`	Pertencimento numérico inclusivo a `values` = `[lo, hi]` (com `lo <= hi`).

Os campos ausentes são avaliados como false para cada operador, exceto EXISTS.

Estrutura da tabela de tarifas

Uma tabela de tarifas é uma entidade no nível do tenant que calcula uma tarifa a partir de um valor bruto.

Campo	Tipo	Descrição
`name`	String	Nome legível da tabela.
`currency`	String	Moeda ISO 4217 em que os valores da tabela são denominados.
`applicationOrder`	Enum	Como os itens se combinam: `PARALLEL` aplica cada item à mesma base bruta; `CASCADING` aplica cada item ao líquido restante depois dos itens anteriores.
`roundingScale`	Integer	Número de casas decimais para as quais os valores de tarifa são arredondados.
`roundingMode`	Enum	Estratégia de arredondamento: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL` ou `TRUNCATE`.
`items`	Array	Um ou mais itens de tarifa que compõem a tabela (pelo menos um obrigatório).

Itens de tarifa

Cada item declara um name, uma priority (ordem de aplicação, relevante para CASCADING), um structureType e uma structure específica do tipo.

`structureType`	Formato de `structure`	Notas
`FLAT`	`{ "amount": "1.50" }`	Valor fixo.
`PERCENTAGE`	`{ "rate": "0.029" }`	`rate` é uma fração `0..1` da base (`0.029` = 2,9%), e não um valor percentual.
`TIERED`	`{ "tiers": [ { "rate": "0.01", "upTo": "1000" }, ... ] }`	A mesma semântica de fração `0..1` por taxa de faixa.
`EXPRESSION`	`{ "expression": "gross - desconto + multa" }`	Fórmula sobre identificadores (`+ - * /`, parênteses e as funções `days_late`, `days_between`, `max`, `min`, `abs`, `clamp`). `gross` é o valor base fornecido pelo motor e sobrepõe qualquer chave de metadados chamada `gross`; os outros identificadores são resolvidos a partir dos metadados. Uma fórmula que contém exatamente um `gross` escalado apenas por literais numéricos é tratada como taxa percentual e deve ficar dentro de `0..1` (`gross * 0.029` é válido; `gross * 2.9` é rejeitado). As outras fórmulas não têm limite.

Como gerenciar tabelas de tarifas

As tabelas de tarifas têm escopo de tenant e são gerenciadas independentemente de qualquer contexto.

Operação	Endpoint
Criar uma tabela de tarifas	`POST /v1/fee-schedules`
Listar tabelas de tarifas	`GET /v1/fee-schedules`
Recuperar uma tabela de tarifas	`GET /v1/fee-schedules/{scheduleId}`
Atualizar uma tabela de tarifas	`PATCH /v1/fee-schedules/{scheduleId}`
Excluir uma tabela de tarifas	`DELETE /v1/fee-schedules/{scheduleId}`
Simular um cálculo de tarifa	`POST /v1/fee-schedules/{scheduleId}/simulate`

Como criar uma tabela de tarifas

Esta tabela calcula uma tarifa de processamento de 2,9% sobre o valor bruto, denominada em BRL.

cURL

curl -X POST "https://api.matcher.example.com/v1/fee-schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Gateway Processing - 2.9%",
   "currency": "BRL",
   "applicationOrder": "PARALLEL",
   "roundingScale": 2,
   "roundingMode": "HALF_UP",
   "items": [
     {
       "name": "processing",
       "priority": 1,
       "structureType": "PERCENTAGE",
       "structure": { "rate": "0.029" }
     }
   ]
 }'

Referência da API:

Como simular uma tabela de tarifas

Antes de ligar uma tabela a uma regra, simule-a contra um valor bruto para confirmar a tarifa calculada.

cURL

curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "grossAmount": "100.00",
   "currency": "BRL"
 }'

A resposta retorna netAmount, totalFee e um detalhamento por item.

Referência da API: Simular cálculo de tarifa

Uma tabela de tarifas não pode ser excluída enquanto uma regra de tarifa ou o histórico de variação de tarifa a referenciar. A requisição de exclusão retorna 409 Conflict com o código MTCH-0108 e inclui os contextos bloqueadores em errors sob fee-schedule.delete.blocking-contexts. Remova ou reaponte antes as referências atuais das regras. As referências históricas de variação continuam bloqueando a exclusão.

Como gerenciar regras de tarifa

As regras de tarifa são criadas dentro de um contexto e referenciam uma tabela de tarifas.

Operação	Endpoint
Criar uma regra de tarifa	`POST /v1/contexts/{contextId}/fee-rules`
Listar as regras de tarifa de um contexto	`GET /v1/contexts/{contextId}/fee-rules`
Recuperar uma regra de tarifa	`GET /v1/fee-rules/{feeRuleId}`
Atualizar uma regra de tarifa	`PATCH /v1/fee-rules/{feeRuleId}`
Excluir uma regra de tarifa	`DELETE /v1/fee-rules/{feeRuleId}`

Como criar uma regra de tarifa

Esta regra aplica a tabela de tarifas criada acima às transações do lado direito cujos metadados de institution são iguais a Banco do Brasil.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/fee-rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "side": "RIGHT",
   "feeScheduleId": "550e8400-e29b-41d4-a716-446655440000",
   "name": "BB Right-Side Processing Fee",
   "priority": 0,
   "predicates": [
     {
       "field": "institution",
       "operator": "EQUALS",
       "value": "Banco do Brasil"
     }
   ]
 }'

Referência da API:

Fluxo de ponta a ponta

O tratamento de tarifas esperadas segue três etapas:

Crie a tabela de tarifas

Defina uma vez, no nível do tenant, como a tarifa é calculada, com POST /v1/fee-schedules. Opcionalmente valide-a com o endpoint de simulação. Anote o id retornado.

Crie a regra de tarifa no contexto

Dentro do contexto de conciliação, crie uma regra de tarifa com POST /v1/contexts/{contextId}/fee-rules. Defina feeScheduleId com o id da tabela, escolha o side, defina uma priority única e adicione os predicates que selecionam as transações às quais a tarifa se aplica.

Aplique durante a correspondência

Defina o feeNormalization do contexto como NET ou GROSS. Durante a correspondência, o Matcher avalia as regras de cada lado relevante em ordem de priority. Uma regra que bate muda o valor de comparação apenas quando a tabela dela e a transação usam a mesma moeda.

Boas práticas

Reutilize tabelas entre contextos

Uma tabela de tarifas tem escopo de tenant e pode ser referenciada por muitas regras. Defina uma tabela uma vez (por exemplo “Card Processing - Visa”) e aponte para ela as regras de contextos diferentes. Editar a tabela atualiza cada regra que a usa.

Mantenha as prioridades únicas e intencionais

As prioridades são únicas dentro de um contexto e compartilhadas entre as regras LEFT, RIGHT e ANY. Ordene-as da mais específica para a mais geral, para uma regra estreita vencer antes de um fallback amplo.

Delimite as regras com predicados precisos

Os predicados são combinados com AND e testados contra os metadados da transação. Combine operadores (EQUALS, IN, BETWEEN, EXISTS) para mirar exatamente as transações às quais uma tarifa se aplica e evitar atribuição indevida de tarifa.

Simule antes de ligar uma tabela a uma regra

Use POST /v1/fee-schedules/{scheduleId}/simulate para confirmar que uma tabela produz a tarifa esperada para valores representativos antes de referenciá-la em uma regra.

Reaponte as regras antes de excluir uma tabela

Uma tabela referenciada por uma regra ou pelo histórico de variação de tarifa não pode ser excluída (409 MTCH-0108). A resposta de conflito lista os contextos bloqueadores em errors sob fee-schedule.delete.blocking-contexts. Atualize ou remova antes as referências atuais das regras; as referências históricas de variação continuam bloqueando a exclusão.

Próximos passos

Regras de correspondência

Configure como o Matcher compara transações depois de considerar as tarifas esperadas.

Roteamento de exceções

Revise a atribuição explícita, o despacho e o comportamento de callback para exceções que o tratamento de tarifas não cobre.

API de tabelas de tarifas

Referência completa da API para os endpoints de tabela de tarifas.

API de regras de tarifa

Referência completa da API para os endpoints de regra de tarifa.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Regras de tarifa

O que o tratamento de tarifas resolve

Como as regras e as tabelas se encaixam

Estrutura da regra de tarifa

Predicados

Estrutura da tabela de tarifas

Itens de tarifa

Como gerenciar tabelas de tarifas

Como criar uma tabela de tarifas

Como simular uma tabela de tarifas

Como gerenciar regras de tarifa

Como criar uma regra de tarifa

Fluxo de ponta a ponta

Boas práticas

Próximos passos

Regras de correspondência

Roteamento de exceções

API de tabelas de tarifas

API de regras de tarifa

​O que o tratamento de tarifas resolve

​Como as regras e as tabelas se encaixam

​Estrutura da regra de tarifa

​Predicados

​Estrutura da tabela de tarifas

​Itens de tarifa

​Como gerenciar tabelas de tarifas

​Como criar uma tabela de tarifas

​Como simular uma tabela de tarifas

​Como gerenciar regras de tarifa

​Como criar uma regra de tarifa

​Fluxo de ponta a ponta

​Boas práticas

​Próximos passos

Regras de correspondência

Roteamento de exceções

API de tabelas de tarifas

API de regras de tarifa

O que o tratamento de tarifas resolve

Como as regras e as tabelas se encaixam

Estrutura da regra de tarifa

Predicados

Estrutura da tabela de tarifas

Itens de tarifa

Como gerenciar tabelas de tarifas

Como criar uma tabela de tarifas

Como simular uma tabela de tarifas

Como gerenciar regras de tarifa

Como criar uma regra de tarifa

Fluxo de ponta a ponta

Boas práticas

Próximos passos