Pular para o conteúdo principal
O motor de regras do Tracer permite construir lógica de validação poderosa sem escrever código. Usando CEL (Common Expression Language) - uma linguagem de expressões type-safe desenvolvida pelo Google - você pode criar regras sofisticadas que avaliam em menos de 1ms, automatizar decisões de negócios complexas e se adaptar rapidamente a novos requisitos.

​
Por que usar o motor de regras

  • Flexibilidade: Crie e modifique regras sem deploys de código
  • Desempenho: Expressões compiladas avaliam em menos de 1ms cada
  • Segurança de tipos: Sintaxe da expressão validada na criação da regra
  • Avaliação completa: Todas as regras ativas são avaliadas para trilha de auditoria abrangente
  • 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

Neste fluxo:
  • Carregar regras busca todas as regras ativas do cache (ou banco de dados em caso de cache miss)
  • Avaliar expressões executa todas as expressões CEL contra o contexto da transação
  • Coletar correspondências reúne todas as regras que corresponderam e determina a decisão

​
Padrão de avaliação

Todas as regras ativas são avaliadas contra cada transação. 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:
  • Se qualquer regra DENY corresponder, o Tracer retorna uma decisão DENY
  • Se apenas regras ALLOW corresponderem, o Tracer retorna uma decisão ALLOW
  • Se nenhuma regra corresponder, o Tracer retorna o padrão configurado (tipicamente ALLOW para comportamento fail-open)
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

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

merchant.category == "gambling"
Expressões têm acesso ao contexto completo da requisição de validação incluindo:
  • amount - Valor da transação em centavos (menor unidade da moeda)
  • transactionType - CARD, WIRE, PIX, CRYPTO
  • subType - Subtipo da transação (ex.: debit, credit, international)
  • currency - Código de moeda ISO 4217
  • transactionTimestamp - Quando a transação ocorreu
  • account - AccountId, segmentId, portfolioId
  • segment - SegmentId e metadados do segmento
  • portfolio - PortfolioId e metadados do portfólio
  • merchant - MerchantId, category, country, riskLevel (opcional)
  • metadata - Campos personalizados passados na requisição

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

​
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çãoDescrição
ALLOWPermitir a transação
DENYNegar a transação
REVIEWEncaminhar para revisão manual

​
Escopos

Escopos definem a quais transações uma regra se aplica. Uma regra só avalia contra transações que correspondem a pelo menos um de seus escopos. Campos de escopo (todos opcionais):
  • 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.)
Se um campo de escopo não for especificado, ele corresponde a qualquer valor para esse campo.

​
Ciclo de vida da regra

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

​
Estados

EstadoDescrição
DRAFTNão avaliada; expressão pode ser modificada livremente
ACTIVEAvaliada durante validações; expressão é imutável
INACTIVENão avaliada; preservada para trilha de auditoria; pode ser reativada
DELETEDRemovida permanentemente; não aparece nas listagens; não pode ser recuperada

​
Transições

TransiçãoDeParaDescrição
activateDRAFT, INACTIVEACTIVEIniciar avaliação (valida expressão)
deactivateACTIVEINACTIVEParar avaliação
deleteDRAFT, INACTIVEDELETEDRemoçã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 único e descritivo
  • 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çãoEndpointDescrição
AtivarPOST /v1/rules/{ruleId}/activateIniciar avaliação desta regra
DesativarPOST /v1/rules/{ruleId}/deactivateParar 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âmetroTipoDescrição
statusstringFiltrar por status (DRAFT, ACTIVE, INACTIVE)
pageSizeintegerItens por página (padrão: 100, máx: 1000)
pageTokenstringToken de paginação

​
Obter uma regra específica

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

​
Atualizar uma regra

Atualize regras usando PATCH /v1/rules/{ruleId}. Regras podem ser atualizadas em qualquer status, com uma restrição importante:
O campo expression não pode ser atualizado enquanto a regra estiver ACTIVE. Desative a regra primeiro para modificar sua expressão.

​
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/{ruleId}
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 claroMais claro
Regra 1Bloquear transações noturnas acima de R$ 5.000
Bloquear altoNegar transações de alto valor no fim de semana
Regra PIXRevisar 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
  • Desative antes de editar - Nunca edite regras ativas
  • 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

​
Referência rápida

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

​
Endpoints

OperaçãoMétodoEndpoint
Criar regraPOST/v1/rules
Listar regrasGET/v1/rules
Obter regraGET/v1/rules/{id}
Atualizar regraPATCH/v1/rules/{id}
Excluir regraDELETE/v1/rules/{id}
Ativar regraPOST/v1/rules/{id}/activate
Desativar regraPOST/v1/rules/{id}/deactivate

​
Ações

AçãoDescrição
ALLOWPermitir a transação
DENYNegar a transação
REVIEWEncaminhar para revisão manual

​
Status

StatusAvaliadaEditávelPode excluir
DRAFTNãoSimSim
ACTIVESimParcial (expression imutável)Não (desativar primeiro)
INACTIVENãoSimSim
DELETEDNãoNãoN/A