VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Qualidade do catálogo

Nota de qualidade dos produtos do seller e revisão assistida por IA: pedir propostas, aprovar e aplicar.

A qualidade do catálogo dá uma nota de 0 a 100 para cada produto do seller, a partir de seis critérios (fotos, descrição, atributos, SEO, preço e variações), e mostra onde melhorar primeiro. A plataforma também consegue propor textos melhores com IA: você pede uma revisão, confere o que foi proposto, aprova o que serve e só então os produtos são alterados.

Pontos principais
  • Tudo é restrito aos seus produtos. Trabalho ou produto de outro seller responde 404.
  • A IA nunca grava sozinha: as propostas ficam em revisão até você aprovar e chamar apply.
  • Só quatro campos podem ser propostos: description, short_desc, seo_title e seo_description. Nome e preço nunca mudam por aqui.
  • A revisão é assíncrona: crie o trabalho, consulte o andamento e só depois liste as propostas.
  • Criar revisão e aplicar exigem que o recurso de IA esteja disponível na loja; sem ele, 403 ai fix unavailable.

Como funciona

  1. Veja onde melhorar

    Leia o resumo e a fila de produtos por impacto. O impacto combina a nota baixa com as visitas dos últimos 30 dias: produto ruim e muito visto vem primeiro.

  2. Peça uma revisão

    Crie o trabalho de revisão com os produtos e os campos desejados.

  3. Aguarde a revisão

    Consulte o trabalho até o status chegar a review.

  4. Aprove ou rejeite

    Liste as propostas, compare atual e proposto, aprove ou rejeite cada uma.

  5. Aplique

    apply grava só as propostas aprovadas. As rejeitadas e as pendentes não mudam o produto.

Status do trabalho:

StatusSignificado
queuedNa fila, ainda não começou.
runningA IA está gerando as propostas.
reviewPropostas prontas, aguardando a sua decisão.
applyingAs aprovadas estão sendo gravadas.
doneConcluído.
cancelledCancelado antes de terminar.

Status de cada proposta: pending (ainda sem proposta), proposed (pronta para decidir), approved, rejected, applied (já gravada) e failed (a IA ou a gravação falhou; o motivo vem em error).

Conceitos importantes

Os seis critérios

Critério (dim)Pontos máximosComo pontua
photos25Nenhuma imagem: 0. Uma ou duas: 15. Três ou mais: 25.
description20Descrição com menos de 100 caracteres: 0. De 100 a 300: 10. Mais de 300: 20.
attributes25Proporção das características exigidas pela ficha da categoria que estão preenchidas. Sem ficha, vale a proporção das características filtráveis da categoria.
seo10Título SEO e descrição SEO preenchidos: 10; senão 0.
price10Preço maior que zero e, se há preço "De", ele maior que o preço de venda: 10; senão 0.
variations10Produto sem opções de compra: 10. Com opções, só pontua se todos os registros de variação tiverem SKU.

A nota do produto é a soma dos critérios (0 a 100). As notas são recalculadas sozinhas quando o produto muda; use recompute só quando quiser forçar.

Endpoints

MétodoCaminhoPara que serve
GET/api/v1/vendor/catalog-quality/summaryResumo da qualidade dos seus produtos.
GET/api/v1/vendor/catalog-quality/productsFila de produtos a melhorar, do maior impacto ao menor.
POST/api/v1/vendor/catalog-quality/recomputeRecalcula as notas dos seus produtos.
POST/api/v1/vendor/catalog-quality/review-jobsCria uma revisão com propostas da IA.
GET/api/v1/vendor/catalog-quality/fix-jobs/{id}Consulta o andamento da revisão.
POST/api/v1/vendor/catalog-quality/fix-jobs/{id}/cancelCancela a revisão.
GET/api/v1/vendor/catalog-quality/fix-jobs/{id}/itemsLista as propostas (atual contra proposto).
POST/api/v1/vendor/catalog-quality/fix-jobs/{id}/items/{itemId}/approveAprova uma proposta.
POST/api/v1/vendor/catalog-quality/fix-jobs/{id}/items/{itemId}/rejectRejeita uma proposta.
POST/api/v1/vendor/catalog-quality/fix-jobs/{id}/approve-allAprova todas as propostas pendentes.
POST/api/v1/vendor/catalog-quality/fix-jobs/{id}/applyGrava as propostas aprovadas nos produtos.

Erros comuns

  1. Listar as propostas cedo demais. Enquanto o trabalho está queued ou running, a lista pode vir vazia ou incompleta. Espere review.
  2. Esperar que approve-all grave. Ele só marca como aprovadas; a gravação é apply.
  3. Pedir revisão de produto de outro seller. Basta um id que não seja seu para o trabalho inteiro ser recusado com 404.
  4. Mandar campos fora da lista. Campos desconhecidos são descartados; se nada sobrar, a resposta é 422 failed (no allowed fields).
  5. Usar dim de pontuação menor que 25 como filtro. O filtro dim considera "ruim" qualquer nota abaixo de 25 pontos, então para description, seo, price e variations (máximos menores) ele não filtra nada. Prefira o dims retornado em cada produto.
  6. Cancelar um trabalho em review. Só trabalhos queued ou running são cancelados; nos demais a chamada responde 200 mas não muda nada.

Próximos passos

Resumo e fila
Onde melhorar primeiro.
Criar revisão
Peça propostas de texto.
Aprovar e aplicar
Decida o que vai para o produto.
Anterior
Exportar categorias e ficha técnica
Próxima
Resumo e fila de qualidade
Nesta página
  • Como funciona
  • Conceitos importantes
  • Os seis critérios
  • Endpoints
  • Erros comuns
  • Próximos passos