Entrar
.md

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 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