Ksiopea·
OpenAPI
Ksiopea · Integración

API de horarios

El horario que genera Ksiopea, para que el programa de gestión del centro y otros sistemas lo lean sin usar la cuenta de nadie. Solo lectura, por centro, versionada. El contrato es OpenAPI 3.1: se importa en Postman, Insomnia o un generador de clientes, y nuestro servidor está hecho a partir de ese mismo documento.

Especificación · borrador para integración

AutenticaciónClave de API por centro

Cada centro genera su clave desde el panel de administración. Se muestra una sola vez y solo guardamos su huella (hash); solo permite leer y se puede revocar en cualquier momento. Se envía en la cabecera:

Authorization: Bearer ksio_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Para probar la integración damos claves de pruebas (ksio_test_...) con un centro de ejemplo.

Direcciones y versionesRutas estables

Un cambio incompatible sube la versión de la ruta (/v2); nunca se rompe /v1 en silencio.

RecursosEndpoints

MétodoRutaDevuelve
GET/centerMetadatos del centro (nombre, etapas, curso activo).
GET/schedulesHorarios publicados.
GET/schedules/{sid}Datos generales y marcos horarios (los tramos de cada día).
GET/schedules/{sid}/groupsGrupos con su código.
GET/schedules/{sid}/teachersDocentes con su código (idnumber/nick).
GET/schedules/{sid}/roomsAulas con su código.
GET/schedules/{sid}/subjectsMaterias con su código.
GET/schedules/{sid}/timetableSin filtro, el horario completo; con group, teacher o room, esa entidad. format=cifra devuelve los códigos Cifra.
GET/schedules/{sid}/icsCalendario ICS para suscribirse (Google, Microsoft).

Usa current como sid para pedir el horario vigente sin tener que listarlos.

EjemploEl horario de un grupo

curl "https://api.ksiopea.com/v1/schedules/sched_2526_def/timetable?group=3esoA" \
  -H "Authorization: Bearer ksio_live_xxxx"
{
  "schedule_id": "sched_2526_def",
  "entity": { "id": "3esoA", "code": "3ESOA", "name": "3º ESO A" },
  "sessions": [
    {
      "day": 2, "slot": 2, "start": "09:55", "end": "10:50",
      "subject": { "id": "MAT", "name": "Matemáticas" },
      "teacher": { "id": "a1b2", "code": "P034", "name": "Docente 34" },
      "room":    { "id": "r12",  "code": "12",   "name": "Aula 12" },
      "kind": "class"
    }
  ]
}

Los tramos siguen el marco del grupo, así que las etapas con horas distintas ya vienen resueltas. No sale ningún dato del alumnado.

FormatosCualquier gestor · Cifra e ICS

El formato nativo es el general y sirve a cualquier gestor. format=cifra es solo una comodidad para cuadrar con ese programa, no una integración exclusiva.

ErroresRespuestas

Los errores llegan como { "error": { "code", "message" } } con el código HTTP que corresponde:

HTTPcodeCuándo
401unauthorizedClave ausente o inválida.
403forbiddenClave revocada o fuera de ámbito.
404not_foundRecurso inexistente.
400bad_requestParámetros incorrectos.
429rate_limitedLímite de peticiones por clave; vuelve a intentarlo cuando indique Retry-After.

IntegrarPrimeros pasos

Hablemos de integración

Háblanos de tu sistema y lo vemos con tu equipo.