Motor de regras

O motor de regras é o que times de risco e fraude usam para mudar como transações são aprovadas ou bloqueadas, sem mexer no código da aplicação. Cada regra é uma pequena expressão que roda em cada transação que o Tracer valida — “bloquear este MCC para este segmento”, “enviar tudo acima de R$ 50 mil para revisão manual”, “negar se a conta estiver suspensa”. O que muda na sua operação: mudanças em regras sobem por um endpoint de API, não por uma release. Um analista pode publicar uma nova regra de manhã e vê-la avaliando transações reais em segundos. Cada correspondência fica registrada, então uma ligação de cliente reclamando seis meses depois pode ser rastreada até a regra exata que disparou. O trade-off honesto: você tem que pensar em CEL (Common Expression Language) em vez de Go, Python ou Java. A curva é curta — a maioria das regras tem uma linha — mas quem escreve não é mais o time de aplicação. A contrapartida é zero deploy, auditoria completa e quem está mais perto da política é dono dela.

Para quem é este guia? Analistas de risco e fraude que vão escrever regras, devs integrando a chamada de validação, e oficiais de compliance lendo a trilha de auditoria. Os exemplos em CEL ficam técnicos mais para frente, mas o ciclo de vida e a lógica de decisão são úteis para qualquer um avaliando o produto.

O motor de regras do Tracer avalia lógica de validação escrita em — uma linguagem de expressões type-safe da Google. As expressões são compiladas na criação da regra e executadas em cada validação de transação; você altera o comportamento atualizando regras via API, sem redeploy de código.

Por que usar o motor de regras

Flexibilidade: Crie e modifique regras sem deploys de código
Modelo de execução: o Tracer avalia expressões compiladas durante a validação
Segurança de tipos: Sintaxe da expressão validada na criação da regra
Sem curto-circuito: as regras correspondentes são avaliadas juntas, então a trilha de auditoria registra as regras que dispararam, não apenas a categoria vencedora
Baseado em escopo: Aplique regras a segmentos, contas ou tipos de transação específicos

Ao final deste guia, você irá:

Entender os conceitos do motor de regras e o fluxo de avaliação
Criar e testar regras baseadas em expressões
Gerenciar o ciclo de vida das regras (DRAFT, ACTIVE, INACTIVE, DELETED)
Aplicar melhores práticas para gerenciamento de regras

O que é o motor de regras

O motor de regras é o componente do Tracer responsável por avaliar expressões durante a validação de transações. Ele permite que analistas de fraude e gestores de risco configurem lógica de negócios que executa em tempo real - sem necessidade de deploys de código ou suporte de engenharia.

Como funciona

Como o motor de regras avalia as expressões configuradas em relação ao contexto da transação durante a validação e retorna uma decisão — Figure 1. Fluxo de avaliação do motor de regras

Neste fluxo:

Carregar regras busca todas as regras ativas do cache (ou banco de dados em caso de cache miss)
Avaliar expressões executa a expressão CEL de cada regra cujo escopo corresponde à transação
Coletar correspondências reúne todas as regras que corresponderam e determina a decisão

Padrão de avaliação

As regras cujo escopo corresponde à transação são avaliadas juntas. Não há ordenação por prioridade ou avaliação de curto-circuito. Isso garante:

Trilha de auditoria completa (todas as regras correspondentes são registradas)
Sem perda de informação (analistas podem ver todos os gatilhos)
Lógica simples (sem conflitos de prioridade)

Precedência de decisão (da mais alta para a mais baixa):

DENY — qualquer regra DENY que corresponder vence imediatamente.
Limite excedido — se nenhuma regra DENY corresponder, mas algum limite aplicável for excedido, a decisão é DENY (a precedência das regras se aplica primeiro; limites entram apenas quando nenhuma DENY casou).
REVIEW — se nenhuma regra DENY corresponder e nenhum limite for excedido, qualquer regra REVIEW que corresponder vence.
ALLOW — se apenas regras ALLOW corresponderem, a decisão é ALLOW.
Padrão — se nenhuma regra corresponder, o Tracer retorna o DEFAULT_DECISION_WHEN_NO_MATCH configurado (ALLOW, a menos que explicitamente definido como DENY para implantações fail-closed). Apenas ALLOW e DENY são aceitos; REVIEW não é um valor válido como decisão padrão, e qualquer outro valor faz o serviço falhar na inicialização.

