API atual/Referência completa/Perguntas de produto

Perguntas de produto

Lista a fila de perguntas públicas sobre produtos e responde, rejeita ou arquiva cada uma.

Na página de um produto, visitantes e clientes podem fazer perguntas públicas. A resposta, depois de publicada, fica visível para todos e ajuda na decisão de compra (e entra no índice de busca do produto). Estas quatro rotas são a fila da equipe da loja: ver o que chegou, responder, rejeitar como spam ou arquivar. O seller dono do produto também pode responder, pela API de seller.

Todas exigem o privilégio manage_content. Mais de uma pessoa pode estar moderando ao mesmo tempo, então confira o status antes de agir.

Listar perguntas

GET/api/v1/admin/product-questionsAdmin

Listar perguntas, mais novas primeiro

Devolve 50 perguntas por página, da mais nova para a mais antiga, com o nome do produto e os dados de quem perguntou. O tamanho da página não é configurável por esta rota.

Parâmetros de consulta

statusstring

pendingansweredrejectedarchived

Filtra por status. Vazio traz todos. Um valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página. Valor inválido ou menor que 1 vale 1.

bash

curl "$BASE_URL/api/v1/admin/product-questions?status=pending" \
  -H "Authorization: Bearer $TOKEN"

200Perguntas

json

{
  "questions": [
    {
      "id": "8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_name": "Notebook Vintage Vermelho",
      "guest_name": "Maria",
      "guest_email": "maria.souza@example.com",
      "question_text": "Esse caderno tem folhas pautadas?",
      "status": "pending",
      "ai_draft": "Sim, o caderno tem folhas pautadas.",
      "ai_draft_shown": false,
      "created_at": "2026-10-11T14:22:05Z"
    }
  ]
}

Campos da resposta

questions[].iduuid

Id da pergunta.

questions[].product_iduuid

Produto da pergunta.

questions[].product_namestring

Nome do produto.

questions[].user_iduuid

Cliente logado que perguntou. Ausente para visitantes.

questions[].guest_namestring

Nome informado por visitante. Ausente quando não há.

questions[].guest_emailstring

E-mail do visitante. Nunca é exposto ao público; só a moderação o vê.

questions[].question_textstring

Texto da pergunta, de 5 a 500 caracteres.

questions[].statusstring

pendingansweredrejectedarchived

Situação.

questions[].ai_draftstring

Rascunho de resposta gerado automaticamente, para a equipe usar de base. Ausente quando não existe.

questions[].ai_draft_shownboolean

Se o rascunho está visível ao público como resposta provisória.

questions[].answer_textstring

Resposta oficial. Ausente antes de responder.

questions[].answered_bystring

Quem respondeu: admin ou o id do seller.

questions[].answered_atstring

Quando foi respondida, RFC 3339.

questions[].created_atstring

Quando foi feita, RFC 3339, UTC.

Responder

PUT/api/v1/admin/product-questions/{id}/answerAdmin

Publicar a resposta de uma pergunta

Grava a resposta, marca a pergunta como answered e publica na página do produto (o produto é reindexado). Só perguntas pending ou archived são respondidas. Se a pergunta já foi respondida ou rejeitada, a rota não muda nada e devolve o estado atual com 200.

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

Corpo da requisição

answer_textstringobrigatório

Texto da resposta. Espaços nas pontas são removidos; vazio é recusado.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/answer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answer_text":"Sim, o caderno tem 96 folhas pautadas."}'

200Pergunta respondida

A resposta é a pergunta completa, no formato da lista, agora com status: "answered", answer_text, answered_by: "admin" e answered_at.

Rejeitar

PUT/api/v1/admin/product-questions/{id}/rejectAdmin

Rejeitar uma pergunta como spam ou ofensa

Marca a pergunta como rejected, o que a tira da página pública. Sem corpo. A rota não confere se a pergunta existe nem em que estado estava: rejeita mesmo uma pergunta já respondida.

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/reject" \
  -H "Authorization: Bearer $TOKEN"

200Pergunta rejeitada

json

{ "rejected": true }

Arquivar

PUT/api/v1/admin/product-questions/{id}/archiveAdmin

Arquivar uma pergunta

Marca a pergunta como archived, escondendo-a da página do produto sem apagá-la. Uma pergunta arquivada pode ser respondida depois. Sem corpo. Também não confere se a pergunta existe.

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/archive" \
  -H "Authorization: Bearer $TOKEN"

200Pergunta arquivada

json

{ "archived": true }

Erros

