API atual/Referência completa/SEO, testes A/B e envio de arquivos

Resolver URLs amigáveis

Descobre qual produto, categoria, página, seller, marca ou post de blog corresponde a um endereço da loja, em duas formas, a antiga com redirecionamento e a canônica.

Em uma vitrine headless o visitante abre /camisetas ou /moda/roupas/camisetas/camisa-x/p e o seu front-end precisa saber o que desenhar. Estas duas rotas respondem exatamente isso, a partir do endereço. Ambas são públicas, sem login, e não têm cache.

Resolver canônico

GET/api/v1/storefront/seo/canonical-resolvePública

Resolve um caminho canônico da vitrine para a entidade correspondente

Trata o endereço amigável como a URL oficial e devolve a entidade que ele representa, para você renderizar a página no próprio endereço, sem redirecionar. Tenta, em ordem de prioridade, seller, categoria, produto, post de blog, página e marca. Se o caminho pedido não é exatamente o oficial da entidade (por exemplo, o produto tem o caminho por categoria e você pediu o slug curto), a resposta inclui redirect_to para você redirecionar o visitante (301).

Quando a loja tem mais de um idioma, um prefixo de idioma no começo do caminho (/es/...) é reconhecido e removido antes da busca, e os slugs traduzidos passam a valer. Um slug de outro idioma devolve redirect_to para o slug certo.

A página de privacidade existe em toda loja: o slug dela resolve como page mesmo sem registro.

Parâmetros de consulta

pathstringobrigatório

Caminho da URL, com ou sem barra inicial e final. Pode ter vários segmentos (moda/roupas/camisetas/camisa-x/p). Deve vir codificado como parâmetro de consulta.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/seo/canonical-resolve" \
  --data-urlencode "path=/camisa-flamengo-masculina-i-26-adidas"

Resposta

200Atalho com redirecionamento

json

{
  "kind": "product",
  "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
  "slug": "camisa-flamengo-masculina-i-26-adidas",
  "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"],
  "redirect_to": "/moda/roupas/camisetas/camisa-flamengo-masculina-i-26-adidas/p"
}

200Caminho já canônico

json

{
  "kind": "product",
  "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
  "slug": "camisa-flamengo-masculina-i-26-adidas",
  "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"]
}

Campos da resposta

kindstring

vendorcategoryproductbrandblogpage

Tipo da entidade encontrada.

iduuid

Id da entidade, para buscar os dados na API certa. Pode faltar na página de privacidade padrão.

slugstring

Slug que casou: o último segmento do caminho.

canonical_patharray

Segmentos do caminho oficial. Use para o link rel="canonical", o mapa do site e os links internos.

module_requiredstring

Quando o caminho canônico só vale com um módulo ligado (hoje seo-category-paths, para produtos com caminho por categoria). Vazio nos demais.

redirect_tostring

Presente quando o caminho pedido difere do oficial. Redirecione o visitante para ele.

Erros

Status	Quando	Corpo
400	Sem `path`	`{"error":"missing path parameter"}`
404	Nada corresponde	`{"error":"no matching entity found","detail":"nao-existe"}`
409	O primeiro segmento é de uma rota da própria vitrine (`products`, `admin`...)	`{"error":"first segment is a reserved storefront path","detail":"admin"}`
500	Falha ao resolver	`{"error":"failed to resolve URL","detail":"..."}`

Resolver (formato antigo)

GET/api/v1/storefront/seo/resolvePública

Resolve uma URL para uma entidade e um redirecionamento legado

Forma antiga, usada pelo redirecionamento de endereços de lojas migradas. Procura, em ordem: (1) a tabela de redirecionamentos do lojista (URLs antigas e mudanças de slug), depois produtos, categorias, páginas, sellers e posts por slug e devolve para onde ir, em formato de caminho clássico (/products/slug, /c/slug, /pages/slug, /vendors/slug, /blog/slug). Para um caminho de vários segmentos, só o último vale como slug da entidade (o caminho inteiro é usado para procurar redirecionamentos).

Se a URL pedida é hoje o endereço vivo de uma entidade, a entidade vence um redirecionamento antigo que apontaria para longe dela. Redirecionamentos encadeados são seguidos com proteção contra ciclos.

Parâmetros de consulta

pathstringobrigatório

Caminho da URL (/camisetas). Só o último segmento identifica a entidade.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/seo/resolve" --data-urlencode "path=/camisetas"

Resposta

200Entidade encontrada

