> For the complete documentation index, see [llms.txt](https://ereemby.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ereemby.gitbook.io/docs/sistema-de-temas/funcoes/feedbacks.md).

# Feedbacks

Carregue feedbacks aprovados da loja com paginação, filtros e ordenação.

Use a função `getFeedbacksPaginationRequest` para buscar os feedbacks **aprovados** da loja, com paginação de **25 itens por página**, filtro por estrelas, ordenação e opção de retornar só os que têm comentário.

Ela já monta a URL, faz o `fetch` e devolve o JSON pronto no formato `{ data, pagination }`. Quando algo falha, retorna `null`.

### getFeedbacksPaginationRequest

Chame a função para carregar uma página de feedbacks. Sem parâmetros, ela retorna a página `1` com os feedbacks mais recentes.

```js
getFeedbacksPaginationRequest({
    page: number,
    star: number,    // 1 a 5, ou 'all'
    order: string,   // 'recent' | 'old' | 'all'
    comment: boolean // true = só feedbacks com comentário
})
```

#### Exemplo pré-preenchido

```js
const feedbacks = await getFeedbacksPaginationRequest({
    page: 2,
    order: 'recent'
})
```

#### Exemplo com filtros

```js
const feedbacks = await getFeedbacksPaginationRequest({
    page: 1,
    star: 5,
    order: 'old',
    comment: true
})
```

### Parâmetros

| Campo     | Tipo                 | Descrição                                                                                                       |
| --------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `page`    | `number`             | Página desejada. O padrão é `1`. Use inteiro positivo.                                                          |
| `star`    | `number` ou `string` | Filtra por nota de `1` a `5`. Use `'all'` ou omita para trazer todas.                                           |
| `order`   | `string`             | Ordenação por data. Use `recent` para mais novos e `old` para mais antigos. Use `'all'` ou omita para o padrão. |
| `comment` | `boolean`            | Quando `true`, retorna só feedbacks com texto. Remove os que têm apenas nota.                                   |

{% hint style="info" %}
A loja é resolvida automaticamente pelo contexto do tema. O retorno já vem filtrado por loja e por feedbacks aprovados.
{% endhint %}

Não é possível usar essa função para buscar feedbacks de outra loja ou feedbacks não aprovados.

### Resposta

A função devolve o JSON já parseado, ou `null` quando a requisição falha. Sempre valide o retorno antes de usar.

```js
const feedbacks = await getFeedbacksPaginationRequest({
    page: 1,
    comment: true
})

if (!feedbacks) {
    return
}

console.log(feedbacks.data)
console.log(feedbacks.pagination)
```

#### Exemplo de retorno

```json
{
  "data": [
    {
      "id": 123,
      "star": 5,
      "comment": "Produto excelente, entrega rápida",
      "tags": ["entrega-rapida", "qualidade"],
      "is_anonymous": false,
      "created_at": "2026-06-20T14:30:00.000Z",
      "user": {
        "icon": "https://.../avatar.png",
        "name": "João Silva"
      },
      "product": {
        "name": "Camiseta Preta",
        "image": "https://.../produto.png",
        "price": 79.9,
        "comparison": 99.9,
        "id": "456"
      },
      "product_id": "456"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 138,
    "totalPages": 6
  }
}
```

### Campos da resposta

| Campo                       | Tipo               | Descrição                                                          |
| --------------------------- | ------------------ | ------------------------------------------------------------------ |
| `data`                      | `array`            | Lista com até `25` feedbacks da página atual.                      |
| `data[].id`                 | `number`           | ID do feedback.                                                    |
| `data[].star`               | `number`           | Nota de `1` a `5`.                                                 |
| `data[].comment`            | `string` ou `null` | Texto do feedback. Vem `null` quando o cliente só enviou estrelas. |
| `data[].tags`               | `array`            | Lista de tags. Vem `[]` quando não há tags.                        |
| `data[].is_anonymous`       | `boolean`          | Indica se o cliente avaliou anonimamente.                          |
| `data[].created_at`         | `string`           | Data de criação em formato ISO 8601.                               |
| `data[].user`               | `object` ou `null` | Dados do usuário. Vem `null` quando o feedback é anônimo.          |
| `data[].user.icon`          | `string`           | URL do avatar do usuário.                                          |
| `data[].user.name`          | `string`           | Nome do usuário.                                                   |
| `data[].product`            | `object`           | Produto ou variante avaliado.                                      |
| `data[].product.name`       | `string`           | Nome do produto.                                                   |
| `data[].product.image`      | `string`           | URL da imagem do produto.                                          |
| `data[].product.price`      | `number`           | Preço atual do produto.                                            |
| `data[].product.comparison` | `number`           | Preço de comparação. Exibe o valor “de”.                           |
| `data[].product.id`         | `string`           | ID do produto dentro do objeto `product`.                          |
| `data[].product_id`         | `string`           | ID do produto. Use para montar links.                              |
| `pagination`                | `object`           | Metadados de paginação.                                            |
| `pagination.page`           | `number`           | Página atual.                                                      |
| `pagination.limit`          | `number`           | Tamanho da página usado na resposta. O máximo é `25`.              |
| `pagination.total`          | `number`           | Total de feedbacks no conjunto filtrado.                           |
| `pagination.totalPages`     | `number`           | Total de páginas disponíveis.                                      |

### Navegação entre páginas

Use `pagination.page` e `pagination.totalPages` para controlar a navegação.

* `page < totalPages` existe próxima página.
* `page > 1`  existe página anterior.
* `limit` permanece em `25`.