Skip to main content
Um responsável por compliance entrega uma frase: “negue compras com cartão sem presença física acima de BRL 5.000 a partir de um dispositivo que não vimos antes.” Este guia transforma essa frase em uma regra que avalia do jeito que a política lê, ensaia essa regra onde ela não alcança ninguém e a coloca no ar. O que muda na sua operação: a política deixa de morar em um ticket e passa a morar em um endpoint. A pessoa que escreveu a frase consegue ler a regra de volta, o ensaio roda por avaliação real em vez de uma planilha, e cada mudança na regra deixa um evento de auditoria atrás de si.
Para quem é este guia? Analistas de risco e fraude que escrevem regras, e os desenvolvedores que ligam os campos da política à requisição de validação. Os passos 1 e 2 tratam da política; os passos 3 a 8 são chamadas de API.

​
Antes de começar

  • Tracer em execução e acessível, com uma API key — veja Primeiros passos
  • As variáveis e o modelo de escopo — veja o Motor de regras
  • Um id de conta de teste para o qual você possa enviar validações, que nenhum tráfego de clientes use
  • A frase da política, por escrito, com quem a escreveu disponível para uma pergunta
Todas as chamadas abaixo enviam a API key como X-API-Key.

​
Passo 1: Mapeie a frase sobre os campos

Uma regra lê o que a requisição de validação carrega. Decomponha a frase cláusula por cláusula e coloque cada uma na coluna à qual ela pertence. Os dois primeiros são campos que o Tracer define. Os dois últimos são campos que sua integração precisa enviar — o Tracer não tem opinião sobre o que “sem presença física” ou “dispositivo novo” significam. Essa é a pergunta para levar de volta a quem escreveu a política: qual sinalizador do nosso payload diz que o dispositivo é novo?
subType chega às expressões em minúsculas, então "card_not_present" é a forma contra a qual comparar. Se sua integração já usa subType para outra coisa, leve o modo de entrada em metadata e compare contra isso — os dois funcionam do mesmo jeito em uma expressão.
Para a lista completa de variáveis e os campos que cada mapa de contexto carrega, veja o Motor de regras.

​
Passo 2: Divida a regra entre escopo e expressão

Duas coisas daquela tabela — o tipo de transação e a conta — são coisas que o Tracer consegue filtrar antes de uma expressão rodar. Elas pertencem aos scopes da regra. As comparações de valor pertencem à expression. Escopo, que decide se a regra é sequer considerada:
Expressão, que decide se a regra dispara:
Leia a expressão contra a frase: modo de entrada, limiar e o sinalizador do dispositivo. amount > 5000 é estritamente maior, então uma transação de exatamente 5000.00 não dispara a regra — confira isso contra a política antes de seguir, porque “acima de” e “a partir de” são regras diferentes. Uma regra que lê uma chave de metadata que a requisição não carrega não corresponde, e as outras regras continuam rodando. Por isso a expressão acima não precisa de um teste de presença para deviceFirstSeen; veja o Motor de regras.
Não repita as condições de escopo dentro da expressão. transactionType == "CARD" nos dois lugares não está errado, mas deixa dois lugares para editar quando a política mudar — e a expressão é a que precisa de uma volta completa pelo ciclo de vida para ser editada.

​
Passo 3: Crie a regra como rascunho

POST /v1/rules cria a regra em DRAFT. Um rascunho não é avaliado, então nada do que você fizer aqui alcança o tráfego.
O accountId nesse escopo é a sua conta de teste. É o que mantém o passo 4 fora do tráfego de clientes; o passo 5 o remove. Um 201 responde com a regra armazenada:
O Tracer armazena o nome da regra em uma forma normalizada, então o name que ele devolve pode diferir da string que você enviou. Pegue o ruleId da resposta — esse é o identificador que toda chamada abaixo usa. Veja Criar uma regra. A expressão é compilada nesta chamada, então uma expressão que não consegue rodar nunca vira um rascunho. Um erro de sintaxe responde 0340, uma expressão que não retorna um booleano responde 0341, e uma cujo custo estimado está acima de CEL_COST_LIMIT responde 0342.

