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

# Regras de tarifa

> Configure tabelas de tarifas e regras de predicado. O Matcher confere as transações correspondidas contra a tarifa esperada e, com a normalização NET ou GROSS, ajusta os valores de comparação.

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 conferir as transações correspondidas contra a tarifa esperada. Com a normalização de tarifa habilitada, o Matcher também considera a tarifa antes de comparar transações, quando 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.

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

1. Você cria uma **tabela de tarifas** uma vez no nível do tenant. Muitas regras em muitos contextos podem reusá-la.
2. Você cria uma **regra de tarifa** dentro de um contexto. Ela define um `side`, um `feeScheduleId`, uma `priority` e uma lista de `predicates`.
3. Quando o Matcher processa um contexto, 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 *quando* a tarifa se aplica editando a regra, sem tocar na tabela. Editar uma tabela muda apenas o nome, a ordem de aplicação, a escala de arredondamento e o modo de arredondamento dela. Para mudar os itens ou a moeda, crie uma nova tabela e aponte o `feeScheduleId` da regra para ela.

> [!NOTE]
>
> Uma regra de tarifa sozinha não muda os valores de comparação. Ela os muda 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. Quando um contexto tem regras de tarifa, toda execução `COMMIT` também confere as transações correspondidas contra a tarifa esperada e gera exceções `FEE_VARIANCE`, `FEE_DATA_MISSING` ou `FEE_CURRENCY_MISMATCH`.

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

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

```bash cURL theme={null}
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" }
     }
   ]
 }'
```

> [!TIP]
>
> Referência da API:
>
> * [Criar tabela de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/create-fee-schedule.md)
> * [Listar tabelas de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/list-fee-schedules.md)
> * [Recuperar tabela de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-fee-schedule.md)
> * [Atualizar tabela de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/update-fee-schedule.md)
> * [Excluir tabela de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/delete-fee-schedule.md)

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

```bash cURL theme={null}
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.

> [!TIP]
>
> Referência da API: [Simular cálculo de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/simulate-fee-schedule.md)

> [!NOTE]
>
> 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`. Quando regras de tarifa bloqueiam a exclusão, a resposta lista os contextos delas na entrada de `errors[]` cuja `location` é `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`.

```bash cURL theme={null}
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"
     }
   ]
 }'
```

> [!TIP]
>
> Referência da API:
>
> * [Criar regra de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/create-fee-rule.md)
> * [Listar regras de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/list-fee-rules.md)
> * [Recuperar regra de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-fee-rule.md)
> * [Atualizar regra de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/update-fee-rule.md)
> * [Excluir regra de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/delete-fee-rule.md)

## Fluxo de ponta a ponta

***

O tratamento de tarifas esperadas segue três etapas:

**1. 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.

**2. 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.

**3. Aplique durante a correspondência**

Defina o `feeNormalization` do contexto como `NET` ou `GROSS`. O contexto então precisa de pelo menos uma regra de tarifa para ser ativado. Até ter uma, a prontidão de ativação informa `context.activation.requirement.fee-rule`. 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

***

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`). Quando regras de tarifa a bloqueiam, a resposta lista os contextos delas em `errors[]`. 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

***

> [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md)
>
> Configure como o Matcher compara transações depois de considerar as tarifas esperadas.

> [card] [Roteamento de exceções](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-exception-routing.md)
>
> Revise a atribuição explícita, o despacho e o comportamento de callback para exceções que o tratamento de tarifas não cobre.

> [card] [API de tabelas de tarifas](https://docs.lerian.studio/pt/reference/products/matcher/create-fee-schedule.md)
>
> Referência completa da API para os endpoints de tabela de tarifas.

> [card] [API de regras de tarifa](https://docs.lerian.studio/pt/reference/products/matcher/create-fee-rule.md)
>
> Referência completa da API para os endpoints de regra de tarifa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.