SEO da categoria

Lê e grava o slug, o título e a descrição de SEO de uma categoria, gera os valores a partir do nome e define o modelo de texto que alimenta o SEO dos produtos.

O SEO de uma categoria é o que os buscadores e as redes sociais mostram da página dela: o endereço (slug), o título da aba e a descrição (meta description). Esta página reúne as cinco rotas que cuidam disso:

ler e gravar o SEO da própria categoria;
gerar um SEO padrão a partir do nome e da descrição;
ler e gravar o modelo de texto (frase de chamada e parágrafo publicitário) que a categoria usa para montar automaticamente o título e a descrição dos produtos dela.

Os mesmos campos (slug, seo_title, seo_description, meta_keywords) também podem ser enviados em Criar categoria e Alterar categoria.

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

Consulta o SEO de uma categoria

Autenticação: Authorization: Bearer <token> com o privilégio view_catalog, manage_catalog ou manage_categories. Não devolve categorias da lixeira.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

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

Grava o SEO de uma categoria

Autenticação: Authorization: Bearer <token> com o privilégio manage_categories. Só os campos enviados mudam.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

slugstring

Novo endereço da página. É normalizado (minúsculas, sem acentos, espaços viram hífen: Mesas Escritório vira mesas-escritorio). Precisa ser único entre as categorias e não pode ficar vazio.

seo_titlestring

Título de SEO. Texto livre.

seo_descriptionstring

Descrição de SEO. Texto livre.

meta_keywordsstring

Aceito, mas ignorado (veja o aviso acima).

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

Gera o SEO a partir do nome da categoria

Calcula e grava um SEO padrão. Não tem corpo. A regra é fixa e determinística (não depende de nenhum serviço externo):

slug: o nome da categoria normalizado e, se já existir, com sufixo numérico. Substitui o slug atual.
seo_title: o próprio nome, cortado em 60 caracteres (os últimos viram ...).
seo_description: a descrição da categoria sem HTML, cortada em 155 caracteres (os últimos viram ...). Fica vazia se a categoria não tem descrição.

Autenticação: privilégio manage_categories.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

GET/api/v1/admin/categories/{id}/seo-templateAdmin

Consulta o modelo de SEO de produto de uma categoria

O modelo de texto da categoria, uma entrada por idioma. A frase de chamada e o parágrafo publicitário alimentam o título e a descrição de SEO dos produtos da categoria (o título gerado é cortado em 48 caracteres e a descrição em 146). Autenticação: view_catalog, manage_catalog ou manage_categories.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

PUT/api/v1/admin/categories/{id}/seo-templateAdmin

Grava o modelo de SEO de produto de uma categoria

Grava a frase de chamada e o parágrafo de um idioma. Enviar as duas frases vazias desliga o modelo para aquele idioma. Autenticação: privilégio manage_categories.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

lang_codestring

Idioma (pt-BR, en...). Sem ele, vale o idioma padrão da loja. A categoria precisa já ter texto cadastrado nesse idioma.

call_to_actionstring

Frase de chamada, até 255 caracteres.

advertising_paragraphstring

Parágrafo publicitário, até 255 caracteres.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/seo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"mesas-escritorio","seo_title":"Mesas de escritório","seo_description":"As melhores mesas para o seu escritório."}'

Resposta

200SEO lido, gravado ou gerado

json

{
  "slug": "mesas-escritorio",
  "seo_title": "Mesas de escritório",
  "seo_description": "As melhores mesas para o seu escritório.",
  "meta_keywords": ""
}

200Modelo de SEO dos produtos

json

{
  "saved": true,
  "templates": [
    { "lang_code": "es", "call_to_action": "", "advertising_paragraph": "" },
    { "lang_code": "pt-BR", "call_to_action": "Compre online", "advertising_paragraph": "Frete rápido para todo o Brasil." }
  ]
}

Campos da resposta

slugstring

Endereço da página.

seo_titlestring

Título de SEO. Vazio quando não definido.

seo_descriptionstring

Descrição de SEO. Vazia quando não definida.

meta_keywordsstring

Sempre vazio nestas rotas, mesmo quando a categoria tem palavras-chave.

savedboolean

Só no PUT /seo-template: true quando gravou.

templatesarray

Uma entrada por idioma da categoria, com lang_code, call_to_action e advertising_paragraph. No GET /seo-template este é o único campo ({"templates": [...]}). Vem vazio quando a loja ainda não tem esse recurso.

Erros

