logo
Começando•

Roteie o tráfego de campanha por UTM ou referenciador

Envie o tráfego da newsletter, de anúncios ou de redes sociais para uma landing page própria a partir de um único link curto, usando parâmetros UTM no link ou o site de origem — passos, API, MCP e os casos em que o referenciador vem vazio.

Avatar for undefined
CodeQR Team
Equipe de Conteúdo

Ao final deste guia, um único link curto envia quem clicou nele na sua newsletter para uma oferta de assinantes, quem veio do Instagram para uma oferta do Instagram e todos os demais para a página padrão — enquanto os parâmetros UTM continuam chegando à sua ferramenta de análise.

Disponibilidade

  • Plano: Business ou superior (preços).
  • Onde: construtor de links → Regras inteligentes. Mesma seção no editor de QR Code para QR Codes dinâmicos do tipo URL.

Antes de começar

  • Decida qual sinal vai usar no roteamento:
  • Origem / Mídia / Campanha / Termo / Conteúdo UTM — a CodeQR lê esses parâmetros da query string do link curto como foi clicado, por exemplo https://go.example.com/promo?utm_source=newsletter. Você controla esse sinal por completo: ele está na URL que você distribui.
  • Referenciador — o domínio da página de onde o visitante veio, sem www. (instagram.com, news.ycombinator.com). Você não controla esse sinal: aplicativos, mensageiros e leituras de QR Code não enviam referenciador nenhum (veja Solução de problemas). Prefira UTM sempre que puder marcar o link.
  • O destino de cada público e uma página padrão para a URL de destino do link.
  • Atenção: o UTM Builder do construtor de links acrescenta parâmetros ao destino; a regra lê parâmetros do link curto. Coloque os UTMs na URL que você compartilha.

Passos

  1. Abra Links e clique em Adicionar Link, ou abra um link existente e escolha Editar.
  2. Informe a página padrão em URL de destino, por exemplo https://example.com/ofertas/.
  3. Ative Regras inteligentes.
  4. Na primeira regra, selecione Origem UTM, mantenha é e digite newsletter.
  5. Na URL de destino dessa regra, informe https://example.com/ofertas/assinantes.
  6. Clique em Adicionar regra. Selecione Referenciador, mantenha é, digite instagram.com e informe https://example.com/ofertas/instagram.
  7. Clique em Criar link (ou Salvar link).
  8. Distribua o link curto marcado na newsletter: https://go.example.com/promo?utm_source=newsletter&utm_campaign=agosto. Coloque o link curto simples https://go.example.com/promo na bio do Instagram.

Duas Regras inteligentes: Origem UTM é newsletter apontando para uma oferta de assinantes e Referenciador é instagram.com apontando para uma oferta do Instagram

Tudo o que está na query string do link curto é repassado ao destino, então ?utm_source=newsletter&utm_campaign=agosto chega a https://example.com/ofertas/assinantes?utm_source=newsletter&utm_campaign=agosto e sua ferramenta de análise atribui a visita normalmente.

O mesmo pela API

Requisição:

curl -X PUT https://api.codeqr.io/links/cmswk759f0001j41i0vj1vmfq \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "attribute": "utm_source", "operator": "equals", "value": "newsletter",
        "url": "https://example.com/ofertas/assinantes" },
      { "attribute": "referrer",   "operator": "equals", "value": "instagram.com",
        "url": "https://example.com/ofertas/instagram" }
    ]
  }'

Resposta (200 OK):

{
  "id": "cmswk759f0001j41i0vj1vmfq",
  "domain": "go.example.com",
  "key": "promo",
  "url": "https://example.com/ofertas/",
  "archived": false,
  "expiresAt": null,
  "expiredUrl": null,
  "password": null,
  "externalId": null,
  "trackConversion": false,
  "proxy": false,
  "title": null,
  "description": null,
  "image": null,
  "video": null,
  "utm_source": null,
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "rewrite": false,
  "doIndex": false,
  "banned": false,
  "flexible": false,
  "filled": false,
  "ios": null,
  "android": null,
  "geo": null,
  "rules": [
    { "url": "https://example.com/ofertas/assinantes", "value": "newsletter",    "operator": "equals", "attribute": "utm_source" },
    { "url": "https://example.com/ofertas/instagram",  "value": "instagram.com", "operator": "equals", "attribute": "referrer" }
  ],
  "userId": "cm73yc6m70002mtesulffnrgb",
  "folderId": null,
  "projectId": "cm73y7wm100008j24i1b137wr",
  "preRedirection": false,
  "pageId": null,
  "pageUrl": null,
  "isFormMandatory": false,
  "publicStats": false,
  "clicks": 0,
  "lastClicked": null,
  "leads": 0,
  "sales": 0,
  "saleAmount": 0,
  "createdAt": "2026-08-17T01:32:38.884Z",
  "updatedAt": "2026-08-17T02:14:10.212Z",
  "tagId": null,
  "comments": null,
  "notificationToken": null,
  "useAsTemplate": false,
  "tags": [],
  "shortLink": "https://go.example.com/promo",
  "webhookIds": [],
  "qrCode": "https://api.codeqr.io/qr?url=https://go.example.com/promo?qr=1"
}

