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"
        },
        { 
            ... 
        }
    ]
}