Regras de tarifas

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

Um fee schedule define quanto de tarifa calcular — a moeda, o arredondamento e um ou mais fee items (fixo, percentual, escalonado ou baseado em expressão).
Uma fee rule decide quando um fee schedule se aplica. Ela pertence a um contexto de conciliação, aponta para um lado de correspondência e carrega predicados que os metadados de uma transação devem satisfazer. Quando os predicados correspondem, a regra seleciona seu fee schedule.

Quando a normalização de tarifas está habilitada e as moedas da transação e do schedule correspondem, modelar as tarifas esperadas dessa forma permite que o Matcher considere cobranças previsíveis antes de comparar transações.

O que o tratamento de tarifas resolve

A conciliação falha quando um lado de uma transação inclui tarifas ou cobranças que o outro lado não registra. Um gateway de pagamento deduz uma taxa de processamento antes de liquidar. Um banco cobra uma tarifa de transferência bancária. Um adquirente desconta taxas dos pagamentos. Sem tarifas modeladas, o Matcher trata essas diferenças como discrepâncias de valor e gera exceções — mesmo quando a diferença é esperada e documentada. Os fee schedules descrevem a cobrança, e as fee rules selecionam quando usá-la durante a normalização de tarifas habilitada.

Como as regras e os schedules se encaixam

Uma fee rule não contém o valor da tarifa nem o cálculo em si. Ela referencia um fee schedule por ID e o aplica às transações que seus predicados selecionam.

Um fee schedule é criado uma vez no nível do tenant e pode ser reutilizado por muitas regras em muitos contextos.
Uma fee rule é criada 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 tarifas habilitada, ele avalia as fee rules do lado relevante na ordem de priority (a mais baixa primeiro). A primeira regra correspondente seleciona o schedule referenciado.

Essa separação significa que você altera como uma tarifa é calculada editando o schedule, e altera quando ela se aplica editando a regra — sem tocar no outro.

Uma fee rule sozinha não altera os valores de comparação. A avaliação de fee rules só afeta a conciliação de tarifas quando o contexto define feeNormalization como NET ou GROSS, o lado relevante tem regras e as moedas da transação e do schedule correspondem.

Estrutura de uma fee rule

Uma fee rule pertence a um contexto e tem os seguintes campos.

