Ksiopea · Integración

API de horarios

Lectura del horario que genera Ksiopea, para que el gestor del centro y otros sistemas lo consuman sin credenciales de persona. Solo lectura, por centro, versionada. El contrato es OpenAPI 3.1: se importa en Postman, Insomnia o un generador de clientes, y el backend se construye contra ese mismo documento.

Descargar el contrato OpenAPI Hablemos de integración

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 se guarda hasheada; ámbito solo lectura, revocable en cualquier momento. Se envía en la cabecera:

Authorization: Bearer ksio_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Para pruebas de integración se emiten claves de sandbox (ksio_test_...) sobre un centro de ejemplo.

Base y versionadoRutas estables

Producción: https://api.ksiopea.com/v1
Pruebas: https://sandbox.api.ksiopea.com/v1

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

RecursosEndpoints

Método	Ruta	Devuelve
GET	`/center`	Metadatos del centro (nombre, etapas, curso activo).
GET	`/schedules`	Horarios publicados.
GET	`/schedules/{sid}`	Cabecera + marcos horarios (campanas por día).
GET	`/schedules/{sid}/groups`	Grupos con su código.
GET	`/schedules/{sid}/teachers`	Docentes con su código (idnumber/nick).
GET	`/schedules/{sid}/rooms`	Aulas con su código.
GET	`/schedules/{sid}/subjects`	Materias con su código.
GET	`/schedules/{sid}/timetable`	Sin filtro, el horario completo; con `group`, `teacher` o `room`, esa entidad. `format=cifra` devuelve los códigos Cifra.
GET	`/schedules/{sid}/ics`	Feed ICS suscribible (Google/Microsoft).

Usa current como sid para el horario publicado vigente, sin listar.

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 (campanas desfasadas entre etapas ya resueltas). No se expone dato alguno de alumnado.

FormatosCualquier SIS · Cifra e ICS

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

format=cifra: los identificadores salen como los códigos Cifra del export (docente/grupo/materia/marco), para reconciliar sin traducir.
Feed ICS: URL suscribible por grupo/docente/aula; cada clase es un evento semanal recurrente durante el curso, con ETag y regeneración al publicar un horario nuevo.

ErroresRespuestas

Los errores llegan como { "error": { "code", "message" } } con el HTTP coherente:

HTTP	code	Cuándo
401	`unauthorized`	Clave ausente o inválida.
403	`forbidden`	Clave revocada o fuera de ámbito.
404	`not_found`	Recurso inexistente.
400	`bad_request`	Parámetros incorrectos.
429	`rate_limited`	Límite por clave; reintenta según `Retry-After`.

IntegrarPrimeros pasos

Descarga el contrato OpenAPI e impórtalo en tu herramienta (Postman, Insomnia, Swagger UI, o un generador de clientes).
Pide acceso al sandbox: te damos una clave ksio_test_... y un centro de ejemplo para validar la integración.
Cuando el contrato encaje con vuestro lado, pasamos a producción con la clave del centro real.