matchedRuleIds na resposta contém todas as regras que corresponderam, independente da categoria vencedora, para que consumidores de auditoria vejam todos os gatilhos.

Por que DENY vence REVIEW e REVIEW vence ALLOW. A precedência é fixa e não configurável, de propósito: remove a ambiguidade de “qual regra DENY vence?” em runtime e torna a auditoria trivial — a resposta sempre identifica a ação mais estrita que disparou. O custo é que você não consegue escrever “regras ALLOW que sobrescrevem DENYs”; se você precisa desse padrão, a resposta certa é tornar a regra DENY mais específica.

O Tracer retorna decisões; ele não bloqueia transações diretamente. Seu sistema recebe a decisão e é responsável por tomar a ação apropriada (ex.: bloquear, permitir ou enfileirar para revisão).

Conceitos principais

Antes de criar regras, entenda os elementos fundamentais.

Regras

Uma regra é uma unidade de lógica de negócios composta por:

Expressão - Uma expressão type-safe que avalia para true ou false
Ação - Qual decisão retornar quando a expressão é verdadeira
Escopos - A quais transações a regra se aplica
Status - O estado do ciclo de vida da regra

Expressões

Expressões são escritas em CEL (Common Expression Language), uma linguagem type-safe que avalia o contexto da transação e retorna um valor booleano (true ou false). CEL fornece validação em tempo de compilação, então erros de sintaxe são detectados quando você cria a regra - não quando as transações estão sendo processadas. Exemplos de expressões:

amount > 10000

segment.segmentId == "high-risk-segment-uuid" && amount > 5000

merchant["category"] == "7995"

(merchant.category é o código MCC ISO 18245 de 4 dígitos — "7995" é o MCC para apostas/cassino. Tanto merchant.category quanto merchant["category"] são aceitos; os exemplos em produção usam a notação com colchetes por convenção. Se precisar casar com um rótulo textual como "gambling", armazene-o em metadata e faça o match por lá.) As expressões leem a requisição de validação através de dez variáveis. Para os tipos e formatos de campo por trás de cada uma, consulte o schema ValidationRequest na referência da API.

Variável	Tipo	Para o que tipicamente serve
`amount`	number	O valor da transação, nas mesmas unidades que você envia na requisição: `"1500.00"` chega à expressão como `1500`. A faixa segura é `±2^53`.
`transactionType`	string	Um dos valores `CARD`, `WIRE`, `PIX`, `CRYPTO`.
`subType`	string	Texto livre, em minúsculas (ex.: `"international"`, `"debit"`). String vazia quando não informado.
`asset`	string	Código de ativo ISO 4217 (ex.: `"BRL"`).
`transactionTimestamp`	int	Horário da transação em nanossegundos Unix. Divida por `1000000000` para obter segundos.
`account`	map	`accountId`, `type`, `status`, `metadata`.
`segment`	map	`segmentId`, `name`, `metadata`.
`portfolio`	map	`portfolioId`, `name`, `metadata`.
`merchant`	map	`merchantId`, `name`, `category`, `country`, `metadata`.
`metadata`	map	Campos customizados que sua integração passa no payload da requisição.

Valores de campo que vale conhecer antes de escrever uma condição:

account.status aceita active, suspended, closed, e account.type aceita checking, savings, credit.
merchant.category recebe um código MCC ISO 18245 de 4 dígitos; merchant.country recebe um código ISO 3166-1 alpha-2.
Esses quatro campos são opcionais na requisição. Um campo que a requisição omite chega à sua expressão como string vazia, então uma condição que o compara com um valor específico é falsa.
segment.segmentId, portfolio.portfolioId, account.accountId e merchant.merchantId são strings UUID.

