Entrar
.md

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