APIs GraphQL internas

Las interfaces web del sistema se comunican con los backends mediante GraphQL. Estas APIs son internas: su contrato sigue la evolución de los frontends y no se garantiza compatibilidad para integraciones externas. Para integraciones use las APIs REST.

Características comunes

• Vista: FileUploadGraphQLView (graphene-file-upload). Acepta peticiones JSON estándar y multipart/form-data para subir archivos según la especificación GraphQL multipart request.
• Implementación: graphene-django + django-graphbox. Cada schema se arma combinando las queries y mutations de varias apps de Django.
• Método: POST al path del schema (por ejemplo BASE_URL_SPS/admin-schema/).
• Cliente en los frontends: Apollo Client. La URL se arma como VITE_API_ENDPOINT + VITE_API_ENDPOINT_PATH (ver Imágenes Docker).
• GraphiQL: disponible en el mismo path solo si el backend corre con DEBUG=True.

Autenticación y sesión

Los schemas GraphQL no usan tokens OAuth2 en la cabecera: trabajan con una sesión por cookie que el backend crea al completar el inicio de sesión.

• CSRF: las peticiones POST requieren la cabecera X-CSRFToken. El token se obtiene en:
  • IDP: BASE_URL_IDP/auth/public/csrf-token/
  • SPS: BASE_URL_SPS/iam-core/csrf-token/
• Sesión: el backend guarda el identificador de sesión hasheado en base de datos y lo valida en cada petición.
• Autorización por portal: en el SPS cada schema tiene su gestor de sesión (admin_session_manager, comision_session_manager, postulante_session_manager, estacion_examen_session_manager), que verifica que el usuario esté activo y tenga acceso vigente a ese portal (y al grupo o rol que exige la operación).
• Modo standby: con SYSTEM_STATUS=False, StandbyMiddleware responde 503 ({"error": "STANDBY", ...}) a toda petición excepto /health/, en ambos backends.

Schemas del IDP

Backend: auth-backend. URL base: BASE_URL_IDP.

Path	Frontend	Audiencia	Apps incluidas
/admin-schema/	auth-frontend-admin	Administradores del IDP	iam_core, oauth2_eje, oidc, aprobacion_documentos, notificaciones
/main-schema/	auth-authorization-frontend	Registro de cuentas en el portal de autorización	iam_core
/public-schema/	frontend-public-auth	Usuarios gestionando su cuenta	iam_core, aprobacion_documentos

Schemas del SPS

Backend: backend-seleccion-postulantes. URL base: BASE_URL_SPS.

Path	Frontend	Audiencia
/admin-schema/	frontend-portal-admin-seleccion-postulantes	Personal administrativo
/comision-schema/	frontend-portal-comisiones-seleccion-postulantes	Miembros de comisiones
/postulante-schema/	frontend-portal-postulantes-seleccion-postulantes	Postulantes
/estacion-examen-schema/	frontend-estacion-examen	Estaciones de examen en línea

Apps incluidas en cada schema:

Schema	Apps
admin	catalogos, iam_core, document_engine, analitica_planillas, sgc, acciones_previas, custodio_integration, convocatorias, difusion, comisiones, resoluciones, trabajo_comisiones, conclusion_proceso, impugnaciones, reportes, interoperabilidad, datos_historicos, notificaciones, consultas, seeders
comision	iam_core, document_engine, sgc, convocatorias, postulaciones, comisiones, trabajo_comisiones, impugnaciones, interoperabilidad, reportes
postulante	catalogos, iam_core, document_engine, sgc, convocatorias, difusion, postulaciones, trabajo_comisiones, impugnaciones, consultas
estacion_examen	trabajo_comisiones

Estaciones de examen

Las estaciones no inician sesión con usuario: se registran subiendo un archivo de credencial JWT generado desde el sistema para el recinto. Estos endpoints REST están exentos de CSRF.

Método	Ruta	Descripción
POST	/trabajo-comisiones/registrar-estacion-examen/	Recibe el archivo credential_jwt (multipart), lo valida y crea la cookie de sesión de la estación
POST	/trabajo-comisiones/sustituir-estacion-examen/	Sustituye una estación registrada usando una credencial JWT

Con esa sesión, la estación opera contra /estacion-examen-schema/.

Actualización automática de estados

El SPS incluye CierreFaseAutomaticoMiddleware: antes de procesar cualquier petición a los cuatro schemas GraphQL, cierra las fases de convocatoria vencidas y marca como finalizadas las rendiciones de examen cuyo tiempo terminó. Por eso los estados pueden cambiar sin una acción explícita del usuario.

Explorar un schema

Con DEBUG=True (entorno local), abra el path del schema en el navegador (por ejemplo http://localhost:8000/postulante-schema/) para usar GraphiQL, que incluye el explorador de documentación del schema.

Para auditar qué campos de un schema usa su frontend, vea el script auditar_types_graphql en Scripts útiles de los backends.