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

Lotes de enriquecimento

Cria, lista e consulta lotes que geram com IA textos, características e SEO para muitos produtos de uma vez.

Um lote é uma fila de trabalho: você descreve com um filtro quais produtos quer enriquecer e quais campos quer gerar, e a plataforma passa a gerar uma proposta para cada produto, em segundo plano (até 4 produtos em paralelo). A criação responde na hora; o andamento você acompanha consultando o lote (done_items, failed_items, status).

Cada produto vira um item com sua proposta. Nada é gravado no produto até você aprovar o item (Itens do lote), com uma exceção que você escolhe: os campos de auto_apply_fields, gravados assim que são gerados.

Quando usar: catálogos recém-importados com descrições vazias, melhoria de SEO em massa, preenchimento de características que faltam.

Auto-aplicar grava antes de você revisar

Campos listados em auto_apply_fields (somente image_alt_text e seo_description são aceitos) são gravados no produto no momento em que a proposta é gerada, sem passar pela revisão. O item continua com status generated, mas esses campos já estão no ar. Deixe auto_apply_fields vazio se quiser revisar tudo.

POST/api/v1/admin/ai-product-fill/batchesAdmin

Cria um lote e inicia a geração

Privilégio exigido: manage_ai_tools ou manage_catalog. Resposta 201 com o lote criado; a geração começa em segundo plano.

Corpo da requisição

filterobject

Quais produtos entram. Sem filter (ou com {}), entram todos os produtos ativos do catálogo, até o limite de 10.000. Produtos excluídos nunca entram. Os critérios se combinam com "e".

category_idsarray
Ids (UUID) de categorias. Só produtos cuja categoria principal esteja na lista.
vendor_iduuid
Só produtos deste seller (lojista).
empty_descriptionbooleanpadrão: false
true seleciona produtos sem descrição ou com menos de 200 caracteres de texto (as marcações HTML não contam).
no_featuresbooleanpadrão: false
true seleciona produtos que não têm nenhuma característica preenchida.
include_disabledbooleanpadrão: false
Por padrão produtos desativados ficam de fora. true os inclui.
fieldsarrayobrigatório
descriptionshort_descriptionseo_titleseo_descriptionimage_alt_textfeatures
Campos a gerar. Nomes fora da lista são descartados em silêncio; se não sobrar nenhum, o erro é fields required. image_alt_text gera um texto alternativo por foto (só funciona em produto com fotos); features propõe pares nome/valor de características.
auto_apply_fieldsarray
image_alt_textseo_description
Campos gravados sem revisão (veja o aviso acima). Outros nomes são descartados.

Exemplo de requisição (criar)

Resposta (criar)

201Lote criado

Campos da resposta

iduuid
Id do lote.
filterobject
O filtro aplicado, com todas as chaves preenchidas.
fieldsarray
Campos a gerar, já sem os nomes inválidos.
auto_apply_fieldsarray
Campos gravados sem revisão.
statusstring
queuedrunningpausedcompletedcancelledfailed
Estado do lote (veja a visão geral).
total_itemsinteger
Quantos produtos o filtro encontrou (e viraram itens).
done_itemsinteger
Itens com proposta gerada.
failed_itemsinteger
Itens cuja geração falhou, mesmo depois de uma segunda tentativa automática.
score_beforenumber
Média da nota de qualidade (0 a 100) dos anúncios no início. Calculada em segundo plano, então pode ser null logo após a criação.
score_afternumber
Média depois do lote. Na prática costuma ficar null ou igual ao valor inicial; não use como medida de resultado.
created_atstring
Data de criação, RFC 3339, UTC.

Erros (criar)

StatusQuandoCorpo de exemplo
400Corpo não é JSON válido.{"error":"invalid_request_body"}
400fields vazio ou só com nomes inválidos.{"error":"fields required"}
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem manage_ai_tools nem manage_catalog.{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}
422O filtro não encontrou nenhum produto. Nada é criado.{"error":"nenhum produto corresponde ao filtro"}
Mensagem em português

