logo
Começando•

Regras inteligentes: atributos, operadores e valores

Todos os atributos, operadores e valores aceitos pelas Regras inteligentes — nomes de dispositivo, códigos de país, região, continente e idioma, formatos de referenciador e UTM — além de limites, mensagens de validação, precedência e planos.

Avatar for undefined
CodeQR Team
Equipe de Conteúdo

Use esta página para consultar o que uma Regra inteligente consegue testar, quais valores combinam e os limites que o app e a API aplicam. Para a lógica de decisão e a solução de problemas veja Como as Regras inteligentes escolhem o destino; para payloads veja Crie Regras inteligentes com a API, o MCP e automações.

Disponibilidade

  • Plano — Business ou superior. Free, Starter e Pro: o botão mostra o selo Business; a API devolve 403 forbidden para qualquer rules não vazio
  • Links — todos os links; seção Regras inteligentes no construtor de links
  • QR Codes — apenas QR Codes dinâmicos do tipo URL; QR Codes estáticos e de outros tipos (Wi-Fi, vCard, WhatsApp, texto, e-mail, telefone) não avaliam regras
  • Superfícies — app web, API REST (rules em links e QR Codes), MCP (create_link, update_link), automações via API, webhooks (link.created, link.updated carregam rules)

Anatomia de uma regra

  • Condição — No app: atributo + é / não é + valor · Na API: attribute, operator, value · Obrigatório: os três, ou nenhum (= Todo o tráfego)
  • Destino — No app: URL de destino · Na API: url · Obrigatório: um entre url / split
  • Divisão — No app: Dividir tráfego (teste A/B) → URL da variante + Peso da variante (%) ×2–4 · Na API: split: [{ url, weight }] · Obrigatório: um entre url / split

Atributos

  • Dispositivo — attribute na API: device · O que é comparado: nome do sistema operacional no user agent · Valores aceitos: iOS, Android, Windows, Mac OS (exibido como macOS), Linux · Exemplo: iOS
  • País — attribute na API: country · O que é comparado: país do endereço IP do visitante · Valores aceitos: ISO 3166-1 alfa-2, duas letras (lista no app) · Exemplo: BR, PT, US
  • Região (estado) — attribute na API: region · O que é comparado: subdivisão do endereço IP do visitante · Valores aceitos: código ISO 3166-2 sem o prefixo do país · Exemplo: SP, RJ, CA
  • Cidade — attribute na API: city · O que é comparado: cidade do endereço IP do visitante · Valores aceitos: nome da cidade como reportado pela geolocalização · Exemplo: São Paulo, Lisboa
  • Continente — attribute na API: continent · O que é comparado: continente do endereço IP do visitante · Valores aceitos: AF África, AN Antártida, AS Ásia, EU Europa, NA América do Norte, OC Oceania, SA América do Sul · Exemplo: SA
  • Idioma — attribute na API: language · O que é comparado: primeiro idioma suportado no Accept-Language do navegador, sem a região · Valores aceitos: pt, en, es, fr, de, zh, ru, it, ja, ko (Português, English, Español, Français, Deutsch, 中文, Русский, Italiano, 日本語, 한국어) · Exemplo: pt (combina com pt-BR, pt-PT)
  • Referenciador — attribute na API: referrer · O que é comparado: hostname da página de origem, sem o www. inicial · Valores aceitos: domínio puro · Exemplo: instagram.com, l.facebook.com
  • Origem UTM — attribute na API: utm_source · O que é comparado: utm_source na query string do link curto · Valores aceitos: qualquer texto · Exemplo: newsletter
  • Mídia UTM — attribute na API: utm_medium · O que é comparado: utm_medium na query string do link curto · Valores aceitos: qualquer texto · Exemplo: email
  • Campanha UTM — attribute na API: utm_campaign · O que é comparado: utm_campaign na query string do link curto · Valores aceitos: qualquer texto · Exemplo: promo-agosto
  • Termo UTM — attribute na API: utm_term · O que é comparado: utm_term na query string do link curto · Valores aceitos: qualquer texto · Exemplo: qr code
  • Conteúdo UTM — attribute na API: utm_content · O que é comparado: utm_content na query string do link curto · Valores aceitos: qualquer texto · Exemplo: cartaz-a

