Redirecionamentos e slugs

Quando uma URL muda (um produto é renomeado, a loja migra de plataforma, uma categoria é reorganizada), os links antigos que estão em buscadores, e-mails e favoritos precisam continuar funcionando. Um redirecionamento diz à vitrine: "quem pedir /caminho-antigo vai para /caminho-novo". Esta seção documenta o cadastro desses redirecionamentos, a importação em lote e o ajuste do slug (o trecho legível da URL) por idioma. As rotas de redirecionamento exigem token de administrador e o módulo SEO ativo na loja; a de slug por idioma exige o privilégio manage_categories.

Como funciona

1. Cadastre o redirecionamento
   POST /api/v1/admin/seo/redirects com old_path e new_path.
2. A vitrine aplica
   Ao resolver um caminho, a vitrine procura um redirecionamento ativo para aquele texto exato e responde 301 ou 302 com o destino.
3. Acompanhe o uso
   Na listagem, hits e last_hit_at mostram se o redirecionamento ainda é usado e podem orientar uma limpeza.

Conceitos-chave

Formato dos caminhos

Cadeias e ciclos

Ao gravar, a plataforma segue os redirecionamentos ativos a partir do new_path. Se chegar de volta ao old_path, ou repetir um destino, recusa com REDIRECT_LOOP. Se passar de 5 saltos, recusa com REDIRECT_CHAIN_TOO_DEEP. Se terminar em um destino final, grava esse destino. Ao gravar, também reaponta os redirecionamentos que já apontavam para o old_path, para pularem o salto.

Slug por idioma

Em lojas com vários idiomas, cada produto, categoria, página, post de blog e marca pode ter um slug diferente por idioma. A rota de slug por idioma valida o novo texto e guarda o anterior para redirecionar.

Endpoints

Erros comuns

• old_path sem a barra inicial. Retorna 400 old_path must start with /.
• new_path sem /, http:// ou https://. Retorna 400.
• Redirecionar um caminho para ele mesmo. Retorna 400 old_path and new_path cannot be identical.
• Criar um ciclo (/a para /b e /b para /a). Retorna 400 com REDIRECT_LOOP.
• Achar que o POST falha quando o old_path já existe. Ele atualiza o existente e devolve 201.
• Esperar 404 ao consultar um id que não é UUID. Retorna 500.
• Importar CSV grande e ter um erro no meio. A importação em lote é transacional: uma linha inválida cancela o lote inteiro.

Próximos passos