Manual de uso del API de Cursos (solo lectura)

El API de cursos permite consultar la oferta académica publicada: cursos, materias y clases. Todos los endpoints están bajo /api/cursos y devuelven JSON.

Autenticación

En cada petición incluye Authorization: Bearer <TOKEN>.
El token debe estar activo y tener permisos sobre el recurso que consultas.
Aunque las rutas actuales solo aceptan GET, mantén Content-Type: application/json si envías parámetros serializados en el cuerpo.

Permisos

read: habilita las peticiones GET descritas abajo.

Sin token, con token expirado o sin permiso read, la API responde con 401 o 403.

Códigos de respuesta comunes

200 OK: solicitud exitosa.
400 Bad Request: parámetros inválidos.
401 / 403: token ausente, inválido o sin permisos.
404 Not Found: curso/materia/clase inexistente, inactiva o sin publicar.
405 Method Not Allowed: se intentó un método distinto de GET.
500 Internal Server Error: error no controlado en el servidor.

Resumen rápido de rutas

Objetivo	Endpoint	Parámetros clave
Listar cursos publicados	`GET /api/cursos`	`limit`, `includeSubjects`, `includeClasses`, `includeFacilitators`, `includeContent`
Ver un curso puntual	`GET /api/cursos?courseId=<id>`	Igual que listado
Curso completo (con materias, clases y facilitadores)	`GET /api/cursos?courseId=<id>&includeSubjects=1&includeClasses=1&includeFacilitators=1`	(opcional) `includeContent`
Obtener materias de un curso	`GET /api/cursos?mode=subjects&courseId=<id>`	`subjectId`, `includeClasses`, `includePeriods`
Obtener clases de una materia	`GET /api/cursos?mode=classes&courseId=<id>&subjectId=<id>`	`periodId`
Obtener periodos de un curso	`GET /api/cursos?mode=periods&courseId=<id>`	`periodId`, `includeClasses`
Todos los cursos con árbol completo	`GET /api/cursos?mode=full`	—

Listado de cursos — `GET /api/cursos`

Devuelve cursos activos y publicados asociados al token. Los resultados están ordenados alfabéticamente por nombre.

Parámetros de consulta

includePeriods (boolean, opcional): agrega el arreglo de periodos con sus materias. Si includeSubjects es false, se devuelven únicamente los periodos.
limit (número, opcional): número máximo de cursos (1–100). Por defecto 50.
includeSubjects (boolean, opcional): agrega las materias al resultado.
includeClasses (boolean, opcional): requiere includeSubjects=true; anida las clases dentro de cada materia.
includeFacilitators (boolean, opcional): agrega el arreglo de facilitadores con nombre, cargo, descripción y foto.
includeContent (boolean, opcional): devuelve el objeto content del curso. Requiere que el token tenga el permiso «Contenido de cursos» (se marca al crear o editar el token en API & Tokens); sin él, la API responde 403. Úsalo solo con tokens de servidor — nunca en un token expuesto en el navegador, porque el contenido puede ser de pago.
courseId / id (string, opcional): si se especifica, devuelve únicamente ese curso.

Los parámetros booleanos aceptan true, 1, yes u on (ignora mayúsculas/minúsculas).

Ejemplo (listado)

bash

curl "https://cms.begraffic.com/api/cursos?limit=20&includeSubjects=true" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "items": [
    {
      "id": "marketing-2024",
      "nombre": "Marketing 2024",
      "descripcionCorta": "Domina estrategias digitales.",
      "activo": true,
      "esGratis": false,
      "tieneInscripcion": true,
      "inscripcionesHabilitadas": true,
      "precio": 199,
      "inscripcionPrecio": 49,
      "idProductoStripe": "prod_ABC123",
      "opcionesPago": [
        {
          "id": "insc-1",
          "nombre": "Pago único",
          "cuotas": 1,
          "precio": "49",
          "frecuencia": "unico",
          "idProductoStripe": "price_INSCRIPCION"
        }
      ],
      "opcionesPagoPrecio": [],
      "coverImage": {
        "originalFileName": "marketing.jpg",
        "previewUrl": "https://...",
        "variants": {
          "medium": {
            "url": "https://...",
            "width": 800,
            "height": 450,
            "format": "jpg",
            "mimeType": "image/jpeg"
          }
        }
      },
      "createdAt": "2024-05-10T18:30:00.000Z",
      "updatedAt": "2024-05-20T13:15:00.000Z",
      "publishedAt": "2024-05-25T12:00:00.000Z",
      "subjects": [
        {
          "id": "fundamentos",
          "titulo": "Fundamentos",
          "descripcion": "",
          "coverImage": null,
          "classes": [
            {
              "id": "cls-intro",
              "titulo": "Introducción",
              "descripcion": "Primeros pasos.",
              "coverImage": null
            }
          ]
        }
      ]
    }
  ]
}