​
Passo 4: Ensaie em uma conta que ninguém mais usa

O escopo que você definiu é o que mantém o ensaio contido: a regra é considerada apenas para transações daquela única conta de teste, então ativá-la a coloca na frente de exatamente o tráfego que você enviar.
1

Ative a regra com escopo

A resposta volta com status: "ACTIVE" e um activatedAt. Veja Ativar uma regra.
2

Envie uma transação que a política deveria negar

Veja Validar uma transação.
3

Leia a decisão

O seu ruleId em matchedRuleIds é o ensaio passando.
4

Envie os casos que não deveriam disparar

Mude um valor por vez e repita a chamada com um requestId novo: "amount": "5000.00" para o limite exato, "deviceFirstSeen": false para um dispositivo conhecido, "subType": "purchase" para uma venda com presença física. Cada uma deve voltar sem o seu ruleId em matchedRuleIds.
Envie um requestId novo a cada tentativa. requestId é a chave de idempotência: repita um e o Tracer responde 200 com a decisão que ele já registrou para aquela chave, então a mudança que você acabou de fazer vai parecer não ter feito nada.
Um ensaio é uma validação real. Ele armazena um registro de decisão e escreve um evento de auditoria, e uma decisão ALLOW consome os limites de gasto que cobrem aquela conta. É por isso que a conta de teste importa.
Se o seu ruleId não estiver em matchedRuleIds, percorra nesta ordem: a regra está ACTIVE (GET /v1/rules/{id})?, a transação corresponde ao escopo que você definiu?, os valores que você enviou satisfazem a expressão?

​
Passo 5: Coloque no ar

Entrar em produção significa uma edição: tire a conta de teste do escopo para que a regra se aplique à população que a política nomeia.
1

Pare de avaliar a versão de ensaio

Editar o escopo não exige INACTIVE. Desativar primeiro faz a troca surtir efeito em um momento que você controla e deixa uma lacuna visível no rastro de auditoria. Cada instância serve as regras a partir de um cache que ela atualiza por sondagem (a cada 10 segundos por padrão, RULE_SYNC_POLL_INTERVAL_SECONDS), então aguarde essa janela para a desativação alcançar todas as instâncias; GET /v1/rules confirma o status armazenado, não que cada instância já se atualizou.
O status vai para INACTIVE. Veja Desativar uma regra.
2

Substitua o escopo

scopes substitui o array inteiro — envie cada objeto de escopo que você quer que a regra mantenha. Veja Atualizar uma regra.
3

Ative

A ativação alcança a instância que atendeu esta chamada assim que ela é confirmada. 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 viaja do mesmo jeito. Aguarde essa mesma janela depois de ativar antes de considerar a regra valendo em todas as instâncias.
4

Confirme o que está no ar

A listagem responde “o que está valendo no tráfego de cartão agora” — veja Listar regras. Para uma regra só, GET /v1/rules/{id} devolve a expressão e os escopos como estão armazenados (Recuperar uma regra). Os dois retornam o estado armazenado, não o que o cache de cada instância guarda.
Uma validação carrega o conjunto de regras dela uma vez, do cache da instância que atende a chamada, quando a chamada começa. Uma regra que é ativada enquanto uma validação está em voo não faz parte daquela decisão, e decisões já registradas não mudam quando as regras mudam depois.

​
Passo 6: Saiba onde a sua regra fica entre as outras

As regras não têm campo de prioridade nem ordem para configurar. Regras cujo escopo corresponde a uma transação são avaliadas juntas, e a decisão vem da ação mais estrita que disparou: primeiro uma regra DENY, depois um limite de gasto excedido, depois REVIEW, depois ALLOW, depois o padrão configurado para quando não há correspondência. matchedRuleIds carrega cada regra que correspondeu, seja qual for a ação de cada uma. Duas consequências para a regra que você acabou de escrever:
  • Uma regra ALLOW não isenta ninguém de uma regra DENY. Se a política tem uma exceção — clientes VIP, um lojista parceiro — a exceção pertence dentro da expressão DENY, como mais uma condição que a torna mais estreita:
    Repare no que isso custa: a regra estreitada agora lê metadata.customerTier, e uma requisição que não carrega essa chave não corresponde a ela.
  • A sua regra entra no conjunto que cada transação correspondente avalia. MAX_RULES_PER_REQUEST limita quantas regras uma validação avalia; quando o conjunto é maior, a resposta reporta truncated: true — veja variáveis de ambiente.
