Este servicio web permite registrar o actualizar la calificación de un estudiante dentro de un acta de examen.

Además de la calificación principal, el servicio también puede guardar libro, folio, observaciones y, cuando la configuración del sistema lo permite, las calificaciones de escrito y oral.

• Usuarios con rol Administrador y permiso 1709 - PERMISO_ACTAS_GESTIONAR_CALIFICACIONES.
• Usuarios con rol Docente y permiso 1720 - PERMISO_DOCENTE_REGISTRAR_CALIFICACIONES_ACTA.
• En el caso de usuarios docentes, además del permiso correspondiente, deben estar vinculados al acta como presidente o vocal.

La invocación se realiza por fuera de la interfaz habitual del sistema, por ejemplo desde Postman o desde una integración externa.

1. Realice una solicitud PUT al endpoint /api/v1/WSExaminationRecords/updateStudentGrade.
2. Envíe el encabezado X-API-KEY con una clave válida.
3. Indique el examinationRecordId y el studentId.
4. Envíe la calificación principal en gradeId, salvo que la inscripción sea de solo lectura.
5. Si corresponde, complete book, folio y observations.
6. Si el sistema tiene habilitada la calificación escrita y oral, también puede enviar gradeIdWritten y gradeIdOral.
7. Verifique la respuesta del servicio para confirmar que el registro fue actualizado correctamente.

Ejemplo básico:

{
  "examinationRecordId": 100,
  "studentId": 200,
  "gradeId": 50
}

Ejemplo con datos complementarios:

{
  "examinationRecordId": 100,
  "studentId": 200,
  "gradeId": 50,
  "book": "12",
  "folio": "45",
  "observations": "Calificación registrada por integración"
}

Cuando la operación es correcta, el servicio responde con estado HTTP 200 y una estructura similar a la siguiente:

{
  "success": true,
  "message": "...",
  "data": {
    "examinationRecordStudentId": 123,
    "studentState": 20
  }
}

studentState indica el estado recalculado del estudiante luego del guardado.

Recalculo del estado del estudiante

• Si la calificación enviada corresponde a sin nota, y no representa ausente ni en proceso, el estudiante queda en estado PENDIENTE.
• En cualquier otro caso, el estudiante queda en estado CALIFICADO.

Calificación escrita y oral

• Si el parámetro MANEJO_CALIFICACION_ESCRITO_ORAL_ACTAS está activo, se pueden informar gradeIdWritten y gradeIdOral.
• Si ese parámetro está desactivado y se envía alguno de esos dos valores, el servicio devuelve error.

Inscripciones de solo lectura

• Si la inscripción del estudiante está marcada como readonly, solo se pueden actualizar book, folio y observations.
• En ese escenario no debe enviarse ninguna calificación.

• Registrar una calificación final de un estudiante en un acta de examen.
• Actualizar libro, folio y observaciones de una inscripción ya existente.
• Registrar calificación escrita y oral cuando esa modalidad está habilitada en el sistema.
• Marcar una inscripción como pendiente al guardar una calificación equivalente a “sin nota”.

• El servicio registra cambios sobre la inscripción del estudiante en el acta y también deja historial en la tabla de auditoría correspondiente.
• Si el acta está cerrada, no se permite guardar cambios.
• Si el estudiante no está inscripto en el acta o la inscripción fue eliminada, la operación no se realiza.
• La validez de gradeId, gradeIdWritten y gradeIdOral depende del grupo de calificaciones configurado en el acta.

¿Siempre debo enviar gradeId?

Sí, excepto cuando la inscripción del estudiante sea de solo lectura. En ese caso, solo puede informar libro, folio y observaciones.

¿Puedo enviar calificación escrita y oral en cualquier caso?

No. Solo puede hacerlo cuando la configuración correspondiente esté habilitada en el sistema.

¿Qué ocurre si la calificación corresponde a “sin nota”?

El servicio guarda la información y deja al estudiante en estado pendiente, siempre que esa calificación no represente ausente ni en proceso.