Comentários

Os comentários são as avaliações que os compradores deixam nos produtos da loja, com nota de 1 a 5 e texto livre. Eles suportam respostas (comentários filhos), formando threads de discussão em cada produto. O comprador gerencia os próprios comentários, enquanto o lojista acompanha e modera tudo pelo painel administrativo.

Todas as requisições devem incluir o header X-Shop-Id (UUID) e, por serem protegidas, o header Authorization: Bearer {token}.

---

Endpoints do Comprador

Endpoints para o comprador criar, editar e acompanhar avaliações de produtos.

Listar Comentários

Retorna uma lista paginada dos comentários da loja, com as respostas aninhadas em cada avaliação.

GET /v1/shop/customer/product-comments

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (mín. 1).
perPage	number	Não	Itens por página (máx. 100).
shopProductId	number	Não	Filtra por produto.
orderBy	enum	Não	id, rate ou createdAt.
orderDirection	enum	Não	asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/product-comments?page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo os comentários, com respostas em children.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "1",
      "parentId": null,
      "shopCustomerId": "2",
      "rate": 3,
      "comment": "Produto de boa qualidade, recomendo.",
      "createdAt": "2026-07-01T21:53:09.428+00:00",
      "updatedAt": "2026-07-01T21:53:09.428+00:00",
      "shopCustomer": {
        "id": "2",
        "firstName": "Maria",
        "lastName": "Silva"
      },
      "children": [
        {
          "id": "2",
          "parentId": "1",
          "shopCustomerId": "2",
          "rate": 4,
          "comment": "Concordo, a entrega também foi rápida.",
          "shopCustomer": {
            "id": "2",
            "firstName": "Maria",
            "lastName": "Silva"
          }
        }
      ]
    }
  ]
}

Criar Comentário

Publica uma nova avaliação em um produto. Para responder a um comentário existente, informe o parentId.

POST /v1/shop/customer/product-comments

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
shopProductId	number	Sim	ID do produto avaliado.
rate	number	Sim	Nota inteira de 1 a 5.
comment	string	Sim	Texto da avaliação (máx. 1000 caracteres).
parentId	number	Não	ID do comentário pai, para respostas (deve ser do mesmo produto). Pode ser null.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/shop/customer/product-comments" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "shopProductId": 2,
    "rate": 5,
    "comment": "Produto de boa qualidade, recomendo.",
    "parentId": null
  }'

Respostas

201 Created

Retorna o ID do comentário criado.

{
  "id": "1"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "Avaliação deve estar entre 1 e 5",
      "rule": "range",
      "field": "rate"
    }
  ]
}

Obter Comentário

Recupera os detalhes de um comentário, incluindo o comentário pai e as respostas.

GET /v1/shop/customer/product-comments/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	ID do comentário.

Respostas

200 OK

Retorna os dados do comentário, com parent e children.

{
  "id": "2",
  "parentId": "1",
  "shopCustomerId": "2",
  "rate": 4,
  "comment": "Concordo, a entrega também foi rápida.",
  "createdAt": "2026-07-01T21:53:55.569+00:00",
  "updatedAt": "2026-07-01T21:53:55.569+00:00",
  "shopCustomer": {
    "id": "2",
    "firstName": "Maria",
    "lastName": "Silva"
  },
  "children": [],
  "parent": {
    "id": "1",
    "shopCustomerId": "2",
    "rate": 3,
    "comment": "Produto de boa qualidade, recomendo.",
    "shopCustomer": {
      "id": "2",
      "firstName": "Maria",
      "lastName": "Silva"
    }
  }
}

404 Not Found

Ocorre quando o comentário não existe na loja.

Atualizar Comentário

Atualiza a nota e o texto de um comentário do comprador autenticado.

PUT /v1/shop/customer/product-comments/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
rate	number	Sim	Nota inteira de 1 a 5.
comment	string	Sim	Texto da avaliação (máx. 1000 caracteres).

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/shop/customer/product-comments/2" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 4,
    "comment": "Depois de mais um tempo de uso, continuo satisfeita."
  }'

Respostas

204 No Content

Comentário atualizado com sucesso.

Remover Comentário

Exclui um comentário do comprador autenticado.

DELETE /v1/shop/customer/product-comments/:id

Respostas

204 No Content

Remoção concluída com sucesso.

---

Endpoints Administrativos

Endpoints protegidos para o lojista acompanhar e moderar as avaliações dos produtos.

Listar Comentários

Retorna uma lista paginada de todos os comentários da loja, com filtros por cliente e produto.

GET /v1/shop/user/product-comments

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (mín. 1).
perPage	number	Não	Itens por página (máx. 100).
search	string	Não	Busca por termo no comentário (máx. 150 caracteres).
shopCustomerId	number	Não	Filtra por cliente.
shopProductId	number	Não	Filtra por produto.
orderBy	enum	Não	id, rate ou createdAt.
orderDirection	enum	Não	asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/product-comments?shopProductId=2" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo os comentários, com respostas em children.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "1",
      "parentId": null,
      "shopCustomerId": "2",
      "rate": 3,
      "comment": "Produto de boa qualidade, recomendo.",
      "createdAt": "2026-07-01T21:53:09.428+00:00",
      "updatedAt": "2026-07-01T21:53:09.428+00:00",
      "shopCustomer": {
        "id": "2",
        "firstName": "Maria",
        "lastName": "Silva"
      },
      "children": [
        {
          "id": "2",
          "parentId": "1",
          "shopCustomerId": "2",
          "rate": 4,
          "comment": "Concordo, a entrega também foi rápida.",
          "shopCustomer": {
            "id": "2",
            "firstName": "Maria",
            "lastName": "Silva"
          }
        }
      ]
    }
  ]
}

Obter Comentário

Recupera os detalhes de um comentário, incluindo o comentário pai e as respostas.

GET /v1/shop/user/product-comments/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	ID do comentário.

Respostas

200 OK

Retorna os dados do comentário, com parent e children.

404 Not Found

Ocorre quando o comentário não existe na loja.

Remover Comentário

Exclui um comentário da loja (moderação).

DELETE /v1/shop/user/product-comments/:id

Respostas

204 No Content

Remoção concluída com sucesso.