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

Correção com revisão

Pede propostas de descrição e SEO por IA para vários produtos, acompanha o job e lista as propostas ao lado dos valores atuais.

Produtos com descrição curta ou sem título de SEO puxam a nota de qualidade para baixo. A correção com revisão gera, por IA, um texto novo para cada produto escolhido, mas não grava nada no produto. As propostas ficam guardadas para uma pessoa conferir uma a uma (aprovar ou rejeitar) e só depois aplicar. É o caminho recomendado.

queued→running→review→applying→done

Status do job	Significado
`queued`	Criado, ainda não começou.
`running`	Gerando propostas, um produto a cada 2 segundos.
`review`	Todas as propostas foram geradas e aguardam decisão.
`applying`	A aplicação dos itens aprovados está em andamento.
`done`	Terminou.
`cancelled`	Cancelado antes de terminar.

Os campos que a IA pode preencher são só estes quatro: description, short_desc, seo_title e seo_description. Nome e preço nunca são tocados. Todas as rotas exigem manage_catalog, e a geração só funciona nas lojas com o preenchimento de produto por IA disponível.

POST/api/v1/admin/catalog-quality/review-jobsAdmin

Cria um job de propostas para revisão

Cria o job e devolve na hora (202) o job_id. A geração continua em segundo plano.

Corpo da requisição (JSON)

product_idsarrayobrigatório

Ids dos produtos a corrigir (UUIDs). Pelo menos um.

fieldsarrayobrigatório

descriptionshort_descseo_titleseo_description

Campos a propor. Valores fora da lista são descartados em silêncio; se não sobrar nenhum, a resposta é 422.

GET/api/v1/admin/catalog-quality/fix-jobs/{id}Admin

Consulta o andamento do job

Devolve o estado do job. Vale tanto para jobs de revisão quanto para os da correção automática.

Parâmetros de caminho

iduuidobrigatório

O job_id.

GET/api/v1/admin/catalog-quality/fix-jobs/{id}/itemsAdmin

Lista as propostas do job

Devolve uma proposta por produto, já com os valores atuais ao lado para comparar. Sem paginação: vêm todos os itens do job.

Parâmetros de caminho

iduuidobrigatório

O job_id.

Exemplo de requisição

bash

# 1) pedir propostas
curl -X POST "$BASE_URL/api/v1/admin/catalog-quality/review-jobs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_ids":["c3f92551-9dda-4fc7-b518-353d1c4e4035"],"fields":["description","seo_title","seo_description"]}'

# 2) acompanhar até status = review
curl "$BASE_URL/api/v1/admin/catalog-quality/fix-jobs/$JOB" -H "Authorization: Bearer $TOKEN"

# 3) ler as propostas
curl "$BASE_URL/api/v1/admin/catalog-quality/fix-jobs/$JOB/items" -H "Authorization: Bearer $TOKEN"

Resposta

202Job criado

json

{ "job_id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34" }

200Job

json

{
  "id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34",
  "status": "review",
  "fields": ["description", "seo_title", "seo_description"],
  "total": 1,
  "processed": 1,
  "succeeded": 1,
  "failed": 0,
  "processed_items": 1,
  "failed_items": 0
}

200Propostas

json

{
  "items": [
    {
      "id": "0b5d7a2e-91c4-4f6a-8c3e-7d1f4a9b2c10",
      "job_id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "proposed": {
        "description": "Notebook Slim Rosa com tela de 14 polegadas, leve e fino, ideal para estudo e trabalho...",
        "meta_title": "Notebook Slim Rosa 14\" | Leve e fino",
        "meta_description": "Compre o Notebook Slim Rosa com envio rápido para todo o Brasil."
      },
      "current": {
        "description": "",
        "short_desc": "",
        "seo_title": "",
        "seo_description": ""
      },
      "status": "proposed"
    }
  ],
  "total": 1
}

Campos do job

iduuid

Id do job.

statusstring

queuedrunningreviewapplyingdonecancelled

Estado, como na tabela do início.

fieldsarray

Campos que o job propõe.

totalinteger

Produtos no job.

processedinteger

Produtos já tratados. Igual a processed_items.

succeededinteger

Propostas geradas.

failedinteger

Produtos em que a geração falhou. Igual a failed_items.

Campos de cada proposta

iduuid

Id do item (use em aprovar e rejeitar).

product_iduuid

Produto.

namestring

Nome do produto.

proposedobject

Texto proposto, por campo. Só trazem chave os campos pedidos em fields que a IA conseguiu gerar. Os nomes são description, short_description, meta_title e meta_description, diferentes dos de current (veja a nota abaixo). Vazio quando a geração falhou.

currentobject

Valores atuais do produto: description, short_desc, seo_title, seo_description.

statusstring

pendingproposedapprovedrejectedappliedfailed

Estado do item. pending ainda sem proposta; proposed aguardando decisão; approved e rejected decididos; applied gravado no produto; failed falhou (veja error).

errorstring

Motivo, quando status é failed.

Erros

