Documentação API

API atual API legada

Guia rápido Referência completa

API legada/Referência completa

Avaliações e comentários

A API de Discussions gerencia as avaliações e os comentários que os clientes deixam nos produtos da sua loja.

Uma discussion (discussão) é tudo o que um cliente escreve sobre um objeto da loja. O caso mais comum é uma avaliação (nota mais texto) ou um comentário (uma dúvida ou uma resposta) em um produto. A API de Discussions permite que um administrador leia, crie, altere e remova essas entradas, por exemplo para moderar o que os clientes publicam.

Toda chamada usa as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL). Os endpoints aparecem abaixo como $BASE_URL/api/2.0/discussions, a forma da API 2.0 que a referência usa nesta seção.

Como funciona

A visão geral desta seção na referência avisa que a documentação de Discussions ainda estava sendo escrita e lista o que ela pretende cobrir. As outras páginas desta seção documentam o que a referência descreve hoje.

Um cliente publica uma entrada
O cliente escreve uma avaliação ou um comentário em um produto. A entrada tem um status, A (ativa) ou D (desativada).
Você lê as entradas
Liste todas as discussões, ou só as de um produto, e reduza o resultado com os filtros de Paginação e filtros.
Você modera
Mude o status de uma entrada com um PUT, ou remova-a com um DELETE.

A visão geral lista estas capacidades previstas: obter discussões por produto, criar novas discussões e comentários, moderar o conteúdo gerado por usuários, gerenciar notas e avaliações e configurar notificações de nova atividade.

Códigos de status

Código	Significado
`A`	Ativa
`D`	Desativada (aparece como "reprovada" no exemplo de atualização)

Conceitos principais

Avaliações e comentários

Tipo	Descrição
`review`	Uma avaliação de produto, que inclui uma nota e normalmente um comentário detalhado
`comment`	Um comentário ou dúvida geral sobre um produto, ou a resposta a outro comentário ou avaliação

Para responder a uma entrada existente, preencha reply_to com o id da entrada pai. A página de filtros escreve o filtro de tipo com uma letra: C para comentários, R para avaliações e B para os dois.

O objeto a que a discussão pertence

Na página de filtros, object_type aceita P (produto), C (categoria), A (página), O (pedido) ou E (página inicial), e object_id é o id desse objeto. Para criar uma entrada você precisa de object_type mais object_id, ou do thread_id de uma discussão existente.

Ids

O id de uma entrada é um número inteiro. Os exemplos de criação e atualização o devolvem como post_id, e os exemplos o usam no caminho como /api/2.0/discussions/{id}.

Endpoints

Método	Caminho	Finalidade	Autenticação
GET	`/api/2.0/discussions`	Listar todas as avaliações e comentários	Administrador
POST	`/api/2.0/discussions`	Criar uma avaliação ou comentário	Administrador
GET	`/api/2.0/discussions/{id}`	Obter uma discussão	Administrador
PUT	`/api/2.0/discussions/{id}`	Atualizar uma discussão	Administrador
DELETE	`/api/2.0/discussions/{id}`	Excluir uma discussão	Administrador
POST	`/api/2.0/products/{p_id}/discussions`	Criar uma discussão para um produto	Administrador
DELETE	`/api/2.0/products/{p_id}/discussions/{id}`	Excluir uma discussão de um produto	Administrador
GET	`/api/2.0/products/{p_id}/discussions`	Listar as discussões de um produto	Administrador
GET	`/api/2.0/products/{p_id}/discussions/{id}`	Obter uma discussão de um produto	Administrador
PUT	`/api/2.0/products/{p_id}/discussions/{id}`	Atualizar uma discussão de um produto	Administrador

Erros comuns

Criar uma entrada sem dizer a que ela pertence. Envie object_type e object_id, ou thread_id.
Excluir uma avaliação para escondê-la. A exclusão é permanente e remove também todos os comentários ligados à avaliação. Mude o status para D.
Listar tudo sem definir o tamanho da página. A lista devolve páginas de 10 por padrão, então peça items_per_page e percorra page.
Misturar os dois conjuntos de letras do filtro de tipo. A página de filtros usa C, R e B, enquanto a página de endpoints menciona review e comment. Teste na sua loja o que você precisa usar.
Enviar o status como palavra. Os valores de status são as letras A e D.

Próximos passos

Todas as URLs e métodos da seção.

Paginação e filtros

Pagine, ordene e filtre avaliações e comentários.

Uma requisição e uma resposta para cada operação.