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

Resposta

200Perguntas retornadas

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

200Sem perguntas

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

Resposta

201Pergunta recebida

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

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

Resposta

200Perguntas retornadas

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

200Sem perguntas

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

Resposta

201Pergunta recebida

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