Motor de regras

O motor de regras é o que as equipes de risco e fraude usam para mudar como o Tracer aprova ou bloqueia transações, sem tocar no código da aplicação. Cada regra é uma pequena expressão que roda em toda transação que o Tracer valida: “bloquear este MCC para este segmento”, “enviar qualquer valor acima de R$ 50 mil para revisão manual”, “negar se a conta estiver suspensa”. O que muda na sua operação: mudanças de regra saem por um endpoint de API, não por um release. Um analista pode publicar uma nova regra de manhã e vê-la avaliando transações reais em segundos. O Tracer registra cada correspondência, então você pode rastrear a ligação de um cliente negado seis meses depois até a regra exata que disparou. Para ser honesto sobre a contrapartida: você precisa pensar em CEL (Common Expression Language) em vez de Go, Python ou Java. A curva de aprendizado é curta (a maioria das regras tem uma linha), mas o time que as escreve não é mais seus desenvolvedores de aplicação. A vantagem é nenhum deploy, auditoria completa, e as pessoas mais próximas da política são as responsáveis por ela.

Para quem é este guia? Analistas de risco e fraude que vão escrever regras, desenvolvedores que integram a chamada de validação, e profissionais de compliance que leem a trilha de auditoria. Os exemplos em CEL ficam mais técnicos mais adiante, mas a lógica de ciclo de vida e de decisão é útil para qualquer pessoa avaliando o produto.

O motor de regras do Tracer avalia a lógica de validação escrita em , uma linguagem de expressão type-safe do Google. O Tracer compila as expressões na criação da regra e as executa durante toda validação de transação. Você muda o comportamento atualizando regras pela API, sem fazer redeploy do 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: a sintaxe da expressão é validada na criação da regra
Sem short-circuit: o Tracer avalia juntas as regras correspondentes, 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ê vai:

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 da regra (DRAFT, ACTIVE, INACTIVE, DELETED)
Aplicar boas práticas de 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 gerentes de risco configurem lógica de negócio que é executada em tempo real, sem exigir deploys de código ou suporte de engenharia.

Como funciona

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

Neste fluxo:

