API atual/Referência completa/Avaliações e perguntas

Perguntas do produto

Lista as perguntas respondidas de um produto e permite enviar uma nova pergunta.

A seção "Perguntas e respostas" da página do produto. A leitura mostra as perguntas que já têm resposta; o envio deixa o visitante ou cliente perguntar. A pergunta entra como pendente e só aparece na lista depois de respondida pelo lojista ou pela loja, ou imediatamente se a loja exibe a resposta automática provisória. Dependendo da configuração da loja, a resposta ao enviar pode trazer um rascunho automático provisório.

O módulo de perguntas precisa estar ligado. A leitura pode ser guardada em cache por 5 minutos.

Listar perguntas

GET/api/v1/storefront/products/{id}/questionsPública

Lista as perguntas respondidas de um produto

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/questions"

Resposta

200Perguntas retornadas

json

{
  "questions": [
    {
      "id": "5d1e9a30-7b2c-4f18-b6a4-0e3c8d2f7a19",
      "question_text": "A caneca pode ir ao micro-ondas?",
      "answer_text": "Sim, a caneca esmaltada pode ir ao micro-ondas por até 2 minutos.",
      "answered_by": "vendor",
      "is_ai_provisional": false,
      "asker_name": "Carlos",
      "created_at": "2026-10-05T18:02:44Z",
      "answered_at": "2026-10-06T09:15:00Z"
    }
  ],
  "total": 1
}

Produto sem perguntas (resposta real da loja de teste):

200Sem perguntas

json

{"questions":[],"total":0}

Campos da resposta

questionsarray

Perguntas visíveis ao público. O e-mail de quem perguntou nunca é exposto.

questions[].iduuid

Id da pergunta.

questions[].question_textstring

Texto da pergunta.

questions[].answer_textstring

Resposta. Ausente se ainda não houver.

questions[].answered_bystring

Quem respondeu (por exemplo, o lojista ou a administração).

questions[].is_ai_provisionalboolean

true quando a resposta é um rascunho automático ainda não revisado por uma pessoa. Mostre um aviso de "resposta provisória".

questions[].asker_namestring

Nome informado por quem perguntou. Ausente se não informado.

questions[].created_atstring

Quando foi perguntado, RFC 3339 em UTC.

questions[].answered_atstring

Quando foi respondido. Ausente sem resposta.

totalinteger

Quantidade de perguntas na lista.

Erros

