Crear un curso

Este endpoint permite crear un curso en el catálogo del negocio, junto con todos sus entrenamientos.

POST /api/v2/businesses/{businessId}/courses

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:

POST /api/v2/businesses/BUSINESSID/courses
{
    "id": "CRS-CAJ",
    "name": "Caja",
    "abbreviation": "CAJ",
    "color": "#F7C2E5",
    "description": "Medios de pago, operativa TPV y arqueo",
    "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": "PT3H",
            "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 201 Created con la información del curso creado.

Consideraciones

La petición es atómica: el curso y todos sus entrenamientos se crean juntos o no se crea nada.

Todos los identificadores de la petición son identificadores externos y deben existir en el negocio para que la petición sea válida.

Si no se indica el id del curso o de alguno de sus entrenamientos, Orquest genera un identificador automáticamente y lo devuelve en la respuesta.

La petición no es idempotente: si se repite con el mismo id, devolverá un error de conflicto; si se repite sin id, se creará un curso nuevo en cada llamada con un identificador externo aleatorio.

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>

Alguno de los cursos indicados en 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.

409 Conflict

The request conflicts with data already stored

Ya existe un curso con el id indicado en el negocio.

Enlaces de interés

¿Qué es un curso?

¿Qué es una tarea?