segmentId e portfolioId ficam nas variáveis de primeiro nível segment e portfolio, não em account. Para filtrar por segmento, escreva segment.segmentId == "...", não account.segmentId == "...".Uma regra que lê um campo de contexto que a requisição não carrega não corresponde, e as outras regras seguem rodando — então você não precisa de uma guarda de presença para esse caso. Quando a presença em si é a condição que você quer, escreva size(segment) > 0 ou "risk_score" in metadata.

O custo das expressões é limitado pelo CEL_COST_LIMIT (padrão 10000). A verificação roda em tempo de compilação — na criação da regra, na atualização da expressão e novamente na ativação —, não apenas na ativação: uma expressão cujo custo estimado no pior caso excede o limite é rejeitada com o código de erro 0342 (limite de custo excedido) na primeira vez que você a envia. Erros de sintaxe aparecem como 0340, erros de tipo (incluindo uma expressão que não retorna um booleano) como 0341, e uma falha ao estimar o custo como 0345.

Exemplos de expressões por caso de uso

Aqui estão exemplos práticos organizados por cenário de negócio:

Regras baseadas em valor

// Bloquear transações acima de um limite
amount > 10000

// Bloquear transferências internacionais de alto valor
transactionType == "WIRE" && subType == "international" && amount > 50000

// Revisar transações de criptomoeda de grande valor
transactionType == "CRYPTO" && amount > 5000

Regras baseadas em comerciante

// Bloquear comerciantes de jogos de azar
merchant.category == "7995"

// Bloquear categorias de comerciantes de alto risco
merchant.category in ["7995", "5967", "5966"]

// Revisar transações de novos países de comerciantes
merchant.country != "BR" && amount > 1000

Regras baseadas em conta

// Bloquear contas suspensas
account.status == "suspended"

// Revisar transações de contas recém-criadas
metadata.accountAgeDays < 30 && amount > 500

// Bloquear contas encerradas
account.status == "closed"

Condições combinadas

// Transação de alto valor de segmento de alto risco
segment.segmentId == "high-risk-segment-uuid" && amount > 5000

// PIX internacional acima do limite
transactionType == "PIX" && subType == "international" && amount > 10000

// Transação de cartão de grande valor para comerciante estrangeiro
transactionType == "CARD" && merchant.country != "BR" && amount > 3000

Regras por horário

// Revisar transações de cartão no fim da noite (a partir das 22:00 UTC) acima de BRL 5.000
transactionType == "CARD" && amount > 5000 && timestamp(transactionTimestamp / 1000000000).getHours("UTC") >= 22

// Revisar transações de fim de semana acima de BRL 10.000
timestamp(transactionTimestamp / 1000000000).getDayOfWeek("UTC") in [0, 6] && amount > 10000

Usando metadata

// Bloquear transações de dispositivos não confiáveis
metadata.deviceTrust == "untrusted"

// Revisar primeiras compras acima do limite
metadata.isFirstPurchase == true && amount > 1000

// Bloquear transações fora do horário comercial (usando metadata)
metadata.isBusinessHours == false && amount > 5000

// Clientes VIP contornam certas restrições
metadata.customerTier == "vip" && amount < 50000

Campos de metadata são fornecidos pela sua integração. Projete seu payload para incluir o contexto que suas regras precisam.

Ações

Ações determinam a decisão quando uma expressão avalia para true:

Ação	Descrição
`ALLOW`	Permitir a transação
`DENY`	Negar a transação
`REVIEW`	Encaminhar para revisão manual

Escopos

Escopos definem a quais transações uma regra se aplica. Uma regra sem scopes é global e avalia contra qualquer transação. Uma regra com um ou mais objetos de escopo só avalia quando a transação corresponde a pelo menos um deles (semântica OR entre objetos de escopo). Dentro de um único objeto de escopo, os campos suportados são:

segmentId - Corresponder transações de um segmento específico
portfolioId - Corresponder transações de um portfólio específico
accountId - Corresponder transações de uma conta específica
merchantId - Corresponder transações para um comerciante específico
transactionType - Corresponder tipos de transação específicos (CARD, WIRE, PIX, CRYPTO)
subType - Corresponder subtipos específicos (debit, credit, instant, etc.)