Carregar regras busca todas as regras ativas do cache (ou do 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

O Tracer avalia juntas todas as regras cujo escopo corresponde à transação. Não há ordenação por prioridade nem avaliação por short-circuit. Isso garante:

Trilha de auditoria completa (todas as regras correspondentes são registradas)
Nenhuma 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 correspondente vence diretamente.
Limite excedido: se nenhuma regra DENY correspondeu, mas a transação excede algum limite aplicável, a decisão é DENY. A precedência de regras se aplica primeiro, e os limites entram em jogo apenas quando nenhuma regra DENY correspondeu.
REVIEW: se nenhuma regra DENY correspondeu e a transação não excedeu nenhum limite, qualquer regra REVIEW correspondente vence.
ALLOW: se apenas regras ALLOW corresponderam, a decisão é ALLOW.
Padrão: se nenhuma regra correspondeu, o Tracer retorna o DEFAULT_DECISION_WHEN_NO_MATCH configurado (ALLOW, a menos que explicitamente definido como DENY para deployments fail-closed). O Tracer aceita apenas ALLOW e DENY. REVIEW deliberadamente não é um padrão válido para ausência de correspondência, e qualquer outro valor faz o serviço falhar na inicialização.

matchedRuleIds na resposta contém toda regra que correspondeu, independentemente da categoria vencedora, para que os consumidores da auditoria possam ver todos os gatilhos.

Por que DENY vence REVIEW que vence ALLOW. A precedência nunca muda e você não pode configurá-la, de propósito. Isso elimina a ambiguidade de “qual regra DENY vence?” em tempo de execução e torna a auditoria trivial. A resposta sempre identifica a ação mais restritiva que disparou. O custo é que você não pode escrever “regras ALLOW que sobrepõem DENYs”. Se precisar 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 deve tomar a ação apropriada (por exemplo, bloquear, permitir ou colocar em fila para revisão).

Conceitos básicos

Antes de criar regras, entenda os elementos fundamentais.

Regras

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

Expressão - uma expressão type-safe que avalia para verdadeiro ou falso
Ação - qual decisão retornar quando a expressão é verdadeira
Escopos - a quais transações a regra se aplica
Status - o estado de ciclo de vida da regra

Expressões

Você escreve expressões em CEL (Common Expression Language), uma linguagem type-safe que avalia o contexto da transação e retorna um valor booleano (verdadeiro ou falso). O CEL oferece validação em tempo de compilação, então erros de sintaxe aparecem quando você cria a regra, não quando o Tracer processa as transações. Exemplos de expressões:

amount > 10000

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

merchant["category"] == "7995"

(merchant.category é o código MCC de 4 dígitos da ISO 18245. "7995" é o MCC para apostas/cassino. O Tracer aceita tanto merchant.category quanto merchant["category"]. Os exemplos de produção usam a notação de colchetes por convenção. Se você precisar corresponder a um rótulo de texto como "gambling", armazene-o em metadata e corresponda a esse campo.) As expressões leem a requisição de validação por meio de dez variáveis. Para os tipos e formatos de campo por trás de cada uma, veja o esquema ValidationRequest na referência da API.

Variável	Tipo	O que você normalmente usa na correspondência
`amount`	number	O valor da transação, nas mesmas unidades que você envia na requisição: `"1500.00"` chega a uma expressão como `1500`. O intervalo seguro é `±2^53`.
`transactionType`	string	Um de `CARD`, `WIRE`, `PIX`, `CRYPTO`.
`subType`	string	Texto livre, em minúsculas (por exemplo, `"international"`, `"debit"`). String vazia quando não fornecido.
`asset`	string	Código ISO 4217 (por exemplo, `"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 a pena 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 de 4 dígitos da ISO 18245. 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 uma string vazia, então uma condição que o testa para um valor específico é falsa.
segment.segmentId, portfolio.portfolioId, account.accountId e merchant.merchantId são strings UUID.

segmentId e portfolioId vivem nas variáveis de nível superior segment e portfolio, não em account. Para corresponder 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 continuam rodando, então você não precisa de uma verificação de presença para esse caso. Quando a própria presença é a condição que você quer, escreva size(segment) > 0 ou "risk_score" in metadata.

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

Exemplos de expressões por caso de uso

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

Regras baseadas em valor

// Block transactions above a threshold
amount > 10000

// Block high-value international transfers
transactionType == "WIRE" && subType == "international" && amount > 50000

// Review large cryptocurrency transactions
transactionType == "CRYPTO" && amount > 5000

Regras baseadas em comerciante

// Block gambling merchants
merchant.category == "7995"

// Block high-risk merchant categories
merchant.category in ["7995", "5967", "5966"]

// Review transactions from new merchant countries
merchant.country != "BR" && amount > 1000

Regras baseadas em conta

// Block suspended accounts
account.status == "suspended"

// Review transactions from newly created accounts
metadata.accountAgeDays < 30 && amount > 500

// Block closed accounts
account.status == "closed"

Condições combinadas

// High-value transaction from high-risk segment
segment.segmentId == "high-risk-segment-uuid" && amount > 5000

// International Pix above threshold
transactionType == "PIX" && subType == "international" && amount > 10000

// Large card transaction to foreign merchant
transactionType == "CARD" && merchant.country != "BR" && amount > 3000

Regras baseadas em tempo

// Review late-night card transactions above BRL 5,000
transactionType == "CARD" && amount > 5000 && timestamp(transactionTimestamp / 1000000000).getHours("UTC") >= 22

// Review weekend transactions above BRL 10,000
timestamp(transactionTimestamp / 1000000000).getDayOfWeek("UTC") in [0, 6] && amount > 10000

Usando metadados

// Block transactions from untrusted devices
metadata.deviceTrust == "untrusted"

// Review first-time purchases above threshold
metadata.isFirstPurchase == true && amount > 1000

// Block transactions outside business hours (using metadata)
metadata.isBusinessHours == false && amount > 5000

// VIP customers bypass certain restrictions
metadata.customerTier == "vip" && amount < 50000

Sua integração fornece campos de metadados. Projete seu payload para incluir o contexto que suas regras precisam.

Ações

As ações determinam a decisão quando uma expressão avalia para verdadeiro:

Ação	Descrição
`ALLOW`	Permite a transação
`DENY`	Nega a transação
`REVIEW`	Encaminha para revisão manual

Escopos

Escopos definem a quais transações uma regra se aplica. Uma regra sem scopes é global e é avaliada em relação a toda transação. Uma regra com um ou mais objetos de escopo é avaliada apenas 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 aceitos são:

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

Semântica de correspondência:

Dentro de um objeto de escopo: os campos se combinam com AND. Um campo que você omite funciona como coringa (corresponde a qualquer valor). Você deve definir pelo menos um campo. O Tracer rejeita objetos de escopo vazios ({}) com o código de erro 0358.
Entre múltiplos objetos de escopo na mesma regra: eles se combinam com OR. A regra corresponde se qualquer objeto de escopo corresponder à transação.

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

Ciclo de vida da regra

As regras avançam por um ciclo de vida definido para garantir um deploy seguro.

Ciclo de vida de regras e limites no Tracer, mostrando as transições de status que uma definição percorre da criação até a aplicação ativa — Figura 2. Ciclo de vida das regras e transições de status

Estados

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

Transições

Transição	De	Para	Descrição
`activate`	DRAFT, INACTIVE	ACTIVE	Inicia a avaliação (valida a expressão)
`deactivate`	ACTIVE	INACTIVE	Para a avaliação
`draft`	INACTIVE	DRAFT	Reedita uma regra previamente desativada antes de reativar
`delete`	DRAFT, INACTIVE	DELETED	Remoção permanente (não é possível excluir regras ACTIVE)

Você deve desativar regras ativas antes da exclusão. Isso evita a remoção acidental de regras que o Tracer ainda avalia.

Criar uma regra

Crie regras usando POST /v1/rules. Por padrão, o Tracer cria regras no status DRAFT. Uma regra exige:

name: um nome descritivo, único dentro do seu contexto. Os escopos da regra decidem o contexto (o menor segmentId entre eles), e regras sem escopo compartilham um único contexto global. Então o mesmo nome de regra pode coexistir entre dois segmentos diferentes, mas não duas vezes dentro de um mesmo segmento. A comparação diferencia maiúsculas de minúsculas e preserva espaços em branco internos, e o Tracer remove espaços em branco no início e no fim antes de armazenar. 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 verdadeiro ou falso
action: a decisão a retornar quando a expressão corresponde (ALLOW, DENY ou REVIEW)
scopes (opcional): limita a quais transações a regra se aplica

Para a estrutura completa do payload e detalhes dos campos, veja a referência da API.

Ativar e desativar regras

Depois de criar uma regra, ative-a para começar a avaliação. Desative regras para parar a avaliação sem excluí-las.

Operação	Endpoint	Descrição
Ativar	`POST /v1/rules/{id}/activate`	Começa a avaliar esta regra
Desativar	`POST /v1/rules/{id}/deactivate`	Para a avaliação (preserva para auditoria)

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

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	Filtra por nome (correspondência parcial sem diferenciar maiúsculas de minúsculas)
`status`	string	Filtra por status (DRAFT, ACTIVE, INACTIVE). `DELETED` não é um valor de filtro válido.
`action`	string	Filtra por ação (ALLOW, DENY, REVIEW)
`account_id`	UUID	Filtra por escopo: ID da conta
`segment_id`	UUID	Filtra por escopo: ID do segmento
`portfolio_id`	UUID	Filtra por escopo: ID do portfólio
`merchant_id`	UUID	Filtra por escopo: ID do comerciante
`transaction_type`	string	Filtra por escopo: tipo de transação (CARD, WIRE, PIX, CRYPTO)
`sub_type`	string	Filtra por escopo: subtipo (por exemplo, debit, credit)
`limit`	integer	Itens por página (padrão: 10, máximo: 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 de ordenaçã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 aceitam atualizações em qualquer status, com uma restrição importante:

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

Excluir uma regra

Exclua regras que você não precisa mais. Você pode excluir apenas regras DRAFT e INACTIVE. Desative regras ACTIVE primeiro.

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

A exclusão é permanente. Você não pode recuperar regras excluídas, e elas não aparecem em nenhuma listagem.

Boas práticas

Siga estas práticas para regras eficazes e fáceis de manter.

Nomenclatura

Use nomes descritivos - o nome deve deixar claro o que a regra faz
Inclua contexto - mencione o cenário ou tipo de transação
Evite abreviações - prefira clareza a brevidade

Menos claro	Mais claro
`Rule 1`	`Block night transactions above BRL 5,000`
`Block high`	`Deny high-value weekend transactions`
`Pix rule`	`Review Pix transfers to new recipients`

Design de expressões

Mantenha as expressões simples - lógica complexa é mais difícil de manter
Use escopos para filtragem - não repita condições de escopo nas expressões
Teste casos extremos - considere valores limite e campos nulos

Gerenciamento do 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 usadas - mantenha a trilha de auditoria intacta
Exclua apenas quando tiver certeza - a exclusão é permanente

Monitoramento

Revise as regras correspondentes - verifique quais regras disparam
Monitore as taxas de DENY - taxas altas de negação podem indicar regras excessivamente agressivas
Audite regularmente - garanta que as regras ainda estejam alinhadas com os requisitos de negócio

Armadilhas comuns ao trabalhar com regras:

“Editei a expressão, mas a mudança não teve 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 depois reative. Apenas INACTIVE não basta.
“Minha regra está ACTIVE, mas outra instância do Tracer ainda não está avaliando essa regra.” A ativação tem efeito imediato na instância que atendeu a chamada de ativação. Quando você roda várias instâncias atrás de um load balancer, 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 os testes de integração considerando essa janela quando as chamadas podem cair em instâncias diferentes.
“Quero excluir uma regra ACTIVE.” Não é possível. Chame POST /v1/rules/{id}/deactivate primeiro, depois DELETE /v1/rules/{id}. Isso força um passo visível em que a regra deixa de afetar o tráfego antes de desaparecer das listagens.
“Meu escopo vazio {} é rejeitado com o código de erro 0358.” Todo objeto de escopo deve ter pelo menos um campo definido. Para rodar uma regra globalmente (contra toda transação), omita o array scopes completamente. Não envie {}.

Referência rápida

Principais endpoints, ações e informações de status.

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`
Mover regra para draft	POST	`/v1/rules/{id}/draft`

Status

Status	Avaliado	Editável	Pode excluir
`DRAFT`	Não	Sim	Sim
`ACTIVE`	Sim	Parcial (expressão imutável)	Não (desative primeiro)
`INACTIVE`	Não	Parcial (expressão imutável; volte 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 básicos

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 baseadas em tempo

Usando metadados

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

Boas práticas

Nomenclatura

Design de expressões

Gerenciamento do 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 básicos

​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 baseadas em tempo

​Usando metadados

​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

​Boas práticas

​Nomenclatura

​Design de expressões

​Gerenciamento do 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 básicos

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 baseadas em tempo

Usando metadados

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

Boas práticas

Nomenclatura

Design de expressões

Gerenciamento do ciclo de vida

Monitoramento

Referência rápida

Endpoints

Status