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.
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
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:
# 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
# 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.
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
ratingantigo (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 retorna400.
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 — todos os endpoints, schemas completos, códigos de erro
- Autenticação — o token
x-guper-authorization - List query parameters — montando URLs de listagem filtrada