Campo	Tipo	Descrição
`side`	Enum	A qual lado de correspondência a regra se aplica: `LEFT`, `RIGHT` ou `ANY`. `ANY` corresponde a transações em qualquer um dos lados.
`feeScheduleId`	UUID	O fee schedule que esta regra aplica quando seus predicados correspondem.
`name`	String	Nome legível da fee rule.
`priority`	Integer	Prioridade de avaliação; números mais baixos são avaliados primeiro. Deve ser único dentro do contexto. As regras `LEFT`, `RIGHT` e `ANY` compartilham o mesmo espaço de prioridade.
`predicates`	Array	Predicados (unidos por AND) que os metadados de uma transação devem satisfazer para que esta regra se aplique.

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 (ex., `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 strings sem distinção entre maiúsculas e minúsculas com um único `value`.
`NEQ`	Para um campo presente, desigualdade numérica quando ambos os valores podem ser convertidos em decimais; caso contrário, desigualdade de strings sem distinção entre maiúsculas e minúsculas.
`IN`	Corresponde a qualquer entrada em `values`.
`EXISTS`	Verifica que o campo está presente (nenhum valor necessário).
`GT` / `GTE` / `LT` / `LTE`	Comparação numérica do campo contra um único `value` decimal.
`BETWEEN`	Pertencimento numérico inclusivo em `values` = `[lo, hi]` (com `lo <= hi`).

Campos ausentes são avaliados como false para todos os operadores, exceto EXISTS.

Estrutura de um fee schedule

Um fee schedule é 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 do schedule.
`currency`	String	Moeda ISO 4217 na qual os valores do schedule são denominados.
`applicationOrder`	Enum	Como os items se combinam: `PARALLEL` aplica cada item à mesma base bruta; `CASCADING` aplica cada item ao líquido restante após os items 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 fee items que compõem o schedule (pelo menos um obrigatório).

Fee items

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%), 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 substitui qualquer chave de metadados chamada `gross`; os demais identificadores são resolvidos a partir dos metadados.

Gerenciamento de fee schedules

Os fee schedules têm escopo de tenant e são gerenciados de forma independente de qualquer contexto.

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

Criar um fee schedule

Este schedule calcula uma taxa 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 API: Create fee schedule · List fee schedules · Retrieve fee schedule · Update fee schedule · Delete fee schedule

Simular um fee schedule

Antes de conectar um schedule a uma regra, simule-o 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 o netAmount, o totalFee e um detalhamento por item.

Referência API: Simulate fee calculation

Um fee schedule não pode ser excluído enquanto uma fee rule ou o histórico de variações de tarifas o referencia. A solicitação retorna 409 Conflict com o código MTCH-0108 e inclui os contextos que bloqueiam a exclusão em errors, em fee-schedule.delete.blocking-contexts. Remova ou reaponte primeiro as referências de regras atuais. As referências do histórico de variações continuam bloqueando a exclusão.

Gerenciamento de fee rules

As fee rules são criadas dentro de um contexto e referenciam um fee schedule.

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

Criar uma fee rule

Esta regra aplica o fee schedule criado acima às transações do lado direito cujos metadados institution sejam 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 API: Create fee rule · List fee rules · Retrieve fee rule · Update fee rule · Delete fee rule

Fluxo de ponta a ponta

Juntando tudo, o tratamento de tarifas esperadas segue três passos:

Crie o fee schedule

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

Crie a fee rule no contexto

Dentro do contexto de conciliação, crie uma fee rule com POST /v1/contexts/{contextId}/fee-rules. Defina feeScheduleId como o id do schedule, 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 feeNormalization do contexto como NET ou GROSS. Durante a correspondência, o Matcher avalia as regras de cada lado relevante na ordem de priority. Uma regra correspondente só altera o valor de comparação quando seu schedule e a transação usam a mesma moeda.

Melhores práticas

Reutilize schedules entre contextos

Um fee schedule tem escopo de tenant e pode ser referenciado por muitas regras. Defina um schedule uma vez (ex., “Card Processing - Visa”) e aponte regras de diferentes contextos para ele. Editar o schedule atualiza todas as regras que o usam.

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 que uma regra estreita vença antes de um fallback amplo.

Delimite as regras com predicados precisos

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

Simule antes de conectar um schedule a uma regra

Use POST /v1/fee-schedules/{scheduleId}/simulate para confirmar que um schedule produz a tarifa esperada para valores representativos antes de referenciá-lo a partir de uma regra.

Reaponte as regras antes de excluir um schedule

Um schedule referenciado por uma regra ou pelo histórico de variações de tarifas não pode ser excluído (409 MTCH-0108). A resposta de conflito lista os contextos que o bloqueiam em errors, em fee-schedule.delete.blocking-contexts. Atualize ou remova primeiro as referências de regras atuais; as referências históricas de variações continuam bloqueando a exclusão.

Próximos passos

Regras de conciliação

Configure como as transações são comparadas depois que as tarifas esperadas são consideradas.

Roteamento de exceções

Revise a atribuição explícita, o despacho e os callbacks das exceções que o tratamento de tarifas não cobre.

Fee schedules API

Referência completa da API para os endpoints de fee schedules.

Fee rules API

Referência completa da API para os endpoints de fee rules.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Regras de tarifas

O que o tratamento de tarifas resolve

Como as regras e os schedules se encaixam

Estrutura de uma fee rule

Predicados

Estrutura de um fee schedule

Fee items

Gerenciamento de fee schedules

Criar um fee schedule

Simular um fee schedule

Gerenciamento de fee rules

Criar uma fee rule

Fluxo de ponta a ponta

Melhores práticas

Próximos passos

Regras de conciliação

Roteamento de exceções

Fee schedules API

Fee rules API

​O que o tratamento de tarifas resolve

​Como as regras e os schedules se encaixam

​Estrutura de uma fee rule

​Predicados

​Estrutura de um fee schedule

​Fee items

​Gerenciamento de fee schedules

​Criar um fee schedule

​Simular um fee schedule

​Gerenciamento de fee rules

​Criar uma fee rule

​Fluxo de ponta a ponta

​Melhores práticas

​Próximos passos

Regras de conciliação

Roteamento de exceções

Fee schedules API

Fee rules API

O que o tratamento de tarifas resolve

Como as regras e os schedules se encaixam

Estrutura de uma fee rule

Predicados

Estrutura de um fee schedule

Fee items

Gerenciamento de fee schedules

Criar um fee schedule

Simular um fee schedule

Gerenciamento de fee rules

Criar uma fee rule

Fluxo de ponta a ponta

Melhores práticas

Próximos passos