API atual/Referência completa/Extração de características com IA

Jobs de extração

Cria, consulta e cancela um job que extrai características de produtos com IA.

Um job é uma execução da extração sobre um conjunto de produtos. Crie um quando quiser preencher as características de uma categoria inteira, ou de uma lista de produtos escolhidos. A criação responde na hora com o id do job; o trabalho acontece em segundo plano, produto a produto, com uma pausa de cerca de 2 segundos entre um e outro. Use a consulta para acompanhar e o cancelamento para interromper.

Todas as rotas exigem o privilégio manage_catalog.

POST/api/v1/admin/feature-extraction/jobsAdmin

Cria um job de extração

Corpo da requisição

category_iduuid

Categoria. Sozinha, processa todos os produtos não excluídos dela. Junto com product_ids, define a ficha técnica usada e só os produtos listados são processados.

product_idsarray

Lista de ids (UUID) de produtos. Sem category_id, cada produto usa a ficha técnica da própria categoria.

Informe pelo menos um dos dois. Não há limite documentado de produtos; um job grande demora, pois o ritmo é de poucas dezenas de produtos por minuto.

Exemplo de requisição (criar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "category_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d" }'

Resposta (criar)

202Job aceito

json

{ "job_id": "3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10" }

Campos da resposta

job_iduuid

Id do job, para consultar ou cancelar.

Erros (criar)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid body","detail":"..."}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
403	A loja não tem IA configurada. (O status é o mesmo do privilégio; veja `error`.)	`{"error":"ai unavailable","detail":"no AI provider configured"}`
422	Nenhum produto a processar (nem `category_id` com produtos, nem `product_ids`).	`{"error":"no products to process"}`
422	A categoria não tem ficha técnica (mensagem em português devolvida pelo servidor).	`{"error":"esta categoria não possui ficha técnica configurada (nenhuma característica associada); configure em Características → Modelos por categoria antes de extrair com IA"}`

GET/api/v1/admin/feature-extraction/jobs/{id}Admin

Consulta o andamento de um job

Devolve o status e os contadores. Repita a consulta a cada poucos segundos até status ser done (ou cancelled).

Parâmetros de caminho

iduuidobrigatório

Id do job, devolvido na criação.

Exemplo de requisição (consultar)

bash

curl "$BASE_URL/api/v1/admin/feature-extraction/jobs/3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Job retornado

json

{
  "id": "3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10",
  "category_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "status": "running",
  "total": 40,
  "processed": 12,
  "applied": 9,
  "review": 7
}

Campos da resposta

iduuid

Id do job.

category_iduuid

Categoria do job, ou null se foi criado só com product_ids.

statusstring

queuedrunningdonecancelled

Estado do job.

totalinteger

Quantidade de produtos que entraram no job.

processedinteger

Produtos já processados, inclusive os que a IA não conseguiu ler.

appliedinteger

Valores gravados direto, sem revisão.

reviewinteger

Valores que foram para a fila de revisã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 `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
404	Job inexistente (também para um id que não é UUID).	`{"error":"not found"}`

POST/api/v1/admin/feature-extraction/jobs/{id}/cancelAdmin

Cancela um job

Interrompe um job queued ou running: o produto em andamento termina e os demais não são processados. Valores já gravados e itens já na fila de revisão permanecem. Cancelar um job que já terminou, ou que não existe, não faz nada e também responde 200.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição (cancelar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/jobs/3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta (cancelar)

200Cancelado

json

{ "status": "cancelled" }

Erros (cancelar)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha ao gravar o cancelamento (também para um id que não é UUID).	`{"error":"failed","detail":"..."}`

Veja também

Jobs de extração

Cria, consulta e cancela um job que extrai características de produtos com IA.

Todas as rotas exigem o privilégio manage_catalog.

POST/api/v1/admin/feature-extraction/jobsAdmin

Cria um job de extração

Corpo da requisição

category_iduuid

Categoria. Sozinha, processa todos os produtos não excluídos dela. Junto com product_ids, define a ficha técnica usada e só os produtos listados são processados.

product_idsarray

Lista de ids (UUID) de produtos. Sem category_id, cada produto usa a ficha técnica da própria categoria.

Informe pelo menos um dos dois. Não há limite documentado de produtos; um job grande demora, pois o ritmo é de poucas dezenas de produtos por minuto.

Exemplo de requisição (criar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "category_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d" }'

Resposta (criar)

202Job aceito

json

{ "job_id": "3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10" }

Campos da resposta

job_iduuid

Id do job, para consultar ou cancelar.

Erros (criar)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid body","detail":"..."}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
403	A loja não tem IA configurada. (O status é o mesmo do privilégio; veja `error`.)	`{"error":"ai unavailable","detail":"no AI provider configured"}`
422	Nenhum produto a processar (nem `category_id` com produtos, nem `product_ids`).	`{"error":"no products to process"}`
422	A categoria não tem ficha técnica (mensagem em português devolvida pelo servidor).	`{"error":"esta categoria não possui ficha técnica configurada (nenhuma característica associada); configure em Características → Modelos por categoria antes de extrair com IA"}`

GET/api/v1/admin/feature-extraction/jobs/{id}Admin

Consulta o andamento de um job

Devolve o status e os contadores. Repita a consulta a cada poucos segundos até status ser done (ou cancelled).

Parâmetros de caminho

iduuidobrigatório

Id do job, devolvido na criação.

Exemplo de requisição (consultar)

bash

curl "$BASE_URL/api/v1/admin/feature-extraction/jobs/3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Job retornado

json

{
  "id": "3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10",
  "category_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "status": "running",
  "total": 40,
  "processed": 12,
  "applied": 9,
  "review": 7
}

Campos da resposta

iduuid

Id do job.

category_iduuid

Categoria do job, ou null se foi criado só com product_ids.

statusstring

queuedrunningdonecancelled

Estado do job.

totalinteger

Quantidade de produtos que entraram no job.

processedinteger

Produtos já processados, inclusive os que a IA não conseguiu ler.

appliedinteger

Valores gravados direto, sem revisão.

reviewinteger

Valores que foram para a fila de revisã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 `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
404	Job inexistente (também para um id que não é UUID).	`{"error":"not found"}`

POST/api/v1/admin/feature-extraction/jobs/{id}/cancelAdmin

Cancela um job

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição (cancelar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/jobs/3f6c1d0e-8b3a-4a77-9d0f-6a1a2b7c9e10/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta (cancelar)

200Cancelado

json

{ "status": "cancelled" }

Erros (cancelar)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	Falha ao gravar o cancelamento (também para um id que não é UUID).	`{"error":"failed","detail":"..."}`