API de integración — GesClas

Conecta GesClas con tus sistemas (académico, ERP, libro de clases). Esta referencia es para tu equipo de TI.

URL base: https://gesclas.cl/api/v1

Autenticación

Todas las llamadas usan una API key que genera el administrador de tu institución en Administración → API de integración. Se muestra una sola vez; guárdala en un lugar seguro.

Envíala en la cabecera Authorization:

Authorization: Bearer cal_xxxxxxxxxxxxxxxxxxxxxxxx

La key está acotada a TU institución: solo accede a tus evaluaciones, alumnos y apoderados. Si se filtra, revócala y crea otra.

GET/exams/{codigo}/results

Devuelve las calificaciones y resultados de una evaluación (por su código).

curl -H "Authorization: Bearer $API_KEY" \
  https://gesclas.cl/api/v1/exams/E12345/results

Respuesta 200:

{
  "exam": { "codigo": "E12345", "titulo": "Prueba Ciencias", "curso": "5B" },
  "results": [
    { "rut": "15555555-5", "nombre": "Tomás Díaz", "nota": 5.8,
      "pct": 83.3, "pts_obten": 5, "pts_total": 6 }
  ]
}

POST/roster

Carga o actualiza tu nómina de alumnos (upsert por RUT). Devuelve el link_code de cada alumno, que el apoderado usa para registrarse.

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alumnos":[{"rut":"15.555.555-5","nombre":"Tomás Díaz","curso":"5B"}]}' \
  https://gesclas.cl/api/v1/roster

Respuesta 200:

{ "ok": true, "creados": 1,
  "alumnos": [ { "rut": "15555555-5", "link_code": "KW46YVQK" } ] }

POST/guardians

Vincula apoderados con alumnos (por RUT). Si el apoderado no existe, se crea su cuenta (rol apoderado).

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vinculos":[{"guardian_email":"madre@correo.cl","guardian_nombre":"Ana Díaz","alumno_rut":"15.555.555-5"}]}' \
  https://gesclas.cl/api/v1/guardians

Respuesta 200: { "ok": true, "vinculos_creados": 1 }

Webhooks — notificación de eventos

Configura una URL HTTPS en Administración → Webhooks. GesClas hará un POST a esa URL cuando ocurra el evento exam_graded (se califica una evaluación).

Cuerpo enviado:

{
  "event": "exam_graded",
  "data": { "exam": "E12345", "rut": "15555555-5",
            "nombre": "Tomás Díaz", "nota": 5.8, "pct": 83.3 },
  "ts": 1782400000.0
}

Verificación de firma (HMAC-SHA256): cada envío incluye la cabecera X-GesClas-Signature: sha256=<firma>. Valida que el cuerpo no fue alterado usando el secret del webhook:

import hmac, hashlib
def verificar(cuerpo_bytes, firma_header, secret):
    esperado = "sha256=" + hmac.new(secret.encode(), cuerpo_bytes,
                                     hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, firma_header)

Responde 2xx para confirmar recepción. El envío es best-effort (reintento no garantizado): para conciliación usa además GET /exams/{codigo}/results.

Códigos de error

Código	Significado
401	API key ausente, inválida o revocada
404	Recurso no encontrado en tu institución
400	Solicitud mal formada (JSON o campos inválidos)

Soporte: equipo ValidaNet · GesClas.