Redirecione visitantes por país, região, cidade ou idioma

Ao final deste guia, um único link curto ou QR Code funciona como geo redirect: envia visitantes de Portugal à sua página em português europeu, navegadores em espanhol à página em espanhol e todos os demais à página padrão — e a mesma abordagem serve para estados, cidades e continentes.

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

As URLs localizadas, uma por público (por exemplo https://example.com/pt-pt/, https://example.com/es/).
Uma página padrão para quem não combina com nenhuma regra; ela vai na URL de destino do link.
Decida o que "público" significa em cada regra:
País, Região (estado), Cidade, Continente vêm do endereço IP do visitante. País é confiável; região e cidade são aproximados (veja Solução de problemas).
Idioma vem do idioma preferido do navegador, não da localização. Dez idiomas estão disponíveis: Português, English, Español, Français, Deutsch, 中文, Русский, Italiano, 日本語, 한국어.
Para Região (estado), tenha o código ISO 3166-2 à mão (SP para São Paulo, RJ para Rio de Janeiro, CA para Califórnia) — o código, não o nome.

Passos

Abra Links e clique em Adicionar Link, ou abra um link existente e escolha Editar.
Informe a página padrão em URL de destino, por exemplo https://example.com/.
Ative Regras inteligentes.
Na primeira regra, selecione País, mantenha é e escolha Portugal na lista.
Na URL de destino dessa regra, informe https://example.com/pt-pt/.
Clique em Adicionar regra. Selecione Idioma, mantenha é, escolha Español e informe https://example.com/es/.
Acrescente outras regras do mesmo jeito — para um estado escolha Região (estado) e digite o código (SP); para uma cidade escolha Cidade e digite o nome (São Paulo); para um continente escolha Continente e selecione-o na lista.
Ordene as regras da mais específica para a menos específica. As regras rodam de cima para baixo e a primeira que combina vence, então coloque Cidade é São Paulo acima de País é Brasil, e decida se uma regra de país ou de idioma deve vencer quando as duas puderem combinar.
Clique em Criar link (ou Salvar link).

Duas Regras inteligentes: País é Brasil apontando para https://example.com/pt-br/ e Idioma é Español apontando para https://example.com/es/

Para mandar todo mundo exceto um público para outro lugar, use não é: País não é Brasil → https://example.com/international/.

Para um QR Code, faça o mesmo na seção Regras inteligentes do editor de um QR Code dinâmico do tipo URL.

O mesmo pela API

Acrescente ou substitua as regras de um link existente com PUT https://api.codeqr.io/links/{linkId} (o mesmo array rules funciona em POST /links, POST /qrcodes e PUT /qrcodes/{qrcodeId}). Códigos de país são ISO 3166-1 alfa-2 (duas letras), códigos de região são ISO 3166-2 sem o prefixo do país, códigos de continente são AF AN AS EU NA OC SA, idiomas têm duas letras (pt, es, …).

Requisição:

curl -X PUT https://api.codeqr.io/links/cmswk759f0001j41i0vj1vmfq \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "attribute": "city",     "operator": "equals", "value": "São Paulo", "url": "https://example.com/pt-br/sao-paulo/" },
      { "attribute": "country",  "operator": "equals", "value": "PT",        "url": "https://example.com/pt-pt/" },
      { "attribute": "language", "operator": "equals", "value": "es",        "url": "https://example.com/es/" }
    ]
  }'

Resposta (200 OK):

{
  "id": "cmswk759f0001j41i0vj1vmfq",
  "domain": "go.example.com",
  "key": "cardapio-de-verao",
  "url": "https://example.com/",
  "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/pt-br/sao-paulo/", "value": "São Paulo", "operator": "equals", "attribute": "city" },
    { "url": "https://example.com/pt-pt/",           "value": "PT",        "operator": "equals", "attribute": "country" },
    { "url": "https://example.com/es/",              "value": "es",        "operator": "equals", "attribute": "language" }
  ],
  "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-17T01:32:59.384Z",
  "tagId": null,
  "comments": null,
  "notificationToken": null,
  "useAsTemplate": false,
  "tags": [],
  "shortLink": "https://go.example.com/cardapio-de-verao",
  "webhookIds": [],
  "qrCode": "https://api.codeqr.io/qr?url=https://go.example.com/cardapio-de-verao?qr=1"
}

Enviar rules substitui a lista inteira; envie todas as regras que quer manter. Para remover todas, envie "rules": null.

O mesmo pelo MCP

Com o cliente de IA conectado a https://mcp.codeqr.io/mcp, peça:

Atualize o link cmswk759f0001j41i0vj1vmfq: visitantes de Portugal (país PT) vão para https://example.com/pt-pt/, navegadores em espanhol (idioma es) vão para https://example.com/es/, os demais continuam no padrão.

O agente chama update_link:

{
  "linkId": "cmswk759f0001j41i0vj1vmfq",
  "rules": [
    { "attribute": "country",  "operator": "equals", "value": "PT", "url": "https://example.com/pt-pt/" },
    { "attribute": "language", "operator": "equals", "value": "es", "url": "https://example.com/es/" }
  ]
}

A descrição da tool traz os formatos aceitos (país com duas letras, código de região sem prefixo, nome da cidade, continente e idioma com duas letras), então um agente bem-comportado não envia Portugal nem BR-SP. create_qrcode e update_qrcode não aceitam rules pelo MCP.

O mesmo por automações

Os módulos do Make, Zapier e Pluga não têm campo de regras. Use o módulo Make an API Call da CodeQR no Make (PUT, /links/{linkId}, corpo como acima) ou um passo HTTP no Zapier ou na Pluga. Os webhooks link.created e link.updated incluem rules.

Como verificar

Idioma é o mais fácil de testar de qualquer lugar. Mude o idioma preferido do navegador e abra o link, ou no terminal:

` curl -sI -H "Accept-Language: es-ES,es;q=0.9,en;q=0.8" https://go.example.com/cardapio-de-verao | grep -i location # location: https://example.com/es/

curl -sI -H "Accept-Language: pt-BR,pt;q=0.9" https://go.example.com/cardapio-de-verao | grep -i location # location: https://example.com/ `

País, região, cidade e continente vêm do endereço IP, então teste de um aparelho que esteja no lugar — um colega, um cliente, um celular na rede móvel local. Uma saída de VPN no país-alvo costuma disparar a regra, mas faixas de IP de VPN e de data center às vezes estão registradas em outro lugar; um teste de VPN que falha não prova que a regra está errada.
Depois de alguns cliques, abra Análise para o link: o card URLs mostra os cliques por destino, e os cards Países, Cidades e Continentes mostram onde a CodeQR posicionou os visitantes.

Solução de problemas

Um visitante de Portugal recebeu a página padrão

A CodeQR lê o país a partir do endereço IP do visitante. Proxies corporativos, VPNs, operadoras de celular e relays de privacidade fazem o tráfego sair por endereços registrados em outro país ou região, então aquele visitante pareceu estar em outro lugar. A detecção de país acerta para a grande maioria dos visitantes; quando erra, o visitante recebe a URL de destino ou a página de outra regra, nunca um erro. Mantenha a página padrão utilizável para qualquer pessoa.

A regra de Cidade quase nunca dispara

Geolocalização por IP no nível de cidade é aproximada: as bases de IP publicam precisão bem abaixo da de país, e operadoras de celular atribuem um mesmo endereço a aparelhos espalhados por uma grande área. Prefira País ou Região (estado) para o que importa; use Cidade só onde uma falha ocasional não incomoda.

A regra de Região nunca dispara

O valor precisa ser o código ISO 3166-2 sem o prefixo do país: SP, RJ, CA. São Paulo, BR-SP e US-CA nunca combinam. Se a região do visitante for desconhecida, nenhuma regra de região combina e o visitante segue para a próxima regra.

Um visitante no Brasil com o navegador em inglês recebeu a página em inglês

Idioma lê o idioma preferido do navegador, não a localização. Um visitante no Brasil cujo navegador prefere inglês combina com Idioma é English. Se a localização importa mais que o idioma, coloque a regra de País acima da regra de Idioma.

O idioma do visitante não está na lista

Dez idiomas são suportados. Um navegador que prefere qualquer outro idioma não combina com nenhuma regra de Idioma — nem com é nem com não é — e continua descendo a lista até a URL de destino. Variantes regionais mapeiam para o idioma base: pt-BR e pt-PT combinam com Português, es-MX combina com Español.

Os buscadores indexam o idioma errado

Os robôs de busca costumam chegar de endereços dos EUA sem preferência de idioma e são roteados como qualquer visitante. Regras inteligentes servem para links curtos e QR Codes; para páginas indexáveis do seu próprio site, mantenha URLs separadas por idioma com hreflang e deixe o visitante escolher.

A API devolve 400 "invalid_enum_value" para o atributo ou "A rule condition needs attribute, operator and value together"

Os nomes de atributo são em minúsculas (country, region, city, continent, language), os operadores são equals ou not_equals, e toda regra com condição precisa dos três campos. Lista completa: Referência das Regras inteligentes.