Status	Quando	Corpo de exemplo
400	`product_ids` vazio	`{"error":"product_ids required"}`
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`, ou a loja não tem o preenchimento por IA	`{"error":"ai fix unavailable","detail":"AI Product Fill is not available"}`
404	Job não existe (ou id que não é UUID)	`{"error":"job not found"}`
422	Nenhum campo permitido em `fields`	`{"error":"failed to create job","detail":"no allowed fields"}`

Veja também

Correção com revisão

Pede propostas de descrição e SEO por IA para vários produtos, acompanha o job e lista as propostas ao lado dos valores atuais.

queued→running→review→applying→done

Status do job	Significado
`queued`	Criado, ainda não começou.
`running`	Gerando propostas, um produto a cada 2 segundos.
`review`	Todas as propostas foram geradas e aguardam decisão.
`applying`	A aplicação dos itens aprovados está em andamento.
`done`	Terminou.
`cancelled`	Cancelado antes de terminar.

POST/api/v1/admin/catalog-quality/review-jobsAdmin

Cria um job de propostas para revisão

Cria o job e devolve na hora (202) o job_id. A geração continua em segundo plano.

Corpo da requisição (JSON)

product_idsarrayobrigatório

Ids dos produtos a corrigir (UUIDs). Pelo menos um.

fieldsarrayobrigatório

descriptionshort_descseo_titleseo_description

Campos a propor. Valores fora da lista são descartados em silêncio; se não sobrar nenhum, a resposta é 422.

GET/api/v1/admin/catalog-quality/fix-jobs/{id}Admin

Consulta o andamento do job

Devolve o estado do job. Vale tanto para jobs de revisão quanto para os da correção automática.

Parâmetros de caminho

iduuidobrigatório

O job_id.

GET/api/v1/admin/catalog-quality/fix-jobs/{id}/itemsAdmin

Lista as propostas do job

Devolve uma proposta por produto, já com os valores atuais ao lado para comparar. Sem paginação: vêm todos os itens do job.

Parâmetros de caminho

iduuidobrigatório

O job_id.

Exemplo de requisição

bash

# 1) pedir propostas
curl -X POST "$BASE_URL/api/v1/admin/catalog-quality/review-jobs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_ids":["c3f92551-9dda-4fc7-b518-353d1c4e4035"],"fields":["description","seo_title","seo_description"]}'

# 2) acompanhar até status = review
curl "$BASE_URL/api/v1/admin/catalog-quality/fix-jobs/$JOB" -H "Authorization: Bearer $TOKEN"

# 3) ler as propostas
curl "$BASE_URL/api/v1/admin/catalog-quality/fix-jobs/$JOB/items" -H "Authorization: Bearer $TOKEN"

Resposta

202Job criado

json

{ "job_id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34" }

200Job

json

{
  "id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34",
  "status": "review",
  "fields": ["description", "seo_title", "seo_description"],
  "total": 1,
  "processed": 1,
  "succeeded": 1,
  "failed": 0,
  "processed_items": 1,
  "failed_items": 0
}

200Propostas

json

{
  "items": [
    {
      "id": "0b5d7a2e-91c4-4f6a-8c3e-7d1f4a9b2c10",
      "job_id": "9d2f1c5e-3a7b-4c88-b1d0-52a8e6f01a34",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "proposed": {
        "description": "Notebook Slim Rosa com tela de 14 polegadas, leve e fino, ideal para estudo e trabalho...",
        "meta_title": "Notebook Slim Rosa 14\" | Leve e fino",
        "meta_description": "Compre o Notebook Slim Rosa com envio rápido para todo o Brasil."
      },
      "current": {
        "description": "",
        "short_desc": "",
        "seo_title": "",
        "seo_description": ""
      },
      "status": "proposed"
    }
  ],
  "total": 1
}

Campos do job

iduuid

Id do job.

statusstring

queuedrunningreviewapplyingdonecancelled

Estado, como na tabela do início.

fieldsarray

Campos que o job propõe.

totalinteger

Produtos no job.

processedinteger

Produtos já tratados. Igual a processed_items.

succeededinteger

Propostas geradas.

failedinteger

Produtos em que a geração falhou. Igual a failed_items.

Campos de cada proposta

iduuid

Id do item (use em aprovar e rejeitar).

product_iduuid

Produto.

namestring

Nome do produto.

proposedobject

currentobject

Valores atuais do produto: description, short_desc, seo_title, seo_description.

statusstring

pendingproposedapprovedrejectedappliedfailed

Estado do item. pending ainda sem proposta; proposed aguardando decisão; approved e rejected decididos; applied gravado no produto; failed falhou (veja error).

errorstring

Motivo, quando status é failed.

Erros

Status	Quando	Corpo de exemplo
400	`product_ids` vazio	`{"error":"product_ids required"}`
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`, ou a loja não tem o preenchimento por IA	`{"error":"ai fix unavailable","detail":"AI Product Fill is not available"}`
404	Job não existe (ou id que não é UUID)	`{"error":"job not found"}`
422	Nenhum campo permitido em `fields`	`{"error":"failed to create job","detail":"no allowed fields"}`