API Planes

Owned by Netex Sistemas
Last updated: Dec 01, 2022 by Netex Support
4 min read

Usar codificación de caracteres UTF-8 en el envío de datos

Manual de autenticación y versionado: manual (autenticación y versionado)

Por motivos de seguridad el external_id no puede contener los caracteres \ ni /  (http://tomcat.apache.org/security-6.html).


Añadir estudiantes a un plan

Método: POST

URL:

  • Añadir por id:
    • /admin/rest/administration/api/plans/id/{id}/students?action={action}
  • Añadir por id externo:
    • /admin/rest/administration/api/plans/externalid/{external_id}/students?action={action}


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo: 

{
"ids": [51476,654165]
}

Parámetros

  • action = acción que se quiere realizar (añadir usando ids de usuario o ids externos) (String, obligatorio)
    • Valores permitidos
      • addByIds
      • addByExternalids
  • id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún estudiante haya dado error)

  • status: KO
  • ids / external ids: listado de ids o external ids que han dado error

Validaciones

  • Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
  • Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
  • Se ha escogido la acción "addByIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
  • No se puede añadir estudiantes al plan --> Error PLN003 / 400 (Bad Request)
  • No existe el plan --> Error 400 (Not Found)
  • Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
  • Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON

Añadir estudiantes a un plan (v2)

Método: POST

URL:

  • Añadir por id:
    • /admin/rest/administration/api/plans/id/{id}/students?action={action}
  • Añadir por id externo:
    • /admin/rest/administration/api/plans/externalid/{external_id}/students?action={action}


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo: 

{
"ids": [51476,654165]
}

Parámetros

  • action = acción que se quiere realizar (añadir usando ids de usuario o ids externos) (String, obligatorio)
    • Valores permitidos
      • addByIds
      • addByExternalids
  • id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún estudiante haya dado error)

  • status: KO
  • ids / external ids: mapa de ids o external ids que han dado error con su código correspondiente:
    • PLN004: Alumno no encontrado.
    • PLN005: Alumno con estado inválido(debe estar activo).
    • PLN006: Alumno eliminado.
    • PLN007: Alumno ya inscrito.

Validaciones

  • Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
  • Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
  • Se ha escogido la acción "addByIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
  • No se puede añadir estudiantes al plan --> Error PLN003 / 400 (Bad Request)
  • No existe el plan --> Error 400 (Not Found)
  • Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
  • Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON

Obtener estudiantes de un plan con paginado

Método: GET

URL:

  • Obtener por id:
    • /admin/rest/administration/api/plans/id/{id}/students
  • Obtener por external id:
    • /admin/rest/administration/api/plans/externalid/{external_id}/students
  • Obtener estudiantes con paginación:
    • /admin/rest/administration/api/plans/id/{id}/students?startIndex={startIndex}&count={count}
    • /admin/rest/administration/api/plans/externalid/{external_id}/students?startIndex={startIndex}&count={count}


Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /

Ejemplo: https://demo.central-lms.com/admin/rest/administration/api/plans/id/345/students?startIndex=0&count=100

Parámetros

  • startindex = índice inicial para la paginación (Integer, opcional)
  • count = total de elementos a recuperar para la paginación (Integer, opcional)

Campos devueltos en el Json

Listado de usuarios estudiantes, cada usuario consta de los siguientes campos:

  • id = Identificador
  • external_id = Id externo
  • username = Nombre de usuario

Validaciones

  • Índices erróneos --> Error 416 (Requested Range Not Satisfiable) Usando paginación, ambos índices deben tener un valor
  • Si el plan no existe --> Error 404 (Not Found)
  • No hay usuarios --> Error 204 (No Content)
  • Error en la generación del Json --> Error 503 (Service Unavailable)
  • Todo OK
    • Si no hay paginación --> 200 (OK) + JSON
    • Si hay paginación --> 206 (Partial Content) + JSON

Eliminar estudiantes de un plan

Método: DELETE

URL:

  • Eliminar por id: 
    • /admin/rest/administration/api/plans/id/{id}/students?action={action}
  • Eliminar por id externo:
    • /admin/rest/administration/api/plans/externalid/{external_id}/students?action{action}


Recuerda que por motivos de seguridad, el external_id  no puede contener los caracteres \ ni /

Ejemplo: 

 {
"ids": [51476,654165]
}


