Actualizar un curso

Este endpoint permite actualizar la definición completa de un curso del catálogo, incluida su lista de entrenamientos.

PUT /api/v2/businesses/{businessId}/courses/{courseId}

El courseId es el identificador externo del curso que se quiere actualizar.

A continuación, se expone una explicación detallada de cada uno de los campos que pueden conformar el cuerpo de la petición, siendo algunos de ellos obligatorios para que esta se realice de manera exitosa.

Los campos obligatorios están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON 
{
  "id": "string",
  "name": "string",
  "description": "string",
  "abbreviation": "string",
  "color": "string",
  "expiresAfter": "string",
  "requirementIds": [
    "string"
  ],
  "unlockCatalogLocationIds": [
    "string"
  ],
  "trainings": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "day": 0,
      "order": 0,
      "duration": "string",
      "needsTrainer": false,
      "needsValidation": false,
      "coverCatalogLocationId": "string"
    }
  ]
}
Detalles

  • id: identificador externo del curso. Si no se indica al crear el curso, Orquest genera uno automáticamente. Al actualizar un curso, se ignora y se mantiene el identificador indicado en la URL.

  • name*: nombre del curso. Admite un máximo de 50 caracteres.

  • description: descripción del curso. Admite un máximo de 500 caracteres.

  • abbreviation*: abreviatura del curso. Admite un máximo de 3 caracteres.

  • color*: color con el que se representa el curso, en formato hexadecimal (por ejemplo, #4338CA).

  • expiresAfter: periodo de validez de la aprobación del curso, en formato ISO-8601 (por ejemplo, P1Y para un año o P6M para seis meses). Si no se indica, la aprobación no caduca.

  • requirementIds: lista de identificadores externos de los cursos que el empleado debe tener aprobados y vigentes antes de registrar el resultado de este curso.

  • unlockCatalogLocationIds: lista de identificadores externos de las tareas del catálogo de tareas que el curso habilita una vez aprobado.

  • trainings: lista de entrenamientos que componen el curso. Para cada entrenamiento, se incluye la siguiente información:

    • id: identificador externo del entrenamiento. Debe ser único dentro del curso. Si no se indica, Orquest genera uno automáticamente.

    • name*: nombre del entrenamiento.

    • description: descripción del entrenamiento.

    • day*: día del curso en el que se realiza el entrenamiento. Es un valor relativo que empieza en 1, el día de inicio del curso.

    • order*: orden del entrenamiento dentro de su día.

    • duration*: duración del entrenamiento, en formato ISO-8601 (por ejemplo, PT2H para dos horas o PT90M para noventa minutos). No puede superar un día.

    • needsTrainer: indica si el entrenamiento requiere formador. Por defecto, false.

    • needsValidation: indica si el entrenamiento se evalúa. Si es true, el resultado del entrenamiento es superado o no superado; si es false, solo se registra la asistencia. Por defecto, false.

    • coverCatalogLocationId: identificador externo de la tarea del catálogo que cubre el empleado mientras realiza el entrenamiento.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo de la petición:

PUT /api/v2/businesses/BUSINESSID/courses/CRS-CAJ
{
    "name": "Caja",
    "description": "Medios de pago, operativa TPV, arqueo y devoluciones",
    "abbreviation": "CAJ",
    "color": "#F7C2E5",
    "expiresAfter": "P1Y",
    "requirementIds": [
        "CRS-VAC"
    ],
    "unlockCatalogLocationIds": [
        "000001"
    ],
    "trainings": [
        {
            "id": "TRN-CAJ-NOR",
            "name": "Normativa de caja y medios de pago",
            "day": 1,
            "order": 1,
            "duration": "PT1H",
            "needsTrainer": false,
            "needsValidation": false
        },
        {
            "id": "TRN-CAJ-TPV",
            "name": "Operativa TPV",
            "day": 1,
            "order": 2,
            "duration": "PT4H",
            "needsTrainer": true,
            "needsValidation": false,
            "coverCatalogLocationId": "000001"
        },
        {
            "id": "TRN-CAJ-ARQ",
            "name": "Arqueo y cuadre de caja",
            "day": 2,
            "order": 1,
            "duration": "PT1H",
            "needsTrainer": true,
            "needsValidation": true
        }
    ]
}

Si la petición es correcta, la respuesta será un 200 OK con el curso resultante, con la misma estructura que devuelve Obtener información de un curso.

Consideraciones

La petición sustituye toda la definición del curso: los campos que no se envíen quedan vacíos o con su valor por defecto. El id del cuerpo se ignora y el curso conserva el identificador indicado en la URL.

Los entrenamientos se identifican por su id:

  • Los entrenamientos con un id existente se actualizan.

  • Los entrenamientos nuevos o sin id se crean.

  • Los entrenamientos existentes que no se incluyan en la petición se eliminan del curso.

Versionado del curso

Algunos cambios modifican la estructura del curso: añadir o eliminar entrenamientos, cambiar el day o el order de alguno de ellos o cambiar las tareas de unlockCatalogLocationIds.

Si el curso ya está asignado a algún empleado y el cambio es estructural, Orquest conserva la definición anterior para las asignaciones existentes y aplica la nueva definición solo a las asignaciones que se creen a partir de ese momento. El curso mantiene su identificador externo y la API devuelve siempre la versión vigente.

Los cursos que tienen este curso como requisito y las trayectorias formativas que lo incluyen pasan a utilizar automáticamente la versión vigente actualizada.

Un curso no puede ser requisito de sí mismo, ni directa ni indirectamente a través de otros cursos.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

404 Not Found

Course not found: <courseId>

El courseId indicado en la URL, o alguno de los cursos de requirementIds, no existe en el negocio.

Catalog location not found: <locationId>

Alguna de las tareas indicadas en unlockCatalogLocationIds o en coverCatalogLocationId no existe en el catálogo del negocio.

400 Bad Request

Name cannot be longer than 50 characters

El campo name supera los 50 caracteres.

Description cannot be longer than 500 characters

El campo description supera los 500 caracteres.

Abbreviation cannot be longer than 3 characters

El campo abbreviation supera los 3 caracteres.

For input string: <color> under radix 16

El campo color no es un color hexadecimal válido.

training name is required

Algún entrenamiento no tiene name.

training day is required / training day must be greater than 0

Algún entrenamiento no tiene day o tiene un valor menor que 1.

training order is required

Algún entrenamiento no tiene order.

training duration is required / Duration cannot be longer than 1 day

Algún entrenamiento no tiene duration o su duración supera un día.

Duplicated training outerId in course trainings

Hay varios entrenamientos con el mismo id dentro del curso.

Requirement loop detected for course with id […​]

Los requisitos indicados generan un ciclo, por ejemplo, porque el curso es requisito de sí mismo.

Enlaces de interés

¿Qué es un curso?

¿Qué es una trayectoria formativa?