Observações:

  • O app oferece listas para Dispositivo, País, Idioma e Continente; os demais atributos são texto livre.
  • A API grava qualquer string de 1 a 190 caracteres como value. Um valor que a requisição nunca carrega (mobile, desktop, tablet, Brasil, BR-SP, uma URL completa de referenciador) é salvo e nunca combina.
  • Dispositivo é o sistema operacional, então não existe "celular" nem "tablet". iPad com Safari em modo desktop reporta macOS.
  • Idioma não é localização: vem do navegador. Navegadores que preferem um idioma fora dos dez acima não combinam com nenhuma regra de Idioma.
  • Os valores de UTM são lidos do link curto como foi clicado (https://go.example.com/promo?utm_source=newsletter), não da URL de destino nem dos campos UTM salvos do link. utm_id não está disponível.
  • Quando a requisição não traz valor para o atributo (localização desconhecida, sem referenciador, ?utm_source= vazio, idioma não suportado), a regra não combina — nem com é nem com não é.

Operadores

  • é — operator na API: equals · Combina quando: o valor da requisição é igual ao valor da regra, comparando a string inteira, sem diferenciar maiúsculas
  • não é — operator na API: not_equals · Combina quando: a requisição traz um valor para o atributo e ele é diferente do valor da regra

Não existe "contém", "começa com", expressão regular nem lista de valores. Cada regra tem exatamente uma condição; use várias regras em ordem para combiná-las.

Dividir tráfego

  • Variantes — 2 a 4
  • Peso — número inteiro de 1 a 100 por variante; os pesos somam exatamente 100
  • Distribuir igualmente — 2 → 50/50, 3 → 34/33/33, 4 → 25/25/25/25 (o resto vai para a primeira variante)
  • Atribuição — hash do link + ID do clique → balde 0–99 → variante pelo peso acumulado
  • Fixa por — 1 hora, ou 30 dias quando o Monitoramento de conversão está ativo (cookie cq_id no caminho do link curto)
  • Onde é permitida — em qualquer regra (com ou sem condição); uma regra sem condição (Todo o tráfego) sempre divide e precisa ser a última
  • Resultados — Análise → card URLs, uma linha por URL de destino

Limites

  • Regras por link ou QR Code — 20
  • Tamanho do valor — 1–190 caracteres
  • Regras sem condição — no máximo uma, na última posição
  • URLs de destino — precisam ser URLs válidas; toda URL de regra e de variante passa pela mesma verificação de segurança do destino principal

Mensagens de validação

App (embaixo da regra): Os pesos precisam somar 100%. · Cada peso precisa ser um número inteiro entre 1 e 100. · Toda variante precisa de uma URL. · Uma regra sem condição sempre divide o tráfego entre as variantes. (dica no botão de divisão desabilitado de uma regra Todo o tráfego) · Smart rules are only available for dynamic QR codes (dica no botão desabilitado de um QR Code estático — texto em inglês no app).

API (400, error.code unprocessable_entity, mensagem prefixada com o índice da regra): A rule needs either a destination url or a traffic split, never both · A rule condition needs attribute, operator and value together · A rule without a condition must split traffic · Split weights must add up to 100 · A rule without a condition matches all traffic, so it must be the last one · Invalid URL · Invalid enum value. Expected 'device' | 'country' | … · String must contain at most 190 character(s) · Array must contain at most 20 element(s).

API (403 forbidden): Smart rules are available on the Business plan and above. Upgrade to Business to use this feature. · Smart rules can only be used on dynamic QR codes.

Precedência

  1. Proteção por senha, expiração, links banidos e o formulário de pré-redirecionamento são tratados antes de qualquer regra de redirecionamento.
  2. Camuflagem de links vence as Regras inteligentes: um link camuflado mostra a sua URL de destino; as regras são ignoradas.
  3. Regras inteligentes, de cima para baixo, a primeira que combina vence.
  4. Segmentação iOS, Segmentação Android, Segmentação Geográfica (botões antigos), nessa ordem.
  5. A URL de destino do link.

Os parâmetros de query recebidos são anexados ao destino escolhido; com Monitoramento de conversão ativo, cq_id é acrescentado. Os redirecionamentos respondem 302 (301 para um domínio raiz).

Artigos relacionados