Ejemplo (curso puntual)

bash

curl "https://cms.begraffic.com/api/cursos?courseId=marketing-2024&includeSubjects=true&includeFacilitators=true" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "course": {
    "id": "marketing-2024",
    "nombre": "Marketing 2024",
    "descripcionCorta": "Domina estrategias digitales.",
    "activo": true,
    "esGratis": false,
    "tieneInscripcion": true,
    "inscripcionesHabilitadas": true,
    "precio": 199,
    "inscripcionPrecio": 49,
    "idProductoStripe": "prod_ABC123",
    "opcionesPago": [],
    "opcionesPagoPrecio": [],
    "coverImage": { "...": "..." },
    "createdAt": "2024-05-10T18:30:00.000Z",
    "updatedAt": "2024-05-20T13:15:00.000Z",
    "publishedAt": "2024-05-25T12:00:00.000Z",
    "subjects": [ /* ... */ ],
    "facilitators": [
      {
        "id": "ana-garcia",
        "nombre": "Ana García",
        "cargo": "Consultora Senior",
        "descripcion": "Más de 10 años liderando estrategias de marketing digital.",
        "foto": {
          "previewUrl": "https://...",
          "variants": { "...": "..." }
        }
      }
    ]
  }
}

Materias — `GET /api/cursos?mode=subjects`

Devuelve las materias publicadas de un curso. Siempre incluye un resumen del curso (course) y puede incluir la estructura de periodos completa para mantener el contexto del plan de estudios.

Parámetros

courseId (string, requerido): identificador del curso.
subjectId (string, opcional): si se especifica, devuelve solo esa materia.
includeClasses (boolean, opcional): anida las clases de cada materia en el mismo resultado.
includePeriods (boolean, opcional): agrega el arreglo completo de periodos además de las materias solicitadas.

Ejemplo (todas las materias con periodos)

bash

curl "https://cms.begraffic.com/api/cursos?mode=subjects&courseId=marketing-2024&includeClasses=true&includePeriods=true" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "course": {
    "id": "marketing-2024",
    "nombre": "Marketing 2024",
    "descripcionCorta": "Domina estrategias digitales.",
    "coverImage": null,
    "publishedAt": "2024-05-25T12:00:00.000Z"
  },
  "subjects": [
    {
      "id": "fundamentos",
      "titulo": "Fundamentos",
      "descripcion": "",
      "coverImage": null,
      "periodId": "periodo-1",
      "periodTitulo": "Primer trimestre",
      "classes": [
        {
          "id": "cls-intro",
          "titulo": "Introducción",
          "descripcion": "Primeros pasos.",
          "coverImage": null
        }
      ]
    }
  ],
  "periods": [
    {
      "id": "periodo-1",
      "titulo": "Primer trimestre",
      "descripcion": "",
      "subjects": [
        {
          "id": "fundamentos",
          "titulo": "Fundamentos",
          "descripcion": "",
          "coverImage": null,
          "classes": [
            {
              "id": "cls-intro",
              "titulo": "Introducción",
              "descripcion": "Primeros pasos.",
              "coverImage": null
            }
          ]
        }
      ]
    }
  ]
}

Ejemplo (materia puntual)

bash

curl "https://cms.begraffic.com/api/cursos?mode=subjects&courseId=marketing-2024&subjectId=fundamentos" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "course": { "...": "..." },
  "subject": {
    "id": "fundamentos",
    "titulo": "Fundamentos",
    "descripcion": "",
    "coverImage": null
  }
}

(Agregar includeClasses=true para obtener también las clases dentro del objeto subject.)

Clases — `GET /api/cursos?mode=classes`

Devuelve las clases de una materia específica. Incluye el resumen del curso, la materia y, cuando sea posible, el periodo al que pertenece.

Parámetros

courseId (string, requerido)
subjectId (string, requerido)
periodId (string, opcional): si lo proporcionas, la API busca directamente en ese periodo (útil si ya conoces la jerarquía).

Ejemplo

bash

curl "https://cms.begraffic.com/api/cursos?mode=classes&courseId=marketing-2024&subjectId=fundamentos" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "course": { "...": "..." },
  "subject": {
    "id": "fundamentos",
    "titulo": "Fundamentos",
    "descripcion": "",
    "coverImage": null,
    "facilitatorId": "ana-garcia"
  },
  "classes": [
    {
      "id": "cls-intro",
      "titulo": "Introducción",
      "descripcion": "Primeros pasos.",
      "coverImage": null
    }
  ]
}

