API atual/Referência completa/Qualidade do catálogo

Nota e fila de qualidade

Consulta a nota média do catálogo, os principais problemas, a fila de produtos por impacto e pede o recálculo das notas.

Estas três rotas mostram o estado do catálogo e dizem por onde começar a consertar. A nota de cada produto vai de 0 a 100 e mede o quanto o cadastro está completo; a fila ordena os produtos pelo prejuízo que a nota baixa causa (nota baixa em produto muito visitado vem primeiro). Todas exigem o privilégio manage_catalog.

Como a nota é calculada

A nota é a soma de seis dimensões, com pesos fixos:

Dimensão (`dims`)	Pontos	Regra
`photos`	até 25	0 fotos: 0. 1 ou 2 fotos: 15. 3 ou mais: 25.
`description`	até 20	Descrição com menos de 100 caracteres: 0. De 100 a 300: 10. Mais de 300: 20.
`attributes`	até 25	Proporção das características aplicáveis que estão preenchidas. Se a categoria tem um modelo de características obrigatórias, valem elas; senão, as características filtráveis que cobrem a categoria. Sem nenhuma aplicável, vale 25.
`seo`	até 10	10 quando o produto tem título de SEO e descrição de SEO. Senão 0.
`price`	até 10	10 quando o preço é maior que zero e, se há preço "de", ele é maior que o preço atual. Senão 0.
`variations`	até 10	10 quando o produto não tem opções, ou quando todas as variações têm SKU. Senão 0.

O impacto é (100 - nota) × visitas dos últimos 30 dias, com no mínimo 1 visita. Quanto maior, mais urgente. É uma nota de completude do cadastro, não de conversão.

A plataforma recalcula a nota de um produto quando ele muda e faz uma varredura geral toda madrugada. Para forçar agora, use recompute.

GET/api/v1/admin/catalog-quality/summaryAdmin

Resumo da qualidade do catálogo

Devolve a nota média, quantos produtos há em cada faixa de nota, quantos têm problema em cada dimensão e a nota média por seller. Produtos excluídos não entram.

GET/api/v1/admin/catalog-quality/productsAdmin

Fila de produtos por impacto

Lista os produtos do maior impacto para o menor.

Parâmetros de consulta

max_scoreinteger

Só produtos com nota até este valor. 0 ou omitido não filtra.

dimstring

photosdescriptionattributesseopricevariations

Só produtos em que esta dimensão tem menos de 25 pontos. O limite é 25 para qualquer dimensão: como seo, price, variations e description valem no máximo 20, o filtro por elas não exclui ninguém. Use photos ou attributes.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta a 25.

POST/api/v1/admin/catalog-quality/recomputeAdmin

Recalcula todas as notas

Pede o recálculo da nota de todos os produtos da loja. A resposta é imediata (202) e o trabalho segue em segundo plano. Sem corpo.

Exemplo de requisição

bash

# produtos com nota até 60 e sem foto, os de maior impacto primeiro
curl "$BASE_URL/api/v1/admin/catalog-quality/products?max_score=60&dim=photos&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

# resumo geral
curl "$BASE_URL/api/v1/admin/catalog-quality/summary" -H "Authorization: Bearer $TOKEN"

# recalcular tudo
curl -X POST "$BASE_URL/api/v1/admin/catalog-quality/recompute" -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo

json

{
  "avg_score": 70,
  "histogram": [
    { "bucket": "0-20", "count": 0 },
    { "bucket": "21-40", "count": 0 },
    { "bucket": "41-60", "count": 240 },
    { "bucket": "61-80", "count": 4746 },
    { "bucket": "81-100", "count": 5 }
  ],
  "top_issues": [
    { "dim": "photos", "count": 4990 },
    { "dim": "description", "count": 4656 },
    { "dim": "attributes", "count": 1 },
    { "dim": "seo", "count": 4985 },
    { "dim": "price", "count": 1 },
    { "dim": "variations", "count": 1 }
  ],
  "by_vendor": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "vendor_name": "Loja Seller Teste", "avg_score": 64 }
  ]
}

200Fila por impacto

json

{
  "products": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "image_url": "/uploads/dfe2555e/product/c3f92551/foto.png",
      "score": 70,
      "dims": { "photos": 15, "description": 0, "attributes": 25, "seo": 10, "price": 10, "variations": 10 },
      "views_30d": 4,
      "impact": 120,
      "needs_photo": false
    }
  ],
  "total": 4991
}

202Recálculo enfileirado

json

{ "status": "queued" }

Campos do resumo

avg_scoreinteger

Nota média de todos os produtos, de 0 a 100 (parte inteira).

histogramarray

Quantos produtos há em cada faixa: 0-20, 21-40, 41-60, 61-80, 81-100.

top_issuesarray

Para cada dimensão (dim), quantos produtos ainda não têm a pontuação máxima nela (count). Mostra onde está o maior déficit.

by_vendorarray

Nota média por seller (vendor_id, vendor_name, avg_score), até 50, do pior para o melhor, ponderada pelas visitas.

Campos de cada produto da fila

product_iduuid

Id do produto.

namestring

Nome.

image_urlstring

Imagem principal. null quando o produto não tem foto.

scoreinteger

Nota total, de 0 a 100.

dimsobject

Pontos obtidos em cada dimensão (veja a tabela no topo da página).

views_30dinteger

Visitas à página do produto nos últimos 30 dias.

impactinteger

(100 - score) × max(1, views_30d). A fila vem ordenada por este valor, do maior para o menor.

