# Regras

Uma regra descreve, em uma linguagem simplificada, o que a plataforma deve fazer com um evento no momento em que ele chega. Ela é executada de forma síncrona, durante o envio para `POST /events`, e pode enriquecer o próprio evento com novos valores antes que ele seja armazenado.

Toda regra pertence a um **tipo de evento**. Esse vínculo é o que define quais campos podem ser usados nas condições e quais campos podem receber valores.

## Estrutura

Uma regra é um conjunto ordenado de [condições](/pt/rules/conditions/). Cada condição tem:

- um **nome**, para identificá-la no painel;
- uma **expressão**, que resulta em verdadeiro ou falso, escrita conforme a [sintaxe para expressões](/pt/rules/expression-syntax/);
- de zero a várias **ações**, executadas quando a expressão é verdadeira.

## Como uma regra é executada

1. o evento chega em `POST /events` e é validado conforme o contrato do tipo de evento;
2. a plataforma identifica qual regra aplicar;
3. as condições são avaliadas **em ordem, todas elas**: a avaliação não para na primeira condição satisfeita;
4. cada condição satisfeita executa suas ações, na ordem em que estão configuradas;
5. os valores produzidos são gravados no evento e devolvidos na resposta.

Todas as condições compartilham a mesma memória de trabalho: uma condição enxerga o que as anteriores escreveram. Isso permite encadear o processamento: uma condição enriquece o evento com um dado externo e outra, mais adiante, decide com base nesse dado.

## Qual regra é executada

A regra a executar é escolhida em duas etapas:

1. o nome informado em `rule.name` na requisição;
2. se a requisição não informar nenhum, a **regra padrão** configurada no tipo de evento.

```json
{
  "event": {
    "type": "transaction",
    "id": "evt_8f3a",
    "attributes": { "amount": "1500.00", "status": "pending" },
    "rule": { "name": "minha_regra" }
  }
}
```

A regra precisa ter uma versão **ativa** publicada e pertencer ao mesmo tipo de evento do evento enviado. Consulte [versionamento](/pt/rules/versioning/) para publicar e reverter versões.

### Quando nenhuma regra é executada

Nos cenários abaixo o evento é ingerido normalmente, apenas sem passar por nenhuma regra:

- a requisição não informa uma regra e o tipo de evento não tem regra padrão;
- a regra informada não existe;
- a regra existe, mas não tem versão ativa publicada;
- a regra pertence a outro tipo de evento.

A requisição **não falha** em nenhum desses casos. Um nome de regra incorreto não interrompe a ingestão; por isso, ao configurar uma regra nova, confirme no painel que ela está ativa e vinculada ao tipo de evento correto.

## O que a regra grava no evento

As ações gravam nos campos do próprio tipo de evento. Esses valores passam a fazer parte do evento como qualquer outro dado enviado na requisição: são persistidos, aparecem na resposta da API, podem ser consultados no painel e podem alimentar [métricas e monitoramentos](/pt/behavioral/).

Além disso, a plataforma registra automaticamente **qual regra processou o evento** e em **qual versão**, em campos reservados criados na primeira ativação de uma regra do tipo de evento. Esses campos ficam disponíveis para consulta e análise, mas não são devolvidos na resposta da API e não podem ser preenchidos na ingestão: nomes de campo iniciados por `_` são rejeitados.

## Limitações

Há limites de quantidade e tamanho aplicáveis a regras e listas. Consulte [limites e parâmetros](/pt/limits/#regras-e-listas) antes de planejar configurações extensas.

## Índice

- [Condições](/pt/rules/conditions/index.html.md)
- [Sintaxe para expressões](/pt/rules/expression-syntax/index.html.md)
- [Ações](/pt/rules/actions/index.html.md)
- [Listas](/pt/rules/lists/index.html.md)
- [Análises](/pt/rules/analyses/index.html.md)
- [Versionamento](/pt/rules/versioning/index.html.md)