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.
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
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:
# ¿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
# 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.
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
ratingviejo (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 es6..10, debes enviar un nuevo rating en 1..5 en el mismo PUT — caso contrario la solicitud devuelve400.
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 — todos los endpoints, schemas completos, códigos de error
- Autenticación — el token
x-guper-authorization - List query parameters — armando URLs de listado filtrado