API atual/Referência completa/Preenchimento de produto com IA

Itens do lote

Lista as propostas de um lote e aprova, recusa ou reverte cada uma.

Cada produto de um lote vira um item. Estas quatro operações são o coração da revisão: você lista os itens, lê a proposta da IA e decide. Aprovar grava a proposta no produto na mesma chamada; recusar descarta; reverter desfaz uma gravação.

Antes de listar, a plataforma marca como expired os itens com mais de 7 dias sem decisão. Todas as rotas exigem manage_ai_tools ou manage_catalog.

GET/api/v1/admin/ai-product-fill/batches/{id}/itemsAdmin

Lista os itens de um lote

Itens do mais recentemente atualizado para o mais antigo.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

Parâmetros de consulta

statusstring

queuedgeneratedapprovedappliedrejectedinvalidatedfailedexpiredcancelled

Filtra por status do item: queued, generated, approved, applied, rejected, invalidated, failed, expired ou cancelled. Sem o filtro, todos. Um valor desconhecido simplesmente não encontra nada.

limitintegerpadrão: 100

Quantidade máxima de itens, de 1 a 500. Fora dessa faixa (ou inválido) vale 100. Não há paginação: para ver mais, filtre por status.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items?status=generated&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Itens retornados

json

{
  "items": [
    {
      "id": "5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f",
      "batch_id": "7d87db3d-2682-42f5-9c40-a91d94e7bf98",
      "product_id": "aaaaaaaa-1111-4111-8111-111111111112",
      "status": "generated",
      "proposal": {
        "description": "<h2>Mouse Gamer</h2><p>Precisão e conforto para longas sessões de jogo.</p>",
        "short_description": null,
        "seo_title": null,
        "seo_description": null,
        "image_alt_text": null,
        "features": [
          { "name": "Cor", "value": "Preto", "matched_feature_id": "b316a51a-50af-4a2f-8688-e562a407956b" }
        ]
      },
      "error": null,
      "applied_at": null
    }
  ],
  "total": 1
}

Campos da resposta

itemsarray

Itens da página, no máximo limit.

items[].iduuid

Id do item.

items[].batch_iduuid

Lote a que pertence.

items[].product_iduuid

Produto que a proposta quer alterar.

items[].statusstring

queuedgeneratedapprovedappliedrejectedinvalidatedfailedexpiredcancelled

Estado do item (tabela na visão geral).

items[].proposalobject

A proposta, ou null enquanto não foi gerada ou quando a geração falhou. Cada campo interno é null se não foi pedido ao criar o lote.

descriptionstring

Descrição completa em HTML simples.

short_descriptionstring

Descrição curta, até 240 caracteres.

seo_titlestring

Título de SEO, até 60 caracteres.

seo_descriptionstring

Descrição de SEO, até 160 caracteres.

image_alt_textarray

Um texto alternativo por foto, na ordem (a principal primeiro).

featuresarray

Características propostas. Cada item tem name, value e matched_feature_id (id da característica já existente com esse nome, ou null se for nova).

items[].errorstring

Motivo da falha quando status é failed. null nos demais.

items[].applied_atstring

Quando a proposta foi gravada (RFC 3339, UTC). null se ainda não foi.

totalinteger

Quantidade de itens nesta resposta (não o total do lote; para isso use total_items do lote).

Erros (listar)

Status	Quando	Corpo de exemplo
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"]}`
500	Falha ao consultar (inclui id de lote que não é UUID).	`{"error":"..."}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/approveAdmin

Aprova e aplica um item

Muda o item de generated para approved e aplica a proposta ao produto na mesma chamada. A resposta diz o desfecho em status: applied (gravado), invalidated (o produto mudou ou sumiu desde a geração; nada foi escrito) ou failed (a gravação deu erro). Só um item em generated pode ser aprovado.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (aprovar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (aprovar)

200Concluído

json

{
  "ok": true,
  "status": "applied",
  "applied": true
}

ok é true sempre que o item estava em revisão, mesmo que o desfecho seja invalidated ou failed: olhe status e applied. Quando não foi aplicado, message traz o motivo (por exemplo o produto mudou desde que a proposta foi gerada).

Erros (aprovar)

Status	Quando	Corpo de exemplo
409	O item não está em `generated` (segundo clique, já aplicado, expirado ou inexistente).	`{"error":"o item não está em revisão","applied":false}`
400	Outro erro ao processar.	`{"error":"..."}`
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"]}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/rejectAdmin

Recusa um item

Muda o item de generated para rejected. Nada é gravado no produto. Só vale para item em generated.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (recusar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/reject" \
  -H "Authorization: Bearer $TOKEN"

Resposta (recusar)

200Concluído

json

{
  "ok": true,
  "status": "rejected",
  "applied": false
}

A resposta tem a mesma forma da aprovação, com status sempre rejected.

Erros (recusar)

Status	Quando	Corpo de exemplo
409	O item não está em `generated`.	`{"error":"o item não está em revisão","applied":false}`
400	Outro erro ao processar.	`{"error":"..."}`
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"]}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/revertAdmin

Reverte um item

Desfaz a gravação de um item, restaurando a descrição que o produto tinha antes, a partir de uma cópia guardada no momento em que a proposta foi gravada. O item volta para generated (de novo revisável) e applied_at é limpo.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (reverter)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/revert" \
  -H "Authorization: Bearer $TOKEN"

Resposta (reverter)

200Concluído

json

{
  "ok": true
}

Resposta mínima: ok: true.

Erros (reverter)

Status	Quando	Corpo de exemplo
400	Item inexistente (ou id que não é UUID). A mensagem é a do banco. Um item sem cópia guardada não dá erro: nada é restaurado e o item volta a `generated`.	`{"error":"sql: no rows in result set"}`
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"]}`