json

{
  "type": "category",
  "slug": "camisetas",
  "redirect_url": "/c/camisetas",
  "status_code": 302
}

Campos da resposta

typestring

productcategorypagevendorblogredirect

Tipo da entidade, ou redirect quando veio da tabela de redirecionamentos.

slugstring

Slug que casou.

redirect_urlstring

Para onde ir, em formato de caminho clássico (/c/camisetas).

status_codeinteger

301302

301 para redirecionamento cadastrado pelo lojista; 302 para casamento direto com uma entidade.

Erros

Status	Quando	Corpo
400	Sem `path`	`{"error":"missing path parameter"}`
404	Nada corresponde	`{"error":"no matching entity found"}`
500	Falha ao resolver	`{"error":"failed to resolve URL","detail":"..."}`

Veja também

API atual/Referência completa/SEO, testes A/B e envio de arquivos

Resolver URLs amigáveis

Descobre qual produto, categoria, página, seller, marca ou post de blog corresponde a um endereço da loja, em duas formas, a antiga com redirecionamento e a canônica.

Resolver canônico

GET/api/v1/storefront/seo/canonical-resolvePública

Resolve um caminho canônico da vitrine para a entidade correspondente

A página de privacidade existe em toda loja: o slug dela resolve como page mesmo sem registro.

Parâmetros de consulta

pathstringobrigatório

Caminho da URL, com ou sem barra inicial e final. Pode ter vários segmentos (moda/roupas/camisetas/camisa-x/p). Deve vir codificado como parâmetro de consulta.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/seo/canonical-resolve" \
  --data-urlencode "path=/camisa-flamengo-masculina-i-26-adidas"

Resposta

200Atalho com redirecionamento

json

{
  "kind": "product",
  "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
  "slug": "camisa-flamengo-masculina-i-26-adidas",
  "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"],
  "redirect_to": "/moda/roupas/camisetas/camisa-flamengo-masculina-i-26-adidas/p"
}

200Caminho já canônico

json

{
  "kind": "product",
  "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
  "slug": "camisa-flamengo-masculina-i-26-adidas",
  "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"]
}

Campos da resposta

kindstring

vendorcategoryproductbrandblogpage

Tipo da entidade encontrada.

iduuid

Id da entidade, para buscar os dados na API certa. Pode faltar na página de privacidade padrão.

slugstring

Slug que casou: o último segmento do caminho.

canonical_patharray

Segmentos do caminho oficial. Use para o link rel="canonical", o mapa do site e os links internos.

module_requiredstring

Quando o caminho canônico só vale com um módulo ligado (hoje seo-category-paths, para produtos com caminho por categoria). Vazio nos demais.

redirect_tostring

Presente quando o caminho pedido difere do oficial. Redirecione o visitante para ele.

Erros

Status	Quando	Corpo
400	Sem `path`	`{"error":"missing path parameter"}`
404	Nada corresponde	`{"error":"no matching entity found","detail":"nao-existe"}`
409	O primeiro segmento é de uma rota da própria vitrine (`products`, `admin`...)	`{"error":"first segment is a reserved storefront path","detail":"admin"}`
500	Falha ao resolver	`{"error":"failed to resolve URL","detail":"..."}`

Resolver (formato antigo)

GET/api/v1/storefront/seo/resolvePública

Resolve uma URL para uma entidade e um redirecionamento legado

Parâmetros de consulta

pathstringobrigatório

Caminho da URL (/camisetas). Só o último segmento identifica a entidade.

Exemplo de requisição

bash

curl -G "$BASE_URL/api/v1/storefront/seo/resolve" --data-urlencode "path=/camisetas"

Resposta

200Entidade encontrada

json

{
  "type": "category",
  "slug": "camisetas",
  "redirect_url": "/c/camisetas",
  "status_code": 302
}

Campos da resposta

typestring

productcategorypagevendorblogredirect

Tipo da entidade, ou redirect quando veio da tabela de redirecionamentos.

slugstring

Slug que casou.

redirect_urlstring

Para onde ir, em formato de caminho clássico (/c/camisetas).

status_codeinteger

301302

301 para redirecionamento cadastrado pelo lojista; 302 para casamento direto com uma entidade.

Erros

Status	Quando	Corpo
400	Sem `path`	`{"error":"missing path parameter"}`
404	Nada corresponde	`{"error":"no matching entity found"}`
500	Falha ao resolver	`{"error":"failed to resolve URL","detail":"..."}`