Status	Quando	Corpo
400	`PUT /seo` sem nenhum campo gravável (corpo vazio, ou só `meta_keywords`)	`{"error":"no SEO fields to update","detail":"no SEO fields to update"}`
400	Corpo inválido, ou `call_to_action`/`advertising_paragraph` com mais de 255 caracteres	`{"error":"call_to_action and advertising_paragraph are limited to 255 characters"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem privilégio	`{"error":"insufficient privileges","required":"manage_categories"}`
404	Categoria não existe ou está na lixeira (`/seo` e `/seo/generate`)	`{"error":"category not found"}`
409	`slug` já usado por outra categoria	`{"error":"slug already in use","detail":"slug \"mesas\" is already used by another category"}`
409	`PUT /seo-template` em uma loja que ainda não tem o recurso	`{"error":"category SEO template columns are not present on this store yet (migration 1001022)","detail":"..."}`
500	`id` que não é UUID, ou `lang_code` sem texto cadastrado na categoria	`{"error":"failed to get category SEO","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Mensagens de detail que o servidor escreve em português seguem em português na resposta real.

Veja também

SEO da categoria

Lê e grava o slug, o título e a descrição de SEO de uma categoria, gera os valores a partir do nome e define o modelo de texto que alimenta o SEO dos produtos.

ler e gravar o SEO da própria categoria;
gerar um SEO padrão a partir do nome e da descrição;
ler e gravar o modelo de texto (frase de chamada e parágrafo publicitário) que a categoria usa para montar automaticamente o título e a descrição dos produtos dela.

Os mesmos campos (slug, seo_title, seo_description, meta_keywords) também podem ser enviados em Criar categoria e Alterar categoria.

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

Consulta o SEO de uma categoria

Autenticação: Authorization: Bearer <token> com o privilégio view_catalog, manage_catalog ou manage_categories. Não devolve categorias da lixeira.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

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

Grava o SEO de uma categoria

Autenticação: Authorization: Bearer <token> com o privilégio manage_categories. Só os campos enviados mudam.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

slugstring

seo_titlestring

Título de SEO. Texto livre.

seo_descriptionstring

Descrição de SEO. Texto livre.

meta_keywordsstring

Aceito, mas ignorado (veja o aviso acima).

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

Gera o SEO a partir do nome da categoria

Calcula e grava um SEO padrão. Não tem corpo. A regra é fixa e determinística (não depende de nenhum serviço externo):

slug: o nome da categoria normalizado e, se já existir, com sufixo numérico. Substitui o slug atual.
seo_title: o próprio nome, cortado em 60 caracteres (os últimos viram ...).
seo_description: a descrição da categoria sem HTML, cortada em 155 caracteres (os últimos viram ...). Fica vazia se a categoria não tem descrição.

Autenticação: privilégio manage_categories.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

GET/api/v1/admin/categories/{id}/seo-templateAdmin

Consulta o modelo de SEO de produto de uma categoria

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

PUT/api/v1/admin/categories/{id}/seo-templateAdmin

Grava o modelo de SEO de produto de uma categoria

Grava a frase de chamada e o parágrafo de um idioma. Enviar as duas frases vazias desliga o modelo para aquele idioma. Autenticação: privilégio manage_categories.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

lang_codestring

Idioma (pt-BR, en...). Sem ele, vale o idioma padrão da loja. A categoria precisa já ter texto cadastrado nesse idioma.

call_to_actionstring

Frase de chamada, até 255 caracteres.

advertising_paragraphstring

Parágrafo publicitário, até 255 caracteres.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/seo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"mesas-escritorio","seo_title":"Mesas de escritório","seo_description":"As melhores mesas para o seu escritório."}'

Resposta

200SEO lido, gravado ou gerado

json

{
  "slug": "mesas-escritorio",
  "seo_title": "Mesas de escritório",
  "seo_description": "As melhores mesas para o seu escritório.",
  "meta_keywords": ""
}

200Modelo de SEO dos produtos

json

{
  "saved": true,
  "templates": [
    { "lang_code": "es", "call_to_action": "", "advertising_paragraph": "" },
    { "lang_code": "pt-BR", "call_to_action": "Compre online", "advertising_paragraph": "Frete rápido para todo o Brasil." }
  ]
}

Campos da resposta

slugstring

Endereço da página.

seo_titlestring

Título de SEO. Vazio quando não definido.

seo_descriptionstring

Descrição de SEO. Vazia quando não definida.

meta_keywordsstring

Sempre vazio nestas rotas, mesmo quando a categoria tem palavras-chave.

savedboolean

Só no PUT /seo-template: true quando gravou.

templatesarray

Erros

Status	Quando	Corpo
400	`PUT /seo` sem nenhum campo gravável (corpo vazio, ou só `meta_keywords`)	`{"error":"no SEO fields to update","detail":"no SEO fields to update"}`
400	Corpo inválido, ou `call_to_action`/`advertising_paragraph` com mais de 255 caracteres	`{"error":"call_to_action and advertising_paragraph are limited to 255 characters"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem privilégio	`{"error":"insufficient privileges","required":"manage_categories"}`
404	Categoria não existe ou está na lixeira (`/seo` e `/seo/generate`)	`{"error":"category not found"}`
409	`slug` já usado por outra categoria	`{"error":"slug already in use","detail":"slug \"mesas\" is already used by another category"}`
409	`PUT /seo-template` em uma loja que ainda não tem o recurso	`{"error":"category SEO template columns are not present on this store yet (migration 1001022)","detail":"..."}`
500	`id` que não é UUID, ou `lang_code` sem texto cadastrado na categoria	`{"error":"failed to get category SEO","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Mensagens de detail que o servidor escreve em português seguem em português na resposta real.