O mesmo array rules funciona em POST /links, POST /qrcodes (dinâmico, tipo url) e PUT /qrcodes/{qrcodeId}. Repare que os campos utm_source … utm_content do próprio link, na resposta, descrevem a URL de destino, não a query recebida; as regras leem a query recebida.

O mesmo pelo MCP

Peça ao agente, conectado a https://mcp.codeqr.io/mcp:

No link cmswk759f0001j41i0vj1vmfq, mande cliques com utm_source newsletter para https://example.com/ofertas/assinantes e cliques vindos de instagram.com para https://example.com/ofertas/instagram.

update_link é chamada com:

{
  "linkId": "cmswk759f0001j41i0vj1vmfq",
  "rules": [
    { "attribute": "utm_source", "operator": "equals", "value": "newsletter",
      "url": "https://example.com/ofertas/assinantes" },
    { "attribute": "referrer", "operator": "equals", "value": "instagram.com",
      "url": "https://example.com/ofertas/instagram" }
  ]
}

O mesmo por automações

Nenhum módulo do Make, Zapier ou Pluga tem campo de regras; use o módulo Make an API Call do Make ou um passo HTTP com a requisição acima. Quando uma automação cria um link por campanha, coloque os valores de UTM tanto na regra (value) quanto na URL que você envia.

Como verificar

curl -sI "https://go.example.com/promo?utm_source=newsletter&utm_campaign=agosto" | grep -i location
# location: https://example.com/ofertas/assinantes?utm_source=newsletter&utm_campaign=agosto

curl -sI -H "Referer: https://www.instagram.com/" https://go.example.com/promo | grep -i location
# location: https://example.com/ofertas/instagram

curl -sI https://go.example.com/promo | grep -i location
# location: https://example.com/ofertas/

Em Análise para o link, o card URLs mostra cliques por destino, e o Relatório UTM detalha os cliques por origem, mídia e campanha.

Solução de problemas

A regra de UTM nunca dispara

O parâmetro está na URL de destino (acrescentado com o UTM Builder ou digitado em URL de destino), não no link curto em que as pessoas clicam. Acrescente-o ao link que você distribui: https://go.example.com/promo?utm_source=newsletter. Confira também o nome do parâmetro — utm_source, utm_medium, utm_campaign, utm_term, utm_content — e se ele tem valor: ?utm_source= sem nada depois não combina com nenhuma regra.

Newsletter e newsletter — maiúsculas importam?

Para a regra, não: os valores são comparados sem diferenciar maiúsculas, então utm_source=Newsletter combina com uma regra newsletter. Importa para o Google Analytics, que trata os dois como origens diferentes, e o parâmetro é repassado exatamente como chegou. Padronize os UTMs em minúsculas na origem.

A regra de Referenciador nunca dispara para Instagram, TikTok, WhatsApp ou QR Code

Aplicativos móveis e mensageiros geralmente não enviam referenciador, leituras de QR Code nunca enviam, e navegadores enviam só a origem (ou nada) em links de páginas HTTPS para HTTP ou marcados com noreferrer. Quando o referenciador falta, nenhuma regra de Referenciador combina, nem com é nem com não é. Roteie por UTM: dê a cada canal seu próprio link curto marcado.

A regra de Referenciador dispara para www.instagram.com mas não para l.instagram.com ou l.facebook.com

O valor é comparado ao hostname de origem retirando apenas o www. inicial. Facebook e Instagram às vezes passam os visitantes por l.facebook.com, lm.facebook.com ou l.instagram.com. Crie uma regra para cada hostname que aparecer no card Referenciadores da análise do link.

Digitei a URL completa como valor do referenciador

Use o domínio puro: instagram.com, não https://www.instagram.com/.

A API devolve 400 "A rule condition needs attribute, operator and value together"

Toda regra com attribute precisa também de operator e value. Os nomes de atributo são em minúsculas com sublinhado: utm_source, referrer.

Artigos relacionados