A mensagem do 422 é devolvida em português pelo servidor, e assim deve ser tratada: compare pelo status 422, não pelo texto.

GET/api/v1/admin/ai-product-fill/batchesAdmin

Lista os lotes recentes

Privilégio exigido: manage_ai_tools ou manage_catalog. Devolve até os 200 lotes mais novos, sem paginação e sem filtros.

Exemplo de requisição (listar)

Resposta (listar)

200Lotes retornados

Campos da resposta

batchesarray
Lotes, do mais novo ao mais antigo, no mesmo formato da criação.
totalinteger
Quantidade de lotes devolvidos (no máximo 200).

Erros (listar)

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem o privilégio necessário.{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}
500Falha ao consultar.{"error":"..."}
GET/api/v1/admin/ai-product-fill/batches/{id}Admin

Consulta um lote

Privilégio exigido: manage_ai_tools ou manage_catalog. Use para acompanhar o progresso: repita a consulta a cada poucos segundos até status ser completed.

Parâmetros de caminho

iduuidobrigatório
Id do lote.

Exemplo de requisição (consultar)

Resposta (consultar)

200Lote retornado

Os campos são os mesmos da criação.

Erros (consultar)

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem o privilégio necessário.{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}
404Lote inexistente (ou id que não é UUID válido).{"error":"sql: no rows in result set"}
Mensagem de erro do servidor

O texto do 404 vem direto do banco de dados. Com um id que não é UUID, ele chega a incluir a mensagem técnica do banco (invalid input syntax for type uuid). Trate o status, não o texto, e valide o formato do id antes de chamar.

Veja também

  • Controlar o lote: pausar, retomar e cancelar.
  • Itens do lote: revisar as propostas.
  • Aplicar em massa
Anterior
Histórico de gerações
Próxima
Controlar o lote
Nesta página
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Exemplo de requisição (consultar)
  • Resposta (consultar)
  • Erros (consultar)
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "empty_description": true, "include_disabled": false },
    "fields": ["description", "features"],
    "auto_apply_fields": []
  }'
bash
curl "$BASE_URL/api/v1/admin/ai-product-fill/batches" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "id": "7d87db3d-2682-42f5-9c40-a91d94e7bf98",
  "filter": {
    "category_ids": [],
    "vendor_id": null,
    "empty_description": true,
    "no_features": false,
    "include_disabled": false
  },
  "fields": ["description", "features"],
  "auto_apply_fields": [],
  "status": "queued",
  "total_items": 1873,
  "done_items": 0,
  "failed_items": 0,
  "score_before": null,
  "score_after": null,
  "created_at": "2026-07-13T03:11:04.869808Z"
}
json
{
  "batches": [
    {
      "id": "82ae9416-ec09-43bf-9c56-16daa9598e3f",
      "filter": { "category_ids": [], "vendor_id": null, "empty_description": true, "no_features": false, "include_disabled": false },
      "fields": ["description", "features"],
      "auto_apply_fields": [],
      "status": "cancelled",
      "total_items": 1575,
      "done_items": 156,
      "failed_items": 0,
      "score_before": 65.4,
      "score_after": null,
      "created_at": "2026-07-20T00:36:58.359926Z"
    }
  ],
  "total": 1
}
json
{
  "id": "7d87db3d-2682-42f5-9c40-a91d94e7bf98",
  "filter": { "category_ids": [], "vendor_id": null, "empty_description": true, "no_features": false, "include_disabled": false },
  "fields": ["description", "features"],
  "auto_apply_fields": [],
  "status": "completed",
  "total_items": 1873,
  "done_items": 1870,
  "failed_items": 3,
  "score_before": 53.4,
  "score_after": 53.4,
  "created_at": "2026-07-13T03:11:04.869808Z"
}