> ## 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 usadas pela normalização NET ou GROSS quando o lado da correspondência e as moedas são compatíveis.

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.

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

<Note>
  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.
</Note>

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

```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](/pt/reference/products/matcher/create-fee-schedule)
  * [Listar tabelas de tarifas](/pt/reference/products/matcher/list-fee-schedules)
  * [Recuperar tabela de tarifas](/pt/reference/products/matcher/retrieve-fee-schedule)
  * [Atualizar tabela de tarifas](/pt/reference/products/matcher/update-fee-schedule)
  * [Excluir tabela de tarifas](/pt/reference/products/matcher/delete-fee-schedule)
</Tip>

### 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](/pt/reference/products/matcher/simulate-fee-schedule)</Tip>

<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` 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.
</Note>

## 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](/pt/reference/products/matcher/create-fee-rule)
  * [Listar regras de tarifa](/pt/reference/products/matcher/list-fee-rules)
  * [Recuperar regra de tarifa](/pt/reference/products/matcher/retrieve-fee-rule)
  * [Atualizar regra de tarifa](/pt/reference/products/matcher/update-fee-rule)
  * [Excluir regra de tarifa](/pt/reference/products/matcher/delete-fee-rule)
</Tip>

## Fluxo de ponta a ponta

***

O tratamento de tarifas esperadas segue três etapas:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Boas práticas

***

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Regras de correspondência" icon="scale-balanced" href="/pt/products/matcher/configuration/matcher-match-rules" horizontal>
  Configure como o Matcher compara transações depois de considerar as tarifas esperadas.
</Card>

<Card title="Roteamento de exceções" icon="route" href="/pt/products/matcher/configuration/matcher-exception-routing" horizontal>
  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>

<Card title="API de tabelas de tarifas" icon="code" href="/pt/reference/products/matcher/create-fee-schedule" horizontal>
  Referência completa da API para os endpoints de tabela de tarifas.
</Card>

<Card title="API de regras de tarifa" icon="code" href="/pt/reference/products/matcher/create-fee-rule" horizontal>
  Referência completa da API para os endpoints de regra de tarifa.
</Card>