API atual/Guia rápido/Conteúdo e características do produto

SEO do produto

Lê, grava e gera o endereço (slug), o título, a descrição e as palavras-chave que os buscadores veem na página do produto.

SEO são os textos que ajudam o Google a encontrar a página do produto e decidem como ela aparece nos resultados: o slug (a parte final do endereço, como tenis-de-corrida-leve), o título da página, a descrição (os dois ou três textos curtos abaixo do título nos resultados) e as palavras-chave.

Três operações: ler os quatro campos, gravar os que você enviar (os outros ficam como estão) e gerar valores automáticos a partir do nome e da descrição do produto. Depois de gravar, a vitrine é atualizada e a página passa a mostrar os novos textos.

GET/api/v1/admin/products/{id}/seoAdmin

Consulta os campos de SEO de um produto

Exige o privilégio view_catalog ou manage_catalog.

Path parameters

iduuidobrigatório

Id do produto.

PUT/api/v1/admin/products/{id}/seoAdmin

Atualiza os campos de SEO de um produto

Exige o privilégio manage_catalog. Atualiza só os campos presentes no corpo. Texto vazio ("") limpa o campo. Corpo sem nenhum dos quatro campos é recusado com 400 (campos desconhecidos, como meta_title, são ignorados).

Ao mudar o slug o servidor normaliza o texto, confere se ninguém mais usa o endereço e cria dois redirecionamentos 301 do endereço antigo para o novo (/slug-antigo e /products/slug-antigo), para não quebrar links e posições no Google.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

slugstring

Novo endereço. Passa por normalização: minúsculas, sem acentos, espaços, _, . e / viram hífen, outros símbolos somem, hífens repetidos viram um. "Tênis de Corrida Leve" vira tenis-de-corrida-leve. Precisa ser único entre os produtos não excluídos e não pode ficar vazio depois de normalizado.

seo_titlestring

Título da página (a tag title). Recomendação de mercado: até 60 caracteres.

seo_descriptionstring

Meta descrição. Recomendação de mercado: até 155 caracteres.

meta_keywordsstring

Palavras-chave separadas por vírgula. Os buscadores atuais quase não usam este campo.

POST/api/v1/admin/products/{id}/seo/generateAdmin

Gera os campos de SEO a partir dos dados do produto

Exige o privilégio manage_catalog. Não recebe corpo. Calcula e grava três campos:

slug: o nome do produto normalizado (mesma regra do PUT);
seo_title: o nome do produto, cortado em cerca de 60 caracteres com ... no final;
seo_description: a descrição curta do produto (ou a descrição completa, se a curta estiver vazia), sem HTML, cortada em cerca de 155 caracteres com ....

Se a categoria principal do produto tiver um modelo de SEO configurado na loja, o título e a descrição saem desse modelo no lugar das regras acima. meta_keywords não é tocado.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

# Gravar
curl -X PUT "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/seo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seo_title": "Tênis de corrida leve | Loja",
    "seo_description": "Tênis leve para treino diário, com amortecimento.",
    "meta_keywords": "tênis, corrida, leve"
  }'

# Gerar a partir do produto
curl -X POST "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/seo/generate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200SEO do produto (GET, PUT e generate)

json

{
  "slug": "zz-conteudo-teste-tenis",
  "seo_title": "Tênis de corrida leve | Loja",
  "seo_description": "Tênis leve para treino diário, com amortecimento.",
  "meta_keywords": "tênis, corrida, leve"
}

Response fields

slugstring

Endereço atual do produto.

seo_titlestring

Título da página. Vazio ("") quando nunca foi preenchido.

seo_descriptionstring

Meta descrição. Vazio quando nunca foi preenchida.

meta_keywordsstring

Palavras-chave. Vazio quando nunca foram preenchidas.

Erros

Status	Quando	Corpo
400	Corpo do `PUT` não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`PUT` sem nenhum dos quatro campos	`{"error":"no SEO fields to update","detail":"no SEO fields to update"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_catalog` para gravar e gerar)	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Produto não existe ou foi excluído	`{"error":"product not found"}`
500	Slug já usado por outro produto	`{"error":"failed to update product SEO","detail":"slug \"zz-doc-teste-caneca\" is already used by another product"}`
500	Slug vazio depois de normalizado (ex.: `"!!!"`)	`{"error":"failed to update product SEO","detail":"slug cannot be empty"}`
500	`{id}` fora do formato UUID	`{"error":"failed to get product SEO","detail":"..."}`

Veja também

SEO do produto

Lê, grava e gera o endereço (slug), o título, a descrição e as palavras-chave que os buscadores veem na página do produto.

GET/api/v1/admin/products/{id}/seoAdmin

Consulta os campos de SEO de um produto

Exige o privilégio view_catalog ou manage_catalog.

Path parameters

iduuidobrigatório

Id do produto.

PUT/api/v1/admin/products/{id}/seoAdmin

Atualiza os campos de SEO de um produto

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

slugstring

seo_titlestring

Título da página (a tag title). Recomendação de mercado: até 60 caracteres.

seo_descriptionstring

Meta descrição. Recomendação de mercado: até 155 caracteres.

meta_keywordsstring

Palavras-chave separadas por vírgula. Os buscadores atuais quase não usam este campo.

POST/api/v1/admin/products/{id}/seo/generateAdmin

Gera os campos de SEO a partir dos dados do produto

Exige o privilégio manage_catalog. Não recebe corpo. Calcula e grava três campos:

slug: o nome do produto normalizado (mesma regra do PUT);
seo_title: o nome do produto, cortado em cerca de 60 caracteres com ... no final;
seo_description: a descrição curta do produto (ou a descrição completa, se a curta estiver vazia), sem HTML, cortada em cerca de 155 caracteres com ....

Se a categoria principal do produto tiver um modelo de SEO configurado na loja, o título e a descrição saem desse modelo no lugar das regras acima. meta_keywords não é tocado.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

# Gravar
curl -X PUT "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/seo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seo_title": "Tênis de corrida leve | Loja",
    "seo_description": "Tênis leve para treino diário, com amortecimento.",
    "meta_keywords": "tênis, corrida, leve"
  }'

# Gerar a partir do produto
curl -X POST "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/seo/generate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200SEO do produto (GET, PUT e generate)

json

{
  "slug": "zz-conteudo-teste-tenis",
  "seo_title": "Tênis de corrida leve | Loja",
  "seo_description": "Tênis leve para treino diário, com amortecimento.",
  "meta_keywords": "tênis, corrida, leve"
}

Response fields

slugstring

Endereço atual do produto.

seo_titlestring

Título da página. Vazio ("") quando nunca foi preenchido.

seo_descriptionstring

Meta descrição. Vazio quando nunca foi preenchida.

meta_keywordsstring

Palavras-chave. Vazio quando nunca foram preenchidas.

Erros

Status	Quando	Corpo
400	Corpo do `PUT` não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`PUT` sem nenhum dos quatro campos	`{"error":"no SEO fields to update","detail":"no SEO fields to update"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_catalog` para gravar e gerar)	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Produto não existe ou foi excluído	`{"error":"product not found"}`
500	Slug já usado por outro produto	`{"error":"failed to update product SEO","detail":"slug \"zz-doc-teste-caneca\" is already used by another product"}`
500	Slug vazio depois de normalizado (ex.: `"!!!"`)	`{"error":"failed to update product SEO","detail":"slug cannot be empty"}`
500	`{id}` fora do formato UUID	`{"error":"failed to get product SEO","detail":"..."}`