Semântica de correspondência:

Dentro de um objeto de escopo: os campos combinam com AND. Um campo não especificado funciona como wildcard (corresponde a qualquer valor). Pelo menos um campo deve estar definido — objetos de escopo vazios ({}) são rejeitados com o código de erro 0358.
Entre múltiplos objetos de escopo na mesma regra: combinam com OR. A regra corresponde se qualquer objeto de escopo corresponder à transação.

Por exemplo, uma regra com dois escopos — um filtrando transactionType: CARD e outro filtrando transactionType: PIX — executa tanto para transações de cartão quanto para PIX. Um único escopo com segmentId E accountId exige que a transação corresponda ao segmento E à conta.

Ciclo de vida da regra

Regras progridem através de um ciclo de vida definido para garantir implantação segura.

Ciclo de vida das regras e dos limites no Tracer, com as transições de estado pelas quais uma definição passa da criação até a aplicação ativa — Figura 2. Ciclo de vida e transições do motor de regras

Estados

Estado	Descrição
`DRAFT`	Não avaliada; expressão pode ser modificada livremente
`ACTIVE`	Avaliada durante validações; expressão é imutável
`INACTIVE`	Não avaliada; preservada para trilha de auditoria; pode ser reativada. A expressão continua imutável neste estado — para editá-la, mova a regra de volta para DRAFT via `POST /v1/rules/{id}/draft`.
`DELETED`	Excluída via soft delete; não retornada nas listagens e não pode ser recuperada via API, mas a linha permanece no banco de dados para trilha de auditoria.

Transições

Transição	De	Para	Descrição
`activate`	DRAFT, INACTIVE	ACTIVE	Iniciar avaliação (valida expressão)
`deactivate`	ACTIVE	INACTIVE	Parar avaliação
`draft`	INACTIVE	DRAFT	Reeditar uma regra previamente desativada antes de reativá-la
`delete`	DRAFT, INACTIVE	DELETED	Remoção permanente (não pode deletar regras ACTIVE)

Regras ativas devem ser desativadas antes da exclusão. Isso previne remoção acidental de regras que estão sendo avaliadas.

Criar uma regra

Crie regras usando POST /v1/rules. Regras são criadas com status DRAFT por padrão. Uma regra requer:

name: Um nome descritivo, único dentro do seu contexto. O contexto é derivado dos escopos da regra (o menor segmentId entre eles); regras sem escopo compartilham um único contexto global. Assim, o mesmo nome de regra pode coexistir em dois segmentos diferentes, mas não duas vezes dentro de um. A comparação diferencia maiúsculas de minúsculas e preserva os espaços internos; os espaços no início e no fim são removidos antes de salvar. Uma colisão retorna 409 Conflict com o código de erro 0441. Referencie a regra pelo ruleId da resposta.
expression: Uma expressão CEL que avalia para true ou false
action: A decisão a retornar quando a expressão corresponder (ALLOW, DENY ou REVIEW)
scopes (opcional): Limita a quais transações a regra se aplica

Para a estrutura completa do payload e detalhes de campos, consulte a Referência da API.

Ativar e desativar regras

Após criar uma regra, ative-a para iniciar a avaliação. Desative regras para parar a avaliação sem excluí-las.

Operação	Endpoint	Descrição
Ativar	`POST /v1/rules/{id}/activate`	Iniciar avaliação desta regra
Desativar	`POST /v1/rules/{id}/deactivate`	Parar avaliação (preserva para auditoria)

Desativar uma regra a preserva para fins de auditoria. Use exclusão apenas quando quiser remover permanentemente uma regra.

Listar e consultar regras