Status	Quando	Corpo de exemplo
400	`answer` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`answer` com `answer_text` vazio.	`{"error":"answer required"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_content`.	`{"error":"insufficient privileges","privilege_required_any":["manage_content"]}`
500	`{id}` que não é UUID, ou falha ao gravar.	`{"error":"failed to answer","detail":"..."}`

Veja também

Perguntas de produto

API atual/Referência completa/Perguntas de produto

Perguntas de produto

Lista a fila de perguntas públicas sobre produtos e responde, rejeita ou arquiva cada uma.

Todas exigem o privilégio manage_content. Mais de uma pessoa pode estar moderando ao mesmo tempo, então confira o status antes de agir.

Listar perguntas

GET/api/v1/admin/product-questionsAdmin

Listar perguntas, mais novas primeiro

Devolve 50 perguntas por página, da mais nova para a mais antiga, com o nome do produto e os dados de quem perguntou. O tamanho da página não é configurável por esta rota.

Parâmetros de consulta

statusstring

pendingansweredrejectedarchived

Filtra por status. Vazio traz todos. Um valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página. Valor inválido ou menor que 1 vale 1.

bash

curl "$BASE_URL/api/v1/admin/product-questions?status=pending" \
  -H "Authorization: Bearer $TOKEN"

200Perguntas

json

{
  "questions": [
    {
      "id": "8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_name": "Notebook Vintage Vermelho",
      "guest_name": "Maria",
      "guest_email": "maria.souza@example.com",
      "question_text": "Esse caderno tem folhas pautadas?",
      "status": "pending",
      "ai_draft": "Sim, o caderno tem folhas pautadas.",
      "ai_draft_shown": false,
      "created_at": "2026-10-11T14:22:05Z"
    }
  ]
}

Campos da resposta

questions[].iduuid

Id da pergunta.

questions[].product_iduuid

Produto da pergunta.

questions[].product_namestring

Nome do produto.

questions[].user_iduuid

Cliente logado que perguntou. Ausente para visitantes.

questions[].guest_namestring

Nome informado por visitante. Ausente quando não há.

questions[].guest_emailstring

E-mail do visitante. Nunca é exposto ao público; só a moderação o vê.

questions[].question_textstring

Texto da pergunta, de 5 a 500 caracteres.

questions[].statusstring

pendingansweredrejectedarchived

Situação.

questions[].ai_draftstring

Rascunho de resposta gerado automaticamente, para a equipe usar de base. Ausente quando não existe.

questions[].ai_draft_shownboolean

Se o rascunho está visível ao público como resposta provisória.

questions[].answer_textstring

Resposta oficial. Ausente antes de responder.

questions[].answered_bystring

Quem respondeu: admin ou o id do seller.

questions[].answered_atstring

Quando foi respondida, RFC 3339.

questions[].created_atstring

Quando foi feita, RFC 3339, UTC.

Responder

PUT/api/v1/admin/product-questions/{id}/answerAdmin

Publicar a resposta de uma pergunta

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

Corpo da requisição

answer_textstringobrigatório

Texto da resposta. Espaços nas pontas são removidos; vazio é recusado.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/answer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answer_text":"Sim, o caderno tem 96 folhas pautadas."}'

200Pergunta respondida

A resposta é a pergunta completa, no formato da lista, agora com status: "answered", answer_text, answered_by: "admin" e answered_at.

Rejeitar

PUT/api/v1/admin/product-questions/{id}/rejectAdmin

Rejeitar uma pergunta como spam ou ofensa

Marca a pergunta como rejected, o que a tira da página pública. Sem corpo. A rota não confere se a pergunta existe nem em que estado estava: rejeita mesmo uma pergunta já respondida.

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/reject" \
  -H "Authorization: Bearer $TOKEN"

200Pergunta rejeitada

json

{ "rejected": true }

Arquivar

PUT/api/v1/admin/product-questions/{id}/archiveAdmin

Arquivar uma pergunta

Marca a pergunta como archived, escondendo-a da página do produto sem apagá-la. Uma pergunta arquivada pode ser respondida depois. Sem corpo. Também não confere se a pergunta existe.

Parâmetros de caminho

iduuidobrigatório

Id da pergunta.

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-questions/8b3e6f10-52c9-4d7a-a1e4-0f9c2d7b5a63/archive" \
  -H "Authorization: Bearer $TOKEN"

200Pergunta arquivada

json

{ "archived": true }

Erros

Status	Quando	Corpo de exemplo
400	`answer` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`answer` com `answer_text` vazio.	`{"error":"answer required"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_content`.	`{"error":"insufficient privileges","privilege_required_any":["manage_content"]}`
500	`{id}` que não é UUID, ou falha ao gravar.	`{"error":"failed to answer","detail":"..."}`

Veja também