---
title: 'Feedback (CSAT / NPS)'
description: 'Registre uma avaliação de satisfação por pedido — CSAT (1..5) ou NPS (0..10) — e consulte-as para relatórios.'
---

# Feedback (CSAT / NPS)

Os endpoints de feedback do Guper permitem registrar **uma avaliação por pedido**, em qualquer uma das duas escalas padrão de mercado:

- **CSAT** — *Customer Satisfaction*. O cliente dá uma nota de **1 a 5**, normalmente respondendo *“Qual seu nível de satisfação com este pedido?”*. O relatório é a média das notas, ou a fatia de `4..5` (satisfeitos).
- **NPS** — *Net Promoter Score*. O cliente dá uma nota de **0 a 10**, normalmente respondendo *“Qual a chance de você nos recomendar para um amigo?”*. O relatório divide os respondentes em **detratores** (`0..6`), **neutros** (`7..8`) e **promotores** (`9..10`); o score é `% promotores − % detratores`.

Você escolhe a escala por avaliação no campo obrigatório `type` — o **mesmo endpoint** trata as duas, e a mesma organização pode usar as duas em fluxos diferentes (ex: CSAT depois do suporte, NPS depois da entrega).

## Referência rápida

| | CSAT | NPS |
|---|---|---|
| `type` | `"csat"` | `"nps"` |
| `rating` permitido | `1..5` | `0..10` |
| Pergunta típica | *Qual sua satisfação?* | *Recomendaria a um amigo?* |
| Cortes comuns | `4..5` = satisfeito | `9..10` = promotor · `0..6` = detrator |
| Fórmula do score | `avg(rating)` | `(%9..10) − (%0..6)` |

## Fluxo completo

```
┌────────────────────┐     ┌──────────────────────┐     ┌────────────────────┐
│ 1. (Opcional)      │     │ 2. Cliente responde  │     │ 3. Leitura         │
│    Crie uma        │ →   │    → POST review     │ →   │    /review/byOrder │
│    categoria       │     │    (csat OU nps)     │     │    ou list filtrada│
└────────────────────┘     └──────────────────────┘     └────────────────────┘
```

### Passo 1 — (Opcional) Defina categorias

Categorias são uma taxonomia opcional que agrupa avaliações pelo que você quer medir (ex: `delivery`, `produto`, `atendimento`). A maioria das organizações começa sem nenhuma categoria — toda avaliação fica sem categoria (`categoryId: null`). Adote um catálogo quando precisar fatiar os relatórios por tópico.

```bash
POST /api/register/feedback/category
{
    "slug":        "delivery",
    "name":        "Entrega",
    "description": "Avalia a experiência de entrega."
}
```

`slug` é único por organização. Use algo curto, estável e em snake_case — ele tipicamente não muda depois que dashboards passam a depender dele.

### Passo 2 — Registre a avaliação

```bash
POST /api/register/feedback/review
{
    "personId":   12345,
    "orderId":    "ORD-789",
    "type":       "csat",       /* ou "nps" */
    "rating":     5,             /* precisa caber no range do type */
    "comment":    "Chegou antes do prazo, embalado perfeitamente.",
    "categoryId": 1,             /* opcional */
    "source":     "journey"      /* opcional; default = "journey" */
}
```

Campos obrigatórios: `personId`, `orderId`, `type`, `rating`, `comment`. O schema garante **uma avaliação por `(organization, orderId)`** — um segundo `POST` para o mesmo pedido é rejeitado com `409 Conflict`. Use `PUT /review/{id}` para alterar.

### Passo 3 — Leia de volta

Dois padrões de leitura são úteis no dia a dia:

```bash
# Este pedido já foi avaliado?
GET /api/register/feedback/review/byOrder/ORD-789
# 200 — a avaliação existe
# 404 — ainda não tem; é a deixa para enviar o convite ao cliente
```

```bash
# Buscar promotores da última campanha
GET /api/register/feedback/review?q[type][]=nps&q[rating][GTE]=9
```

A listagem aceita a gramática `q[col][OP]=valor` — veja [List query parameters](/docs/{lang}/guides/list-query-parameters).

## Editando uma avaliação

`PUT /api/register/feedback/review/{id}` aplica patch só nos campos enviados. Duas regras não-óbvias quando o `type` muda:

- **csat → nps** é sempre seguro: o `rating` antigo (1..5) ainda cabe no novo range (0..10), mas você pode sobrescrever com uma nota maior.
- **nps → csat** só é seguro quando o rating existente é `1..5`. Se o NPS atual é `6..10`, você precisa enviar um novo rating em 1..5 no mesmo PUT — caso contrário a requisição retorna `400`.

## Regras de validação

| Regra | Status |
|---|---|
| Falta `type`, `personId`, `orderId`, `rating` ou `comment` | `400 Bad Request` |
| `type` diferente de `csat` ou `nps` | `400 Bad Request` |
| `rating` fora do range para o `type` escolhido (csat: 1..5 · nps: 0..10) | `400 Bad Request` |
| `comment` vazio ou só com espaços | `400 Bad Request` |
| `categoryId` não pertence a esta organização | `400 Bad Request` |
| Já existe uma avaliação para `(organization, orderId)` | `409 Conflict` |

## Quando usar CSAT ou NPS

Não há uma resposta "certa" — as escalas respondem perguntas diferentes:

- Use **CSAT** quando quer medir uma transação específica (*“A entrega foi boa?”*). A escala 1..5 é rápida de responder e fácil de explicar.
- Use **NPS** quando quer um sinal de lealdade (*“Você nos recomendaria?”*). A escala 0..10 separa fãs ativos de clientes apenas satisfeitos.

Muitos programas misturam os dois: um CSAT rápido logo depois do pedido, um pulso de NPS uma semana depois. Como cada avaliação carrega seu próprio `type`, você pode tocar os dois fluxos pelo mesmo endpoint e separá-los na leitura.

## Veja também

- [Referência da API de Feedback](/docs/{lang}/api-reference/register/feedback) — todos os endpoints, schemas completos, códigos de erro
- [Autenticação](/docs/{lang}/guides/authentication) — o token `x-guper-authorization`
- [List query parameters](/docs/{lang}/guides/list-query-parameters) — montando URLs de listagem filtrada