Veja também

Itens do lote

Lista as propostas de um lote e aprova, recusa ou reverte cada uma.

Antes de listar, a plataforma marca como expired os itens com mais de 7 dias sem decisão. Todas as rotas exigem manage_ai_tools ou manage_catalog.

GET/api/v1/admin/ai-product-fill/batches/{id}/itemsAdmin

Lista os itens de um lote

Itens do mais recentemente atualizado para o mais antigo.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

Parâmetros de consulta

statusstring

queuedgeneratedapprovedappliedrejectedinvalidatedfailedexpiredcancelled

limitintegerpadrão: 100

Quantidade máxima de itens, de 1 a 500. Fora dessa faixa (ou inválido) vale 100. Não há paginação: para ver mais, filtre por status.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items?status=generated&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Itens retornados

json

{
  "items": [
    {
      "id": "5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f",
      "batch_id": "7d87db3d-2682-42f5-9c40-a91d94e7bf98",
      "product_id": "aaaaaaaa-1111-4111-8111-111111111112",
      "status": "generated",
      "proposal": {
        "description": "<h2>Mouse Gamer</h2><p>Precisão e conforto para longas sessões de jogo.</p>",
        "short_description": null,
        "seo_title": null,
        "seo_description": null,
        "image_alt_text": null,
        "features": [
          { "name": "Cor", "value": "Preto", "matched_feature_id": "b316a51a-50af-4a2f-8688-e562a407956b" }
        ]
      },
      "error": null,
      "applied_at": null
    }
  ],
  "total": 1
}

Campos da resposta

itemsarray

Itens da página, no máximo limit.

items[].iduuid

Id do item.

items[].batch_iduuid

Lote a que pertence.

items[].product_iduuid

Produto que a proposta quer alterar.

items[].statusstring

queuedgeneratedapprovedappliedrejectedinvalidatedfailedexpiredcancelled

Estado do item (tabela na visão geral).

items[].proposalobject

A proposta, ou null enquanto não foi gerada ou quando a geração falhou. Cada campo interno é null se não foi pedido ao criar o lote.

descriptionstring

Descrição completa em HTML simples.

short_descriptionstring

Descrição curta, até 240 caracteres.

seo_titlestring

Título de SEO, até 60 caracteres.

seo_descriptionstring

Descrição de SEO, até 160 caracteres.

image_alt_textarray

Um texto alternativo por foto, na ordem (a principal primeiro).

featuresarray

Características propostas. Cada item tem name, value e matched_feature_id (id da característica já existente com esse nome, ou null se for nova).

items[].errorstring

Motivo da falha quando status é failed. null nos demais.

items[].applied_atstring

Quando a proposta foi gravada (RFC 3339, UTC). null se ainda não foi.

totalinteger

Quantidade de itens nesta resposta (não o total do lote; para isso use total_items do lote).

Erros (listar)

Status	Quando	Corpo de exemplo
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"]}`
500	Falha ao consultar (inclui id de lote que não é UUID).	`{"error":"..."}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/approveAdmin

Aprova e aplica um item

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (aprovar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (aprovar)

200Concluído

json

{
  "ok": true,
  "status": "applied",
  "applied": true
}

Erros (aprovar)

Status	Quando	Corpo de exemplo
409	O item não está em `generated` (segundo clique, já aplicado, expirado ou inexistente).	`{"error":"o item não está em revisão","applied":false}`
400	Outro erro ao processar.	`{"error":"..."}`
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"]}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/rejectAdmin

Recusa um item

Muda o item de generated para rejected. Nada é gravado no produto. Só vale para item em generated.

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (recusar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/reject" \
  -H "Authorization: Bearer $TOKEN"

Resposta (recusar)

200Concluído

json

{
  "ok": true,
  "status": "rejected",
  "applied": false
}

A resposta tem a mesma forma da aprovação, com status sempre rejected.

Erros (recusar)

Status	Quando	Corpo de exemplo
409	O item não está em `generated`.	`{"error":"o item não está em revisão","applied":false}`
400	Outro erro ao processar.	`{"error":"..."}`
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"]}`

POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/revertAdmin

Reverte um item

Parâmetros de caminho

iduuidobrigatório

Id do lote.

itemIduuidobrigatório

Id do item (UUID), vindo da lista de itens.

Exemplo de requisição (reverter)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/batches/7d87db3d-2682-42f5-9c40-a91d94e7bf98/items/5cc5c4f9-b35d-4b5a-a93e-53fa0ebb9a9f/revert" \
  -H "Authorization: Bearer $TOKEN"

Resposta (reverter)

200Concluído

json

{
  "ok": true
}

Resposta mínima: ok: true.

Erros (reverter)

Status	Quando	Corpo de exemplo
400	Item inexistente (ou id que não é UUID). A mensagem é a do banco. Um item sem cópia guardada não dá erro: nada é restaurado e o item volta a `generated`.	`{"error":"sql: no rows in result set"}`
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"]}`