needs_photoboolean

true quando o produto não tem nenhuma imagem. Produtos assim não entram na correção por IA.

totalinteger

Total de produtos que atendem ao filtro (todas as páginas).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha ao consultar	`{"error":"failed","detail":"..."}`

Veja também

Nota e fila de qualidade

Consulta a nota média do catálogo, os principais problemas, a fila de produtos por impacto e pede o recálculo das notas.

Como a nota é calculada

A nota é a soma de seis dimensões, com pesos fixos:

Dimensão (`dims`)	Pontos	Regra
`photos`	até 25	0 fotos: 0. 1 ou 2 fotos: 15. 3 ou mais: 25.
`description`	até 20	Descrição com menos de 100 caracteres: 0. De 100 a 300: 10. Mais de 300: 20.
`attributes`	até 25	Proporção das características aplicáveis que estão preenchidas. Se a categoria tem um modelo de características obrigatórias, valem elas; senão, as características filtráveis que cobrem a categoria. Sem nenhuma aplicável, vale 25.
`seo`	até 10	10 quando o produto tem título de SEO e descrição de SEO. Senão 0.
`price`	até 10	10 quando o preço é maior que zero e, se há preço "de", ele é maior que o preço atual. Senão 0.
`variations`	até 10	10 quando o produto não tem opções, ou quando todas as variações têm SKU. Senão 0.

O impacto é (100 - nota) × visitas dos últimos 30 dias, com no mínimo 1 visita. Quanto maior, mais urgente. É uma nota de completude do cadastro, não de conversão.

A plataforma recalcula a nota de um produto quando ele muda e faz uma varredura geral toda madrugada. Para forçar agora, use recompute.

GET/api/v1/admin/catalog-quality/summaryAdmin

Resumo da qualidade do catálogo

Devolve a nota média, quantos produtos há em cada faixa de nota, quantos têm problema em cada dimensão e a nota média por seller. Produtos excluídos não entram.

GET/api/v1/admin/catalog-quality/productsAdmin

Fila de produtos por impacto

Lista os produtos do maior impacto para o menor.

Parâmetros de consulta

max_scoreinteger

Só produtos com nota até este valor. 0 ou omitido não filtra.

dimstring

photosdescriptionattributesseopricevariations

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Fora disso volta a 25.

POST/api/v1/admin/catalog-quality/recomputeAdmin

Recalcula todas as notas

Pede o recálculo da nota de todos os produtos da loja. A resposta é imediata (202) e o trabalho segue em segundo plano. Sem corpo.

Exemplo de requisição

bash

# produtos com nota até 60 e sem foto, os de maior impacto primeiro
curl "$BASE_URL/api/v1/admin/catalog-quality/products?max_score=60&dim=photos&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

# resumo geral
curl "$BASE_URL/api/v1/admin/catalog-quality/summary" -H "Authorization: Bearer $TOKEN"

# recalcular tudo
curl -X POST "$BASE_URL/api/v1/admin/catalog-quality/recompute" -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo

json

{
  "avg_score": 70,
  "histogram": [
    { "bucket": "0-20", "count": 0 },
    { "bucket": "21-40", "count": 0 },
    { "bucket": "41-60", "count": 240 },
    { "bucket": "61-80", "count": 4746 },
    { "bucket": "81-100", "count": 5 }
  ],
  "top_issues": [
    { "dim": "photos", "count": 4990 },
    { "dim": "description", "count": 4656 },
    { "dim": "attributes", "count": 1 },
    { "dim": "seo", "count": 4985 },
    { "dim": "price", "count": 1 },
    { "dim": "variations", "count": 1 }
  ],
  "by_vendor": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "vendor_name": "Loja Seller Teste", "avg_score": 64 }
  ]
}

200Fila por impacto

json

{
  "products": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "image_url": "/uploads/dfe2555e/product/c3f92551/foto.png",
      "score": 70,
      "dims": { "photos": 15, "description": 0, "attributes": 25, "seo": 10, "price": 10, "variations": 10 },
      "views_30d": 4,
      "impact": 120,
      "needs_photo": false
    }
  ],
  "total": 4991
}

202Recálculo enfileirado

json

{ "status": "queued" }

Campos do resumo

avg_scoreinteger

Nota média de todos os produtos, de 0 a 100 (parte inteira).

histogramarray

Quantos produtos há em cada faixa: 0-20, 21-40, 41-60, 61-80, 81-100.

top_issuesarray

Para cada dimensão (dim), quantos produtos ainda não têm a pontuação máxima nela (count). Mostra onde está o maior déficit.

by_vendorarray

Nota média por seller (vendor_id, vendor_name, avg_score), até 50, do pior para o melhor, ponderada pelas visitas.

Campos de cada produto da fila

product_iduuid

Id do produto.

namestring

Nome.

image_urlstring

Imagem principal. null quando o produto não tem foto.

scoreinteger

Nota total, de 0 a 100.

dimsobject

Pontos obtidos em cada dimensão (veja a tabela no topo da página).

views_30dinteger

Visitas à página do produto nos últimos 30 dias.

impactinteger

(100 - score) × max(1, views_30d). A fila vem ordenada por este valor, do maior para o menor.

needs_photoboolean

true quando o produto não tem nenhuma imagem. Produtos assim não entram na correção por IA.

totalinteger

Total de produtos que atendem ao filtro (todas as páginas).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha ao consultar	`{"error":"failed","detail":"..."}`