Consulte regras para gerenciamento e auditoria usando GET /v1/rules.

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`name`	string	Filtrar por nome (correspondência parcial, case-insensitive)
`status`	string	Filtrar por status (DRAFT, ACTIVE, INACTIVE). `DELETED` não é um valor válido para este filtro.
`action`	string	Filtrar por ação (ALLOW, DENY, REVIEW)
`account_id`	UUID	Filtrar por escopo: ID da conta
`segment_id`	UUID	Filtrar por escopo: ID do segmento
`portfolio_id`	UUID	Filtrar por escopo: ID do portfólio
`merchant_id`	UUID	Filtrar por escopo: ID do comerciante
`transaction_type`	string	Filtrar por escopo: tipo de transação (CARD, WIRE, PIX, CRYPTO)
`sub_type`	string	Filtrar por escopo: subtipo (ex.: debit, credit)
`limit`	integer	Itens por página (padrão: 10, máx: 100)
`cursor`	string	Cursor de paginação da resposta anterior
`sort_by`	string	Campo de ordenação: `created_at`, `updated_at`, `name`, `status` (padrão: `created_at`)
`sort_order`	string	Direção: `ASC`, `DESC` (padrão: `DESC`)

Obter uma regra específica

Use GET /v1/rules/{id} para recuperar a definição completa da regra incluindo expressão e escopos.

Atualizar uma regra

Atualize regras usando PATCH /v1/rules/{id}. Regras podem ser atualizadas em qualquer status, com uma restrição importante:

O campo expression é imutável nos estados ACTIVE e INACTIVE — desativar a regra não basta. Para editar uma expressão, mova a regra de ACTIVE → INACTIVE (POST /v1/rules/{id}/deactivate) e depois de INACTIVE → DRAFT (POST /v1/rules/{id}/draft). Apenas regras DRAFT aceitam alterações na expressão. Após editar, reative com POST /v1/rules/{id}/activate.

Excluir uma regra

Exclua regras que não são mais necessárias. Apenas regras DRAFT e INACTIVE podem ser excluídas. Regras ACTIVE devem ser desativadas primeiro.

DELETE /v1/rules/{id}
X-API-Key: {api_key}

Resposta: 204 No Content

A exclusão é permanente. Regras excluídas não podem ser recuperadas e não aparecem em nenhuma listagem.

Melhores práticas

Siga estas práticas para regras eficazes e manuteníveis.

Nomenclatura

Use nomes descritivos - O nome deve indicar claramente o que a regra faz
Inclua contexto - Mencione o cenário ou tipo de transação
Evite abreviações - Prefira clareza à brevidade

Menos claro	Mais claro
`Regra 1`	`Bloquear transações noturnas acima de R$ 5.000`
`Bloquear alto`	`Negar transações de alto valor no fim de semana`
`Regra PIX`	`Revisar transferências PIX para novos destinatários`

Design de expressões

Mantenha expressões simples - Lógica complexa é mais difícil de manter
Use escopos para filtrar - Não repita condições de escopo nas expressões
Teste casos limite - Considere valores de fronteira e campos nulos

Gerenciamento de ciclo de vida

Comece em DRAFT - Teste antes de ativar
Volte para DRAFT antes de editar a expressão - A expressão é imutável em ACTIVE e INACTIVE; mova a regra para DRAFT via POST /v1/rules/{id}/draft para editar, depois reative
Arquive regras não utilizadas - Mantenha a trilha de auditoria intacta
Exclua apenas quando tiver certeza - A exclusão é permanente

Monitoramento

Revise regras correspondentes - Verifique quais regras estão sendo acionadas
Monitore taxas de DENY - Taxas de negação altas podem indicar regras muito agressivas
Audite regularmente - Garanta que as regras ainda estão alinhadas com os requisitos de negócio

Tropeços comuns ao trabalhar com regras:

