---
title: 'Feedback (CSAT / NPS)'
description: 'Registra una evaluación de satisfacción por pedido — CSAT (1..5) o NPS (0..10) — y consúltalas para reportes.'
---

# Feedback (CSAT / NPS)

Los endpoints de feedback de Guper permiten registrar **una evaluación por pedido**, en cualquiera de las dos escalas estándar del mercado:

- **CSAT** — *Customer Satisfaction*. El cliente da una nota de **1 a 5**, generalmente respondiendo *“¿Qué tan satisfecho estuviste con este pedido?”*. El reporte es el promedio de las notas, o el porcentaje de `4..5` (satisfechos).
- **NPS** — *Net Promoter Score*. El cliente da una nota de **0 a 10**, generalmente respondiendo *“¿Qué tan probable es que nos recomiendes a un amigo?”*. El reporte divide a los encuestados en **detractores** (`0..6`), **neutros** (`7..8`) y **promotores** (`9..10`); el score es `% promotores − % detractores`.

Eliges la escala por evaluación en el campo obligatorio `type` — el **mismo endpoint** maneja las dos, y la misma organización puede usar ambas en flujos distintos (ej: CSAT después del soporte, NPS después de la entrega).

## Referencia rápida

| | CSAT | NPS |
|---|---|---|
| `type` | `"csat"` | `"nps"` |
| `rating` permitido | `1..5` | `0..10` |
| Pregunta típica | *¿Qué tan satisfecho?* | *¿Recomendarías a un amigo?* |
| Cortes comunes | `4..5` = satisfecho | `9..10` = promotor · `0..6` = detractor |
| Fórmula del score | `avg(rating)` | `(%9..10) − (%0..6)` |

## Flujo completo

```
┌────────────────────┐     ┌──────────────────────┐     ┌────────────────────┐
│ 1. (Opcional)      │     │ 2. Cliente responde  │     │ 3. Lectura         │
│    Crea una        │ →   │    → POST review     │ →   │    /review/byOrder │
│    categoría       │     │    (csat O nps)      │     │    o list filtrada │
└────────────────────┘     └──────────────────────┘     └────────────────────┘
```

### Paso 1 — (Opcional) Define categorías

Las categorías son una taxonomía opcional que agrupa evaluaciones por lo que quieres medir (ej: `delivery`, `producto`, `atención`). La mayoría de las organizaciones empieza sin ninguna categoría — toda evaluación queda sin categoría (`categoryId: null`). Adopta un catálogo cuando necesites segmentar reportes por tópico.

```bash
POST /api/register/feedback/category
{
    "slug":        "delivery",
    "name":        "Entrega",
    "description": "Evalúa la experiencia de entrega."
}
```

`slug` es único por organización. Usa algo corto, estable y en snake_case — generalmente no cambia una vez que los dashboards dependen de él.

### Paso 2 — Registra la evaluación

```bash
POST /api/register/feedback/review
{
    "personId":   12345,
    "orderId":    "ORD-789",
    "type":       "csat",       /* o "nps" */
    "rating":     5,             /* debe caber en el rango del type */
    "comment":    "Llegó antes del plazo, perfectamente empaquetado.",
    "categoryId": 1,             /* opcional */
    "source":     "journey"      /* opcional; default = "journey" */
}
```

Campos obligatorios: `personId`, `orderId`, `type`, `rating`, `comment`. El schema garantiza **una evaluación por `(organization, orderId)`** — un segundo `POST` para el mismo pedido es rechazado con `409 Conflict`. Usa `PUT /review/{id}` para modificarla.

### Paso 3 — Léela de vuelta

Dos patrones de lectura son útiles en el día a día:

```bash
# ¿Este pedido ya fue evaluado?
GET /api/register/feedback/review/byOrder/ORD-789
# 200 — la evaluación existe
# 404 — todavía no; es la señal para enviar la invitación al cliente
```

```bash
# Buscar promotores de la última campaña
GET /api/register/feedback/review?q[type][]=nps&q[rating][GTE]=9
```

El listado acepta la gramática `q[col][OP]=valor` — ver [List query parameters](/docs/{lang}/guides/list-query-parameters).

## Editando una evaluación

`PUT /api/register/feedback/review/{id}` aplica patch solo a los campos enviados. Dos reglas no obvias cuando el `type` cambia:

- **csat → nps** siempre es seguro: el `rating` viejo (1..5) sigue cabiendo en el nuevo rango (0..10), pero puedes sobrescribirlo con una nota mayor.
- **nps → csat** solo es seguro cuando el rating existente es `1..5`. Si el NPS actual es `6..10`, debes enviar un nuevo rating en 1..5 en el mismo PUT — caso contrario la solicitud devuelve `400`.

## Reglas de validación

| Regla | Status |
|---|---|
| Falta `type`, `personId`, `orderId`, `rating` o `comment` | `400 Bad Request` |
| `type` distinto a `csat` o `nps` | `400 Bad Request` |
| `rating` fuera del rango para el `type` elegido (csat: 1..5 · nps: 0..10) | `400 Bad Request` |
| `comment` vacío o solo con espacios | `400 Bad Request` |
| `categoryId` no pertenece a esta organización | `400 Bad Request` |
| Ya existe una evaluación para `(organization, orderId)` | `409 Conflict` |

## Cuándo usar CSAT o NPS

No hay una respuesta "correcta" — las escalas responden preguntas distintas:

- Usa **CSAT** cuando quieres medir una transacción específica (*“¿La entrega estuvo bien?”*). La escala 1..5 es rápida de responder y fácil de explicar.
- Usa **NPS** cuando quieres una señal de lealtad (*“¿Nos recomendarías?”*). La escala 0..10 separa fans activos de clientes solo satisfechos.

Muchos programas combinan ambos: un CSAT rápido justo después del pedido, un pulso de NPS una semana después. Como cada evaluación lleva su propio `type`, puedes manejar los dos flujos por el mismo endpoint y separarlos al leer.

## Ver también

- [Referencia de la API de Feedback](/docs/{lang}/api-reference/register/feedback) — todos los endpoints, schemas completos, códigos de error
- [Autenticación](/docs/{lang}/guides/authentication) — el token `x-guper-authorization`
- [List query parameters](/docs/{lang}/guides/list-query-parameters) — armando URLs de listado filtrado