Curso completo (toda la información)

Para obtener un solo curso con materias, clases y facilitadores en la misma respuesta, combina los parámetros includeSubjects, includeClasses e includeFacilitators junto con courseId.

bash

curl "https://cms.begraffic.com/api/cursos?courseId=marketing-2024&includeSubjects=1&includeClasses=1&includeFacilitators=1" \
  -H "Authorization: Bearer TU_TOKEN"

Si también requieres el contenido del curso, agrega includeContent=1 (el token debe tener el permiso «Contenido de cursos»).

Periodos — `GET /api/cursos?mode=periods`

Devuelve los periodos publicados de un curso junto con sus materias y, opcionalmente, las clases. Siempre incluye un resumen del curso (course).

Parámetros

courseId (string, requerido): identificador del curso.
periodId (string, opcional): si se especifica, devuelve solo ese periodo.
includeClasses (boolean, opcional): anida las clases dentro de cada materia del periodo.

Ejemplo

bash

curl "https://cms.begraffic.com/api/cursos?mode=periods&courseId=marketing-2024&includeClasses=true" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "course": {
    "id": "marketing-2024",
    "nombre": "Marketing 2024"
  },
  "periods": [
    {
      "id": "periodo-1",
      "titulo": "Primer trimestre",
      "descripcion": "",
      "subjects": [
        {
          "id": "fundamentos",
          "titulo": "Fundamentos",
          "classes": [
            {
              "id": "cls-intro",
              "titulo": "Introducción"
            }
          ]
        }
      ]
    }
  ]
}

Todos los cursos (árbol completo) — `GET /api/cursos?mode=full`

Devuelve todos los cursos publicados con sus materias, clases y facilitadores simultáneamente. Es equivalente a solicitar includeSubjects=true, includeClasses=true e includeFacilitators=true para cada curso individual.

Ejemplo

bash

curl "https://cms.begraffic.com/api/cursos?mode=full" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "items": [
    {
      "id": "marketing-2024",
      "nombre": "Marketing 2024",
      "subjects": [
        {
          "id": "fundamentos",
          "classes": [
            { "id": "cls-intro", "titulo": "Introducción", "descripcion": "Primeros pasos.", "coverImage": null }
          ]
        }
      ],
      "facilitators": [
        {
          "id": "ana-garcia",
          "nombre": "Ana García",
          "cargo": "Consultora Senior",
          "descripcion": "Más de 10 años liderando estrategias de marketing digital.",
          "foto": { "...": "..." }
        }
      ]
    }
  ]
}

⚠️ Usa esta ruta con moderación: al devolver todo el árbol puede resultar pesada. Para integraciones paginadas o vistas específicas, prefiere los modos segmentados.

Notas y limitaciones

Solo se exponen los cursos publicados.
El orden de cursos, materias y clases es el definido por el propietario del contenido.
Los campos numéricos (p.ej., precios) se devuelven como número cuando es posible.
El objeto content se devuelve con las referencias a sus medios asociados.
Cada curso publicado incluye su fecha de publicación en el campo publishedAt.
No existen rutas públicas para crear, editar o eliminar cursos mediante esta API.
Si necesitas consultar recursos adicionales (por ejemplo, facilitadores o archivos multimedia), usa los endpoints específicos cuando estén disponibles.

Manual de uso del API de Cursos (solo lectura)

Autenticación

Permisos

Códigos de respuesta comunes

Resumen rápido de rutas

Listado de cursos — GET /api/cursos

Parámetros de consulta

Ejemplo (listado)

Ejemplo (curso puntual)

Materias — GET /api/cursos?mode=subjects

Parámetros

Ejemplo (todas las materias con periodos)

Ejemplo (materia puntual)

Clases — GET /api/cursos?mode=classes

Parámetros

Ejemplo

Curso completo (toda la información)

Periodos — GET /api/cursos?mode=periods

Parámetros

Ejemplo

Todos los cursos (árbol completo) — GET /api/cursos?mode=full

Ejemplo

Notas y limitaciones

Listado de cursos — `GET /api/cursos`

Materias — `GET /api/cursos?mode=subjects`

Clases — `GET /api/cursos?mode=classes`

Periodos — `GET /api/cursos?mode=periods`

Todos los cursos (árbol completo) — `GET /api/cursos?mode=full`