Status	Quando	Corpo de exemplo
403	O módulo de perguntas está desligado.	`{"error":"module_disabled","module":"product-qa"}`
500	O id não é um UUID válido.	`{"error":"failed to list questions","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Enviar uma pergunta

POST/api/v1/storefront/products/{id}/questionsPública

Envia uma pergunta sobre o produto

O token é opcional. Cliente logado não precisa informar quem é; visitante precisa mandar guest.email.

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Corpo da requisição

question_textstringobrigatório

Pergunta, de 5 a 500 caracteres (contados depois de remover espaços nas pontas).

guestobject

Identificação do visitante. Obrigatório sem token.

emailstringobrigatório

E-mail válido de quem pergunta. Nunca é exibido publicamente.

namestring

Nome para exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/questions" \
  -H "Content-Type: application/json" \
  -d '{"question_text": "A caneca pode ir ao micro-ondas?", "guest": {"name": "Carlos", "email": "carlos@example.com"}}'

Resposta

201Pergunta recebida

json

{"id":"5d1e9a30-7b2c-4f18-b6a4-0e3c8d2f7a19","status":"pending","provisional_answer":null}

Campos da resposta

iduuid

Id da pergunta.

statusstring

pending

Sempre pending ao criar: a pergunta aguarda resposta.

provisional_answerstring

Rascunho de resposta automática, quando a loja liga esse recurso e o rascunho foi gerado. null caso contrário.

Erros

Status	Quando	Corpo de exemplo
400	Pergunta com menos de 5 ou mais de 500 caracteres.	`{"error":"question must be 5-500 characters"}`
400	Visitante sem `guest.email` válido.	`{"error":"email required"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
429	Limite diário de perguntas por pessoa e produto atingido (padrão 5).	`{"error":"too many questions today"}`
403	O módulo de perguntas está desligado.	`{"error":"module_disabled","module":"product-qa"}`

Veja também

API atual/Referência completa/Avaliações e perguntas

Perguntas do produto

Lista as perguntas respondidas de um produto e permite enviar uma nova pergunta.

O módulo de perguntas precisa estar ligado. A leitura pode ser guardada em cache por 5 minutos.

Listar perguntas

GET/api/v1/storefront/products/{id}/questionsPública

Lista as perguntas respondidas de um produto

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/questions"

Resposta

200Perguntas retornadas

json

{
  "questions": [
    {
      "id": "5d1e9a30-7b2c-4f18-b6a4-0e3c8d2f7a19",
      "question_text": "A caneca pode ir ao micro-ondas?",
      "answer_text": "Sim, a caneca esmaltada pode ir ao micro-ondas por até 2 minutos.",
      "answered_by": "vendor",
      "is_ai_provisional": false,
      "asker_name": "Carlos",
      "created_at": "2026-10-05T18:02:44Z",
      "answered_at": "2026-10-06T09:15:00Z"
    }
  ],
  "total": 1
}

Produto sem perguntas (resposta real da loja de teste):

200Sem perguntas

json

{"questions":[],"total":0}

Campos da resposta

questionsarray

Perguntas visíveis ao público. O e-mail de quem perguntou nunca é exposto.

questions[].iduuid

Id da pergunta.

questions[].question_textstring

Texto da pergunta.

questions[].answer_textstring

Resposta. Ausente se ainda não houver.

questions[].answered_bystring

Quem respondeu (por exemplo, o lojista ou a administração).

questions[].is_ai_provisionalboolean

true quando a resposta é um rascunho automático ainda não revisado por uma pessoa. Mostre um aviso de "resposta provisória".

questions[].asker_namestring

Nome informado por quem perguntou. Ausente se não informado.

questions[].created_atstring

Quando foi perguntado, RFC 3339 em UTC.

questions[].answered_atstring

Quando foi respondido. Ausente sem resposta.

totalinteger

Quantidade de perguntas na lista.

Erros

Status	Quando	Corpo de exemplo
403	O módulo de perguntas está desligado.	`{"error":"module_disabled","module":"product-qa"}`
500	O id não é um UUID válido.	`{"error":"failed to list questions","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Enviar uma pergunta

POST/api/v1/storefront/products/{id}/questionsPública

Envia uma pergunta sobre o produto

O token é opcional. Cliente logado não precisa informar quem é; visitante precisa mandar guest.email.

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Corpo da requisição

question_textstringobrigatório

Pergunta, de 5 a 500 caracteres (contados depois de remover espaços nas pontas).

guestobject

Identificação do visitante. Obrigatório sem token.

emailstringobrigatório

E-mail válido de quem pergunta. Nunca é exibido publicamente.

namestring

Nome para exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/questions" \
  -H "Content-Type: application/json" \
  -d '{"question_text": "A caneca pode ir ao micro-ondas?", "guest": {"name": "Carlos", "email": "carlos@example.com"}}'

Resposta

201Pergunta recebida

json

{"id":"5d1e9a30-7b2c-4f18-b6a4-0e3c8d2f7a19","status":"pending","provisional_answer":null}

Campos da resposta

iduuid

Id da pergunta.

statusstring

pending

Sempre pending ao criar: a pergunta aguarda resposta.

provisional_answerstring

Rascunho de resposta automática, quando a loja liga esse recurso e o rascunho foi gerado. null caso contrário.

Erros

Status	Quando	Corpo de exemplo
400	Pergunta com menos de 5 ou mais de 500 caracteres.	`{"error":"question must be 5-500 characters"}`
400	Visitante sem `guest.email` válido.	`{"error":"email required"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
429	Limite diário de perguntas por pessoa e produto atingido (padrão 5).	`{"error":"too many questions today"}`
403	O módulo de perguntas está desligado.	`{"error":"module_disabled","module":"product-qa"}`