redirection_url: especificação do redirecionamento transparente

Esta é a especificação pública do comportamento do endpoint /r/{slug} quando recebe o parâmetro redirection_url. Ela existe para que anunciantes, auditores e plataformas de anúncios possam verificar que o Affilitrack redireciona para onde a URL declara, sem saltos intermediários e sem alterar o destino além do estritamente necessário.

Parâmetro

• Nome: redirection_url — exato, minúsculo, sensível a maiúsculas. REDIRECTION_URL ou Redirection_Url não são lidos.
• Valor: uma URL absoluta, normalmente codificada para URL (o que o Google faz com {lpurl}). Codificado ou não, o valor é decodificado uma vez.
• Onde: query string de GET /r/{slug} e de GET /r/{slug}/{subid}.

Sem o parâmetro

Comportamento legado: o destino é a URL de destino da oferta, com as macros expandidas e o parâmetro do click acrescentado. É o que campanhas de Meta, TikTok, Kwai e fontes personalizadas usam.

Com o parâmetro: validação

O valor é aceito se, e somente se, todas as condições valem:

1. URL absoluta com esquema http ou https e host presente. Relativas (/pagina), protocolo-relativas (//host), javascript:, data:, file:, ftp: são recusadas.
2. Esquema https; http só é aceito se a URL da oferta também for http.
3. Host permitido: igual ao host da URL de destino da oferta, ou um subdomínio dele. www. é equivalente ao apex nos dois sentidos (oferta www.loja.com.br aceita loja.com.br, e vice-versa). Sufixos parecidos (naoloja.com.br, loja.com.br.evil.com) são recusados.
4. Porta: igual à da oferta (ou ausente nas duas).
5. Sem userinfo: https://loja.com.br@evil.com/ é recusado.
6. Sem caracteres de controle, espaço, barra invertida, CR/LF.
7. Tamanho: até 2 048 caracteres.
8. Host normalizado por IDNA: homógrafos Unicode (а cirílico por a latino) não passam por igual.
9. A oferta precisa ter uma URL válida para servir de base; sem ela, nenhum destino declarado é obedecido.

Com o parâmetro: comportamento

Se válido:

• O destino é a URL declarada, literal. Nenhuma macro {…} é expandida dentro dela. Nenhum parâmetro seu é removido ou reescrito. Os parâmetros que vieram no {lpurl} (UTMs do sufixo de URL final, por exemplo) chegam intactos.
• O único acréscimo é o parâmetro do click da oferta (clickid=<click_id>, nome configurável), a menos que ele já esteja presente no valor.
• Resposta 302 Found com Location e Cache-Control: no-store. Um único salto; sem página intermediária; sem Set-Cookie.
• O clique é gravado com redirect_status = declared.

Se inválido:

• Resposta 400 Bad Request, corpo JSON {"detail": "redirection_url inválido para esta campanha", "reason": "<motivo>", "click_id": "<id>"}, sem cabeçalho Location. O visitante não é redirecionado a lugar nenhum.
• O clique é gravado com redirect_status = refused e redirect_reason = <motivo>, para auditoria. Motivos possíveis: vazio, longa demais, caractere proibido, não absoluta http(s), oferta sem url válida, esquema http não permitido, host fora da oferta, porta não permitida.

Ordem das operações no clique

1. Localiza a campanha e a oferta.
2. Gera o click_id; lê ref_id e o mapa de parâmetros; detecta bot.
3. Resolve o destino (declarado ou legado) antes de gravar, para que a recusa fique no registro.
4. Grava o clique.
5. Responde 302 (ou 400).

Exemplo

Oferta com URL https://clinica.com.br/agendar, click_param = clickid. Requisição:

GET /r/30c2jVaU?redirection_url=https%3A%2F%2Fclinica.com.br%2Fagendar%3Futm_source%3Dgoogle&gclid=Cj0K…&campaignid=111

Resposta:

HTTP/1.1 302 Found
Location: https://clinica.com.br/agendar?utm_source=google&clickid=034U7aNU58sxhCH1BD7gom
Cache-Control: no-store

Requisição com host externo:

GET /r/30c2jVaU?redirection_url=https%3A%2F%2Fexample.com%2F

Resposta:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"detail":"redirection_url inválido para esta campanha","reason":"host fora da oferta","click_id":"034U7ar2esrQR3reoSXp5a"}

Domínios de anunciante (CNAME)

O mesmo comportamento vale em domínios de tracking próprios (track.seusite.com.br/r/…). O host de tracking não interfere na validação: o que importa é o host da oferta versus o do destino declarado.

Métodos

GET apenas. HEAD responde 405. Para inspecionar cabeçalhos em linha de comando: curl -sS -D- -o /dev/null 'URL'.

OpenAPI

As duas rotas declaram redirection_url como parâmetro de query opcional e as respostas 302 e 400 em https://app.affilitrack.com.br/api/openapi.json.