Tutorial dev: como montar payloads json complexos para testar regras de flag no simulador do useflagly em 2026

Testar regras de segmentação em produção sem validação prévia é uma das formas mais rápidas de introduzir falhas silenciosas na experiência do usuário. Quando trabalhamos com fluxos críticos — como gateways de pagamento, esteiras de checkout e Canary Releases —, pequenas divergências na tipagem de atributos ou na hierarquia do payload podem fazer com que uma regra falhe silenciosamente, entregando a variante incorreta. O Simulador de Avaliação em Tempo Real do UseFlagly resolve esse problema ao permitir que engenheiros submetam estruturas JSON completas e inspecionem o comportamento das decisões de toggles antes de qualquer release.

Este tutorial foi construído para desenvolvedores backend, frontend e engenheiros de confiabilidade que precisam validar cenários complexos com precisão matemática. Em vez de depender de deploys sucessivos em ambientes de homologação ou disparar requisições manuais cegas contra APIs de avaliação, você aprenderá a estruturar dados contextuais aninhados, testar operadores lógicos e interpretar os vereditos detalhados retornados pelo motor de avaliação. O objetivo final é eliminar completamente o blast radius gerado por regras mal configuradas.

Com a metodologia institucional do UseFlagly, o processo de entrega ganha previsibilidade: o deploy de artefatos de código continua ocorrendo de forma contínua via CI/CD, enquanto a liberação funcional é testada e governada isoladamente. Ao dominar a montagem de payloads complexos no simulador, seu time garante que apenas regras validadas e testadas contra casos de borda entrem no fluxo de entrega em 2026.

Fase 1: preparação & pré-requisitos

Antes de abrir a interface do simulador, é fundamental mapear a árvore de decisão da funcionalidade e compreender como a engine hierárquica do UseFlagly consome os dados. O motor de avaliação organiza as regras em uma estrutura encadeada: Cenário (módulo maior), Fluxo (pipeline de regras encadeadas), Parte de Fluxo (blocos reutilizáveis) e Feature Flag (o seletor final entregue à aplicação cliente). Para que a avaliação ocorra com exatidão, seu payload JSON precisa fornecer os atributos exatos exigidos pelas condicionais do fluxo.

O payload padrão consumido pela API REST e pelo simulador exige três chaves raiz essenciais: environment, identifier e attributes. O campo environment aceita valores como PRD ou HML, definindo o escopo das regras ativas. O identifier é a chave primária do usuário (como um UUID ou user ID do banco de dados), elemento indispensável para o algoritmo de hashing determinístico e idempotente usado em rollouts graduais. Por fim, o objeto attributes abriga pares de chave-valor contendo dados contextuais, demográficos e operacionais do usuário ou da transação.

Para preparar seu ambiente de teste, acesse o painel e tenha em mãos o esquema da flag configurada. Liste todos os tipos de dados envolvidos nas regras: strings (ex: planos, slugs de tenants), números (ex: ticket médio, saldo de pontos, volume de pedidos), booleanos (ex: isBetaTester) e arrays de identificadores. Garantir essa coerência de tipos logo no rascunho do payload impede falsos negativos durante a simulação.

Fase 2: execução passo a passo

A montagem de um payload JSON complexo requer a correta estruturação dos atributos para atender a múltiplas regras concorrentes. Considere um cenário de checkout onde a flag pix-parcelado-v2 só deve ser ativada para clientes do plano Enterprise, situados no Brasil, com score de crédito superior a 750 e que façam parte de uma lista de permissão (Allowlist). No editor do simulador, monte a estrutura base conforme o padrão da API do UseFlagly:

{ "environment": "PRD", "identifier": "usr_live_884920a", "attributes": { "email": "techlead@empresa.com.br", "tier": "ENTERPRISE", "country": "BR", "creditScore": 810, "accountAgeMonths": 24, "isBetaTester": true, "billing": { "currency": "BRL", "monthlySpend": 15400.50, "inGoodStanding": true } } }

Cole o payload no editor do simulador em useflagly.com.br/simulador e clique no botão de disparo de avaliação. O simulador submeterá a requisição contra a mesma engine que processa os endpoints oficiais do protocolo universal OFREP e da REST API direta (https://api.useflagly.com.br/validate). Em milissegundos, o painel exibirá o resultado visual da execução.

Observe o detalhamento passo a passo: a engine lista cada condicional do fluxo individualmente, exibindo o status de passed ou failed para cada cláusula avaliada. Se o creditScore estiver acima de 750 e o tier for igual a ENTERPRISE, o simulador marcará as regras com o status verde de MATCH. Se uma única cláusula restritiva falhar (por exemplo, caso altere o country para US), o motor indicará NO MATCH e exibirá o valor de fallback definido para a flag.

Fase 3: validação & testes de qualidade

A fase de validação consiste em testar os casos de borda e garantir a integridade dos dados sob condições adversas. O primeiro teste mandatório é a mutação controlada de valores. Altere deliberadamente o atributo creditScore para valores limítrofes, como 749 e 750, para verificar se o operador numérico foi configurado como maior estrito (>) ou maior ou igual (>=). Esse teste simples previne desvios de regra que costumam passar despercebidos em testes unitários convencionais.

O segundo teste crítico envolve validar o comportamento do Canary Release determinístico. Altere apenas o valor do campo identifier (por exemplo, de usr_live_884920a para usr_live_99103bc) mantendo os mesmos atributos contextuais. Como o UseFlagly utiliza hashing determinístico para distribuir tráfego progressivo (ex: 1%, 5%, 25%, 50%), você poderá auditar em tempo real se o identificador em teste cai dentro ou fora da fatia percentual selecionada no rollout gradual.

Por fim, execute a simulação do Kill-Switch de emergência. Desative momentaneamente o toggle correspondente no painel e repita a submissão do mesmo payload complexo. O simulador deve retornar instantaneamente o status inativo da flag, confirmando que, em caso de instabilidade no gateway de destino ou falha de infraestrutura de terceiros, a funcionalidade será cortada em menos de 1 segundo sem necessidade de deploy ou rollback de aplicação.

Checklist completo de execução

• Fase 1: Pré-requisitos — Cenário, Fluxo e Feature Flag devidamente instanciados no painel do UseFlagly

• Fase 1: Mapeamento de Tipos — Strings, inteiros, floats e booleanos catalogados sem divergência de tipagem

• Fase 2: Estrutura Raiz — Payload contendo estritamente as chaves 'environment', 'identifier' e 'attributes'

• Fase 2: Simulação Base — Execução realizada no simulador interativo com veredito 'MATCH' verificado

• Fase 3: Casos de Borda — Testes de operadores limítrofes (ex: >= vs >) executados com sucesso

• Fase 3: Hashing Determinístico — Identificadores alternados para validação da distribuição de Canary Release

• Fase 3: Validação de Kill-Switch — Comportamento do seletor testado com toggle desativado

• Monitoramento — Alertas de alteração de flag e faturamento (limite de 80%) ativos no dashboard

Elimine o risco em produção testando suas regras agora mesmo. Crie sua conta gratuita no UseFlagly e explore todos os recursos do simulador em useflagly.com.br/simulador no plano Hobby sem precisar de cartão de crédito.