Manual de uso del API de Testimonios (solo lectura)

El API de testimonios expone el contenido público de cada sección. Todas las rutas viven bajo /api/testimonials y responden en JSON.

Autenticación

• Incluye Authorization: Bearer <token> en cada llamada.
• El token debe estar activo y tener permisos sobre el recurso que consultas.
• Usa Content-Type: application/json para mantener la compatibilidad con futuros cambios.

Permisos

• read: requerido para realizar peticiones GET.

Si el token está expirado, desactivado o sin el permiso read, la API responde con 401 o 403.

Códigos de respuesta comunes

• 200 OK: operación exitosa.
• 400 Bad Request: parámetros faltantes o inválidos.
• 401 / 403: token ausente, inválido o sin permisos.
• 404 Not Found: sección o testimonio inexistente para el token.
• 405 Method Not Allowed: cualquier método distinto de GET.
• 500 Internal Server Error: error interno no controlado.

Secciones de testimonios — /api/testimonials

Parámetro obligatorio

• sectionId (string): identifica la sección desde la cual leer testimonios.

Parámetros opcionales

• limit (número > 0): máximo de testimonios a devolver (1–50, por defecto 20).
• id (string): cuando se especifica, devuelve únicamente el testimonio indicado.

GET listado

Devuelve la sección solicitada y sus testimonios ordenados por fecha de creación descendente. Solo se incluyen testimonios en estado published.

Los campos devueltos para cada testimonio son:

• id, authorName, authorRole, company, headline, content, rating, photoUrl, createdAt, updatedAt.
• country: cadena tal como se guarda en el CMS (incluye el emoji de bandera seguido del nombre del país, por ejemplo 🇲🇽 México).

curl "https://cms.begraffic.com/api/testimonials?sectionId=clientes-saas&limit=10" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

{
  "sectionId": "clientes-saas",
  "items": [
    {
      "id": "ana-garcia",
      "authorName": "Ana García",
      "authorRole": "CEO en Acme",
      "company": "Acme Corp",
      "country": "🇲🇽 México",
      "headline": "Crecimos 3x con la plataforma",
      "content": "Desde que usamos la herramienta mejoramos nuestros indicadores clave.",
      "rating": 5,
      "photoUrl": "https://cdn.begraffic.com/photos/ana.jpg",
      "createdAt": "2024-04-15T10:00:00.000Z",
      "updatedAt": "2024-05-01T12:00:00.000Z"
    }
  ]
}

GET un testimonio

GET /api/testimonials?sectionId=<id>&id=<testimonialId>

curl "https://cms.begraffic.com/api/testimonials?sectionId=clientes-saas&id=ana-garcia" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

{
  "sectionId": "clientes-saas",
  "testimonial": {
    "id": "ana-garcia",
    "authorName": "Ana García",
    "authorRole": "CEO en Acme",
    "company": "Acme Corp",
    "country": "🇲🇽 México",
    "headline": "Crecimos 3x con la plataforma",
    "content": "Desde que usamos la herramienta mejoramos nuestros indicadores clave.",
    "rating": 5,
    "photoUrl": "https://cdn.begraffic.com/photos/ana.jpg",
    "createdAt": "2024-04-15T10:00:00.000Z",
    "updatedAt": "2024-05-01T12:00:00.000Z"
  }
}

Si el testimonio o la sección no existen o no están publicados, la API responde 404.

El campo country siempre devuelve el valor completo guardado (emoji + nombre del país).

Ejemplos de respuestas de error

Sección o testimonio no encontrado (404)

{
  "error": "No encontramos el testimonio solicitado."
}

Parámetro faltante (400)

{
  "error": "Debes proporcionar el parámetro sectionId."
}

Token inválido o sin permisos (401 / 403)

{
  "error": "El token no cuenta con permisos suficientes para esta acción."
}

Qué puedes hacer con este endpoint

• Consultar una sección publicada y obtener sus testimonios públicos.
• Recuperar un testimonio individual (siempre que esté publicado).
• Limitar la cantidad de resultados con limit para optimizar el consumo del API.
• Reutilizar el mismo token para varias secciones a las que tenga acceso con permiso read.

Qué no puedes hacer

• Crear, actualizar o eliminar testimonios (el endpoint es solo de lectura).
• Obtener testimonios en estado draft o secciones no publicadas.
• Acceder a secciones para las que el token no tiene permisos.
• Utilizar un método distinto de GET; cualquier otro método devuelve 405.