Personalización de API: sustituciones de puntos de acceso y hooks

Dónde encontrarlo

Módulo Administración, pantalla Importar, exportar, sección Personalización de API, botón API.

La pantalla está reservada a las cuentas Premium y protegida por una autenticación reforzada: Omniscol vuelve a solicitar la contraseña del administrador antes de abrir la ventana. Como toda acción en esta pantalla afecta al contrato técnico de su integración, su puesta en marcha se realiza en coordinación con Omniscol.

Configuración general

Aquí define cabeceras HTTP (formato clave1:valor1;clave2:valor2) aplicadas a todos los hooks. Es el lugar natural para transportar un token de autenticación hacia su propio servidor (por ejemplo un Authorization: Bearer … que su servidor espera). Para una sustitución, la autenticación se transporta en cambio en las cabeceras propias del punto de acceso (véase más abajo).

Sustitución de un punto de acceso

Una sustitución redefine un punto de acceso de la API de Omniscol para que la aplicación web llame a otra URL en su lugar. Tres usos, del más potente al más simple.

Servir un dato en directo desde su sistema de información

Es el uso más potente. Redirige un punto de acceso de lectura hacia una URL externa — normalmente un ETL que interconecta el sistema de información interno de su centro. La aplicación web va entonces a buscar el dato en directo en ese sistema, en lugar de la copia local que conserva Omniscol.

En concreto: cuando la URL de redirección es una dirección externa absoluta, la aplicación web la llama directamente, sin volver a pasar por los servidores de Omniscol, y consume la respuesta tal cual — exactamente como si viniera de Omniscol. La única restricción es que su sistema responda en el formato esperado por Omniscol para ese punto de acceso (misma estructura JSON): no hay ninguna transcodificación intermedia. Para ese punto de acceso, la copia local de Omniscol deja de consultarse; el dato mostrado es el dato vivo de su sistema.

Ejemplo: el catálogo de asignaturas del centro servido al vuelo desde su sistema de información, de modo que toda actualización del lado del centro sea visible inmediatamente en Omniscol, sin reimportación.

La autenticación hacia su sistema se transporta aquí en las cabeceras propias del punto de acceso (por ejemplo un Authorization: Bearer …), introducidas en la línea de la sustitución. El método HTTP también puede imponerse por punto de acceso.

Reconectar un punto de acceso de la propia aplicación a una fuente externa viva es una posibilidad tan potente como exigente: debe manejarse con su departamento de informática, y en coordinación con Omniscol.

Intercalar su propio servidor o un proxy

También puede hacer pasar las llamadas por su propio servidor o un proxy — por ejemplo para autorizar el intercambio de recursos entre orígenes (CORS), o para intercalar una lógica propia entre la aplicación web y Omniscol.

Desactivar un punto de acceso

Desactiva un punto de acceso al no darle ninguna URL de redirección (método null).

Valore el efecto en la interfaz. Omniscol es una aplicación web de una sola página (SPA) cuyos elementos de interfaz están gobernados por los puntos de acceso disponibles: los botones, pestañas y menús solo se muestran si el punto de acceso del que dependen existe. Desactivar un punto de acceso hace por tanto desaparecer dinámicamente, en la siguiente visualización, los elementos de interfaz que dependen de él — y si desactiva todos los puntos de acceso de un módulo, es el módulo entero el que desaparece de la navegación. Estos elementos se retiran, no solo se ocultan, y todo ello se hace sin ninguna intervención en el código: basta con modificar la configuración y recargar la aplicación.

La tabla enumera, por punto de acceso: su clave (el código interno de la operación), su URL de origen, el método HTTP, la nueva URL de redirección y cabeceras específicas. Un campo de búsqueda permite encontrar el punto de acceso que se desea sustituir.

Hooks (llamadas salientes)

Un hook pide a Omniscol que envíe una petición HTTP a su URL después de que una operación haya tenido éxito. Es el mecanismo para mantener un sistema externo al corriente en tiempo real — un panel de información, un espacio digital de trabajo, un sistema de recursos humanos, una sincronización propia…

Un hook se conecta de dos maneras:

• a un punto de acceso concreto (la clave de la operación);
• a un evento agrupado, que cubre de una vez una familia de operaciones. Existen tres eventos agrupados:
  • modificación de horario (creación, desplazamiento o eliminación de sesiones, activación de un horario, y ausencias de profesor o de clase en cuanto se ve afectada una fecha);
  • modificación de un profesor (adición, actualización o eliminación);
  • modificación de una asignatura (asignaturas personalizadas).

Para cada hook, indica la URL de retorno de llamada, el método HTTP, la casilla «con datos» (¿debe adjuntarse el cuerpo de la petición de origen?) y cabeceras propias.

Lo que recibe su servidor

La llamada se envía en application/json y transporta, además de sus cabeceras:

• el cuerpo de la petición de origen si la opción «con datos» está activada;
• un bloque de metadatos de Omniscol: la URL llamada, el código del punto de acceso, el método, los parámetros, el token de autenticación del usuario y el identificador del centro;
• cabeceras de trazabilidad: X-OS-original-query, X-OS-original-endpoint, X-OS-auth y X-School.

Para el evento modificación de horario, cuando la opción «con datos» está activa, la llamada incluye además un diferencial de las sesiones (sesiones añadidas, modificadas, eliminadas) — práctico para propagar solo lo que ha cambiado.

Comportamiento

Los hooks parten en segundo plano, después de que la operación del usuario haya concluido: no ralentizan la interfaz y no la bloquean en caso de fallo de su servidor. Una llamada saliente que no concluye queda registrada, sin interrumpir el trabajo en Omniscol. Cada llamada tiene un plazo de expiración corto (unos segundos): su servidor debe acusar recibo rápidamente y procesar el resto por su lado.

Conviene saber

• La API de Omniscol expone un subconjunto de operaciones; una sustitución o un hook solo se aplica a los puntos de acceso realmente expuestos. Véase API de Omniscol para la lista y la autenticación.
• Para una integración con un paquete de software (ERP, SIRH, espacio digital de trabajo), la sincronización dedicada suele ser más adecuada — véase Sincronización con sistemas externos. Internamente, se utiliza el mismo sistema de hook.
• Para que un agente de IA consulte sus datos sin desarrollo, véase MCP — conectar un agente de IA externo.