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.
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
- 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} | Datos generales y marcos horarios (los tramos de cada 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 | Calendario 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.
format=cifra: los identificadores salen con los códigos de la exportación de Cifra (docente, grupo, materia y marco), para cuadrarlos sin traducir nada.- Calendario ICS: una dirección por grupo, docente o aula para suscribirse; cada clase es un evento que se repite cada semana durante el curso, con
ETag, y se actualiza al publicar un horario nuevo.
ErroresRespuestas
Los errores llegan como { "error": { "code", "message" } } con el código HTTP que corresponde:
| 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 de peticiones por clave; vuelve a intentarlo cuando indique 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 entorno de pruebas: te damos una clave
ksio_test_...y un centro de ejemplo para validar la integración. - Cuando todo encaje en tu sistema, pasamos a producción con la clave del centro real.