“Editei a expressão mas a mudança não fez efeito.” A expressão é imutável nos estados ACTIVE e INACTIVE. Mova a regra de volta para DRAFT via POST /v1/rules/{id}/draft, edite e reative. INACTIVE sozinho não basta.
“Minha regra está ACTIVE mas outra instância do Tracer ainda não está avaliando ela.” A ativação passa a valer imediatamente na instância que atendeu a chamada de ativação. Quando você roda várias instâncias atrás de um balanceador, as outras pegam a mudança na próxima sincronização de regras (RULE_SYNC_POLL_INTERVAL_SECONDS, padrão 10). A desativação se propaga da mesma forma. Planeje testes de integração com essa janela quando as chamadas podem cair em instâncias diferentes.
“Quero deletar uma regra ACTIVE.” Você não pode — POST /v1/rules/{id}/deactivate primeiro, depois DELETE /v1/rules/{id}. Isso força um passo visível em que a regra para de afetar o tráfego antes de sumir das listagens.
“Meu escopo vazio {} está sendo rejeitado com o código de erro 0358.” Todo objeto de escopo precisa ter pelo menos um campo definido. Para rodar uma regra globalmente (contra qualquer transação), omita o array scopes inteiro — não passe {}.

Referência rápida

Endpoints, ações e informações de status-chave.

Endpoints

Operação	Método	Endpoint
Criar regra	POST	`/v1/rules`
Listar regras	GET	`/v1/rules`
Obter regra	GET	`/v1/rules/{id}`
Atualizar regra	PATCH	`/v1/rules/{id}`
Excluir regra	DELETE	`/v1/rules/{id}`
Ativar regra	POST	`/v1/rules/{id}/activate`
Desativar regra	POST	`/v1/rules/{id}/deactivate`
Voltar para rascunho	POST	`/v1/rules/{id}/draft`

Status

Status	Avaliada	Editável	Pode excluir
`DRAFT`	Não	Sim	Sim
`ACTIVE`	Sim	Parcial (`expression` imutável)	Não (desativar primeiro)
`INACTIVE`	Não	Parcial (`expression` imutável; voltar para DRAFT primeiro)	Sim
`DELETED`	Não	Não	N/A

Visão geral

Guias

Console

Operações

Motor de regras

Por que usar o motor de regras

O que é o motor de regras

Como funciona

Padrão de avaliação

Conceitos principais

Regras

Expressões

Exemplos de expressões por caso de uso

Regras baseadas em valor

Regras baseadas em comerciante

Regras baseadas em conta

Condições combinadas

Regras por horário

Usando metadata

Ações

Escopos

Ciclo de vida da regra

Estados

Transições

Criar uma regra

Ativar e desativar regras

Listar e consultar regras

Parâmetros de consulta

Obter uma regra específica

Atualizar uma regra

Excluir uma regra

Melhores práticas

Nomenclatura

Design de expressões

Gerenciamento de ciclo de vida

Monitoramento

Referência rápida

Endpoints

Status

​Por que usar o motor de regras

​O que é o motor de regras

​Como funciona

​Padrão de avaliação

​Conceitos principais

​Regras

​Expressões

​Exemplos de expressões por caso de uso

​Regras baseadas em valor

​Regras baseadas em comerciante

​Regras baseadas em conta

​Condições combinadas

​Regras por horário

​Usando metadata

​Ações

​Escopos

​Ciclo de vida da regra

​Estados

​Transições

​Criar uma regra

​Ativar e desativar regras

​Listar e consultar regras

​Parâmetros de consulta

​Obter uma regra específica

​Atualizar uma regra

​Excluir uma regra

​Melhores práticas

​Nomenclatura

​Design de expressões

​Gerenciamento de ciclo de vida

​Monitoramento

​Referência rápida

​Endpoints

​Status

Por que usar o motor de regras

O que é o motor de regras

Como funciona

Padrão de avaliação

Conceitos principais

Regras

Expressões

Exemplos de expressões por caso de uso

Regras baseadas em valor

Regras baseadas em comerciante

Regras baseadas em conta

Condições combinadas

Regras por horário

Usando metadata

Ações

Escopos

Ciclo de vida da regra

Estados

Transições

Criar uma regra

Ativar e desativar regras

Listar e consultar regras

Parâmetros de consulta

Obter uma regra específica

Atualizar uma regra

Excluir uma regra

Melhores práticas

Nomenclatura

Design de expressões

Gerenciamento de ciclo de vida

Monitoramento

Referência rápida

Endpoints

Status