Manual de uso del API de Calendario

Este API permite gestionar categorías y eventos del calendario desde integraciones externas.
Las rutas viven bajo /api/calendar/* y devuelven JSON.

Autenticación

• Envía Authorization: Bearer <token> en cada solicitud.
• El token debe estar activo y tener permisos sobre el recurso que consultas.
• Mantén Content-Type: application/json cuando el endpoint acepte cuerpo.

Permisos

• read: requerido para todas las solicitudes (GET).
• update: permite usar includeDrafts=true en /events para ver borradores/eventos programados.

Si el token está vencido, inactivo o no cuenta con los permisos necesarios, la respuesta será 401 o 403.

Respuestas comunes

• 200 OK: solicitud exitosa.
• 400 Bad Request: parámetros o cuerpo inválidos.
• 401 / 403: token inválido, expirado o sin permisos.
• 404 Not Found: recurso inexistente o no visible para el modo actual.
• 405 Method Not Allowed: se usó un método no soportado.
• 500 Internal Server Error: error inesperado en el servidor.

Categorías — /api/calendar/categories

GET listado

Lista las categorías disponibles para la página asociada al token.

Parámetros opcionales

• limit (número, 1‑100): restringe la cantidad de resultados.
• id / slug (string): devuelve una única categoría que coincida con el identificador.

curl "https://cms.begraffic.com/api/calendar/categories?limit=50" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

{
  "count": 2,
  "categories": [
    {
      "id": "lanzamientos",
      "name": "Lanzamientos",
      "description": "Actividades de lanzamiento",
      "color": "#f97316",
      "createdAt": "2024-07-12T15:00:00.000Z",
      "updatedAt": "2024-07-12T15:00:00.000Z"
    }
  ]
}

Si envías id/slug, la respuesta tendrá la forma:

{ "category": { ... } }

Eventos — /api/calendar/events

GET listado

Devuelve eventos futuros o ya publicados para la página del token.

Parámetros opcionales

• start (ISO): obtiene eventos cuyo inicio sea igual o posterior a la fecha.
• end (ISO): obtiene eventos cuyo inicio sea igual o anterior a la fecha indicada.
• categoryId (string): filtra por categoría.
• limit (1‑200): máximo de registros.
• includeDrafts (booleano): requiere permiso update y devuelve además borradores/programados.

curl "https://cms.begraffic.com/api/calendar/events?start=2024-07-01&end=2024-07-31" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

{
  "count": 1,
  "events": [
    {
      "id": "launch-demo",
      "title": "Demo de lanzamiento",
      "description": "Presentación del nuevo producto.",
      "start": "2024-07-08T15:00:00.000Z",
      "end": "2024-07-08T16:30:00.000Z",
      "location": "Google Meet",
      "visibility": "public",
      "categoryId": "lanzamientos",
      "categoryName": "Lanzamientos",
      "categoryColor": "#f97316",
      "publish": true,
      "publishAt": null,
      "isPublished": true,
      "isScheduled": false,
      "isAllDay": false,
      "createdAt": "2024-07-01T10:00:00.000Z",
      "updatedAt": "2024-07-01T10:00:00.000Z"
    }
  ]
}

Los eventos programados (publish = false y publishAt futuro) solo se devuelven cuando el token incluye includeDrafts=true y cuenta con permiso update.

GET detalle

GET /api/calendar/events?id=<id>
Devuelve un único evento publicado (o borrador, si includeDrafts=true y el token tiene update).

Notas generales

• Todas las fechas se esperan y devuelven en formato ISO 8601.
• Los errores se devuelven en la forma { "error": "mensaje descriptivo" }.
• El API está pensado para integraciones de confianza; aplica límites razonables (limit, rangos de fechas) para evitar lecturas muy grandes.