Parámetros

  • action = acción que se quiere realizar (eliminar usando ids de usuarios o ids externos) (String, obligatorio)
    • Valores permitidos
      • removeByIds
      • removeByExternalids
  • ids (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)

Campos devueltos en el Json (en caso de que algún estudiante haya dado error)

  • status: KO
  • ids / external ids: listado de ids o external ids que han dado error

Validaciones

  • Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
  • Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
  • Se ha escogido la acción "addByIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
  • No se pueden eliminar estudiantes del plan--> Error PLN001 / 400 (Bad Request)
  • El plan está bloqueado --> Error PLN002 / 400 (Bad Request)
  • No existe el plan --> Error 400 (Not Found)
  • Ejecución OK y todos los estudiantes han sido eliminados -> 200 (OK)
  • Ejecución OK y algún estudiante no ha podido ser eliminado --> 200 (OK) + JSON

Obtener datos de un plan

Método: GET

URL:

  • Obtener por id:
    • /admin/rest/administration/api/plans/id/{id}
  • Obtener por external id:
    • /admin/rest/administration/api/plans/externalid/{external_id}

Ejemplo: https://demo.central-lms.com/admin/rest/administration/api/plans/id/345?startIndex=0&count=100

Parámetros

  • startIndex = índice inicial para la paginación (Integer, opcional)
  • count = total de elementos a recuperar para la paginación (Integer, opcional)

Cabeceras

  • NLC-datesFormat. Opcional, valores permitidos:
    • milliseconds. Las fechas se devolverán en milisegundos
    • en otro caso se seguirá el formato de texto: "yyyy-MM-dd HH:mm:ss"

Campos devueltos en el Json

Listado de usuarios estudiantes, cada usuario consta de los siguientes campos:

  • id = Identificador del plan
  • name = Nombre del plan
  • startDate = Fecha de inicio del plan en formato "yyyy-MM-dd HH:mm:ss" (null si el plan está en estado borrador) o milisegundos (0 si el plan está en estado borrador)
  • endDate = Fecha de finalización del plan en formato  "yyyy-MM-dd HH:mm:ss" (null si el plan está en estado borrador o no se ha delimitado una fecha de fin) o milisegundos (0 si el plan está en estado borrador o no se ha delimitado una fecha de fin).
  • externalId = Identificador externo del plan.
  • students = Lista que incluye los datos de los estudiantes inscritos en el plan. Si no hay estudiantes inscritos, la lista se devuelve vacía.
    • id = Identificador de usuario del estudiante.
    • username = Nombre de usuario del estudiante.
    • firstName = Nombre del estudiante.
    • lastName = Apellidos del estudiante.
    • email = Correo electrónico del estudiante.
    • enrolmentDate = Fecha de inscripción del estudiante en formato "yyyy-MM-dd HH:mm:ss" o milisegundos.
    • passedCourses = Número de cursos superados.
    • passedMandatoryCourses = Número de cursos obligatorios superados.
    • passedPlanDate = Fecha de superación/convalidación del estudiante en el plan en milisegundos (0 si el estudiante aún no ha superado el plan)
    • status = Estado del estudiante en el plan. Posibles valores
      • IN_PROGRESS (en progreso)
      • PASSED (superado)
      • NOT_PASSED (no superado)
      • NOT_STARTED (no iniciado)

 Validaciones

  • Índices erróneos --> Error 416 (Requested Range Not Satisfiable) Usando paginación, ambos índices deben tener un valor
  • Si el plan por id no existe --> Código de error ERR004 (Error 404)
  • Si el plan por external_id no existe --> Código de error ERR005 (Error 404)
  • Si el id dado es erróneo -> Error 404
  • Todo OK --> 200 (OK) + JSON

BODY - application/json

{
    "id": 13234,
    "name": "Plan de API",
    "startDate": "2022-03-03 13:14:09",
    "endDate": null,
    "externalId": "Plan_de_API",
    "students": [
        {
            "id": 7,
            "username": "admin",
            "firstName": "firstName3727",
            "lastName": "lastName3727",
            "email": "admin@netexlearning.com",
            "enrolmentDate": "2022-03-08 12:04:14",
            "passedCourses": 1,
            "passedMandatoryCourses": 1,
            "passedPlanDate": "2022-03-10 11:36:25",
            "status": "PASSED"
        },
        {
            ...
        }
    ]
}