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

Fila de revisão

Lista os valores que a IA propôs com confiança média e aprova ou recusa cada um.

Quando a IA não tem certeza o bastante (ou quando o valor exigiria criar uma opção nova em uma característica de lista), o valor não é gravado: ele fica na fila de revisão. Aqui você lista essa fila, aprova os itens corretos (o valor é gravado no produto) e recusa os errados (eles saem da fila e nada muda).

Ao aprovar um valor de uma característica de lista cuja opção ainda não existe, a plataforma cria a opção e então grava o valor. A gravação dispara o evento de produto atualizado (busca reindexada, nota de qualidade recalculada). Todas as rotas exigem manage_catalog.

GET/api/v1/admin/feature-extraction/reviewAdmin

Lista os itens em revisão

Devolve até 500 itens, da maior para a menor confiança. Não há paginação.

Parâmetros de consulta

job_iduuid

Só itens deste job.

feature_iduuid

Só itens desta característica (por exemplo, só a cor).

Exemplo de requisição (listar)

bash

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

Resposta (listar)

200Itens retornados

json

{
  "items": [
    {
      "id": "dbc0d593-e444-4973-9985-1ec20044d154",
      "product_id": "e7a1757e-3f19-421c-836a-684737295885",
      "product_name": "Air Fryer Ultra Bege 02768 - PROMOÇÃO",
      "feature_id": "b316a51a-50af-4a2f-8688-e562a407956b",
      "feature_name": "Cor",
      "proposed_value": "preta",
      "confidence": 0.95,
      "status": "review"
    }
  ]
}

Campos da resposta

itemsarray

Itens em revisão, máximo 500.

items[].iduuid

Id do item, usado em apply e reject.

items[].product_iduuid

Produto que receberia o valor.

items[].product_namestring

Nome do produto, para exibir.

items[].feature_iduuid

Característica a preencher.

items[].feature_namestring

Nome da característica, para exibir.

items[].proposed_valuestring

Valor proposto pela IA, já normalizado.

items[].confidencenumber

Confiança de 0 a 1.

items[].statusstring

Sempre review nesta lista.

Erros (listar)

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 consultar (inclui `job_id` ou `feature_id` que não é UUID).	`{"error":"failed","detail":"..."}`

POST/api/v1/admin/feature-extraction/review/applyAdmin

Aprova itens e grava os valores

Grava no produto o valor de cada item informado que ainda esteja em revisão. Itens já decididos, de outro estado ou inexistentes são ignorados em silêncio.

Corpo da requisição

item_idsarrayobrigatório

Ids (UUID) dos itens a aprovar, vindos da listagem.

Exemplo de requisição (aprovar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/review/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "item_ids": ["dbc0d593-e444-4973-9985-1ec20044d154"] }'

Resposta (aprovar)

200Processado

json

{ "status": "applied" }

A resposta não diz quantos itens foram de fato gravados. Para conferir, liste a fila de novo: os aprovados saem dela.

Erros (aprovar)

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

POST/api/v1/admin/feature-extraction/review/rejectAdmin

Recusa itens da fila

Descarta os itens informados que ainda estejam em revisão. O produto não é alterado e o item não volta à fila. Como na aprovação, ids que não estão em revisão são ignorados em silêncio.

Corpo da requisição

item_idsarrayobrigatório

Ids (UUID) dos itens a recusar.

Exemplo de requisição (recusar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/review/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "item_ids": ["dbc0d593-e444-4973-9985-1ec20044d154"] }'

Resposta (recusar)

200Processado

json

{ "status": "rejected" }

Erros (recusar)

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

Veja também

Fila de revisão

Lista os valores que a IA propôs com confiança média e aprova ou recusa cada um.

GET/api/v1/admin/feature-extraction/reviewAdmin

Lista os itens em revisão

Devolve até 500 itens, da maior para a menor confiança. Não há paginação.

Parâmetros de consulta

job_iduuid

Só itens deste job.

feature_iduuid

Só itens desta característica (por exemplo, só a cor).

Exemplo de requisição (listar)

bash

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

Resposta (listar)

200Itens retornados

json

{
  "items": [
    {
      "id": "dbc0d593-e444-4973-9985-1ec20044d154",
      "product_id": "e7a1757e-3f19-421c-836a-684737295885",
      "product_name": "Air Fryer Ultra Bege 02768 - PROMOÇÃO",
      "feature_id": "b316a51a-50af-4a2f-8688-e562a407956b",
      "feature_name": "Cor",
      "proposed_value": "preta",
      "confidence": 0.95,
      "status": "review"
    }
  ]
}

Campos da resposta

itemsarray

Itens em revisão, máximo 500.

items[].iduuid

Id do item, usado em apply e reject.

items[].product_iduuid

Produto que receberia o valor.

items[].product_namestring

Nome do produto, para exibir.

items[].feature_iduuid

Característica a preencher.

items[].feature_namestring

Nome da característica, para exibir.

items[].proposed_valuestring

Valor proposto pela IA, já normalizado.

items[].confidencenumber

Confiança de 0 a 1.

items[].statusstring

Sempre review nesta lista.

Erros (listar)

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 consultar (inclui `job_id` ou `feature_id` que não é UUID).	`{"error":"failed","detail":"..."}`

POST/api/v1/admin/feature-extraction/review/applyAdmin

Aprova itens e grava os valores

Grava no produto o valor de cada item informado que ainda esteja em revisão. Itens já decididos, de outro estado ou inexistentes são ignorados em silêncio.

Corpo da requisição

item_idsarrayobrigatório

Ids (UUID) dos itens a aprovar, vindos da listagem.

Exemplo de requisição (aprovar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/review/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "item_ids": ["dbc0d593-e444-4973-9985-1ec20044d154"] }'

Resposta (aprovar)

200Processado

json

{ "status": "applied" }

A resposta não diz quantos itens foram de fato gravados. Para conferir, liste a fila de novo: os aprovados saem dela.

Erros (aprovar)

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

POST/api/v1/admin/feature-extraction/review/rejectAdmin

Recusa itens da fila

Descarta os itens informados que ainda estejam em revisão. O produto não é alterado e o item não volta à fila. Como na aprovação, ids que não estão em revisão são ignorados em silêncio.

Corpo da requisição

item_idsarrayobrigatório

Ids (UUID) dos itens a recusar.

Exemplo de requisição (recusar)

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-extraction/review/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "item_ids": ["dbc0d593-e444-4973-9985-1ec20044d154"] }'

Resposta (recusar)

200Processado

json

{ "status": "rejected" }

Erros (recusar)

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