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.

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)

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": []
  }'

Resposta (criar)

201Lote criado

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"
}

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)

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

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)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Lotes retornados

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
}

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)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
500	Falha 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)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Lote retornado

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"
}

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

Erros (consultar)

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

Veja também

Controlar o lote: pausar, retomar e cancelar.
Itens do lote: revisar as propostas.
Aplicar em massa

Lotes de enriquecimento

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

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

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

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)

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": []
  }'

Resposta (criar)

201Lote criado

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"
}

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)

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

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)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Lotes retornados

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
}

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)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
500	Falha 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)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Lote retornado

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"
}

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

Erros (consultar)

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

Veja também

Controlar o lote: pausar, retomar e cancelar.
Itens do lote: revisar as propostas.
Aplicar em massa