A tabela de precedência e o raciocínio por trás dela estão na página do Motor de regras.

​
Passo 7: Mude a regra quando a política mudar

O que você faz depende do campo, não de como a regra está indo.
A expression aceita uma edição apenas enquanto a regra está em DRAFT. Enviar uma para uma regra em outro status responde 422 com o código de erro 0351 — desativar não basta sozinho, porque INACTIVE não é DRAFT. POST /v1/rules/{id}/draft é o passo que as pessoas esquecem; veja Voltar uma regra para rascunho.
Um PATCH fica armazenado quando responde, e chega à avaliação na próxima sincronização de regras. Quando a mudança importa ao minuto, desative primeiro e ative de novo depois — essa sequência ainda deixa uma lacuna visível no rastro de auditoria onde a regra não estava valendo, que é o que quem revisa vai procurar. O ciclo de vida é um conjunto fechado de movimentos: DRAFT é ativado ou excluído; ACTIVE é desativado; INACTIVE volta para DRAFT, volta para ACTIVE ou é excluído; DELETED é o fim. Qualquer outra coisa responde 422 com o código de erro 0349 — inclusive um pedido para voltar para rascunho uma regra que ainda está ACTIVE.

​
Passo 8: Aposente ou exclua a regra

Para parar de valer sem perder nada, desative. A regra mantém a expressão, os escopos e a história dela, para de ser avaliada, e POST /v1/rules/{id}/activate a traz de volta. Esse é o movimento para uma política suspensa, sazonal ou em revisão. Para removê-la, exclua — e só depois de desativar, porque uma regra em ACTIVE não pode ser excluída:
Um 204 responde em caso de sucesso. Veja Excluir uma regra. O que a exclusão remove:
  • A regra para de responder em GET /v1/rules/{id}, que devolve 404 com o código de erro 0347 a partir de então.
  • Ela não aparece mais em GET /v1/rules, e DELETED não é um valor que o filtro status aceita.
  • DELETED é o fim do ciclo de vida. Nenhum endpoint tira uma regra de lá — uma regra excluída volta apenas como uma regra nova que você crie de novo.
O que a exclusão deixa para trás:
  • O rastro de auditoria mantém o ciclo de vida da regra, e o evento RULE_DELETED carrega a definição — nome, descrição, expressão, ação, escopos — como ela estava na exclusão. Veja Auditoria e compliance.
  • As decisões que a regra produziu mantêm o ruleId dela em matchedRuleIds. Uma negativa de seis meses atrás ainda a nomeia — veja Revisar uma transação negada.
  • O nome fica disponível de novo para uma regra nova no mesmo contexto.
Desative, depois leia o rastro de auditoria, depois exclua. Desativar é reversível em uma chamada e excluir não é reversível de jeito nenhum, então não há razão para pular o estado intermediário.

​
Erros comuns

O que costuma dar errado ao transformar uma política em regra:
  • “A regra está ACTIVE mas nada corresponde.” Verifique o campo em que a política mais se apoia. Uma regra que lê metadata.deviceFirstSeen não corresponde a nada se a sua integração nunca envia essa chave — a regra está correta e o payload está incompleto.
  • “Ela disparou em uma transação que a política isenta.” Uma regra ALLOW não anula uma DENY. Coloque a isenção dentro da expressão DENY (passo 6).
  • “Meu segundo ensaio devolveu a primeira decisão.” requestId é a chave de idempotência. Envie um UUID novo a cada tentativa.
  • “O PATCH rejeitou minha expressão com 422.” A regra não estava em DRAFT. Mova-a para lá primeiro (passo 7).
  • “O nome que enviei não é o nome que recebo.” O Tracer armazena os nomes em uma forma normalizada. Referencie a regra pelo ruleId.

​
Códigos de erro

A lista completa está na Lista de erros do Tracer.

​
Referência rápida