Registrar una vacante

Este endpoint permite crear una vacante y hacerla pública para los empleados indicados en la petición.

POST /api/v1/businesses/{businessId}/vacancies

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

Cuerpo de la petición

Análisis del JSON 
{
  "id": "string",
  "product": "string",
  "day": "yyyy-MM-dd",
  "expiration": "yyyy-MM-ddTHH:mm:ssXXX",
  "employees": [
    "string",
    "string"
  ],
  "shifts": [
    {
      "start": "yyyy-MM-ddTHH:mm:ssXXX",
      "end": "yyyy-MM-ddTHH:mm:ssXXX"
    }
  ],
  "publishToSiblings": false
}
Detalles

  • id*: identificador externo de la vacante.

  • product*: identificador externo del producto vinculado con la vacante.

  • day*: día para el que se publica la vacante en formato yyyy-MM-dd.

  • expiration*: fecha límite para postular a la vacante. Una vez que ha pasado esa fecha, no se aceptarán solicitudes para la vacante. Se debe enviar en formato yyyy-MM-ddTHH:mm:ssXXX, con zona horaria en forma de offset (+02:00) o Z para UTC. No puede ser anterior a la fecha y hora actuales.

  • employees*: listado de identificadores externos de los empleados a los que se notificará la publicación de la vacante.

  • shifts*: lista de turnos definidos para la vacante (1 o 2 como máximo). Incluye, para cada intervalo, los siguientes campos:

    • start*: inicio del turno en formato yyyy-MM-ddTHH:mm:ssXXX. La zona horaria debe especificarse mediante un offset (por ejemplo, +02:00) o Z (UTC). Debe coincidir con la fecha para la que se publica la vacante.

    • end*: fin del turno en formato yyyy-MM-ddTHH:mm:ssXXX. La zona horaria debe especificarse mediante un offset (por ejemplo, +02:00) o Z (UTC). Puede ser posterior a la fecha para la que se publica la vacante, por ejemplo, en turnos que terminan después de las 00:00.

  • publishToSiblings: determina si la vacante se oferta también a empleados que cuelgan del mismo nodo organizativo (true), en lugar de restringirse únicamente al producto indicado. Por defecto es false.

Ejemplo de la petición

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

{
  "id": "2f14p",
  "product": "0001-G",
  "day": "2026-07-24",
  "expiration": "2026-07-23T04:00:00Z",
  "employees": [
    "1006370","2677189"
  ],
  "shifts": [
    {
      "start": "2026-07-24T18:00:00Z",
      "end": "2026-07-24T19:00:00Z"
    },
    {
      "start": "2026-07-24T21:00:00Z",
      "end": "2026-07-25T03:00:00Z"
    }
  ],
  "publishToSiblings": true
}

Si los datos son correctos, la vacante se publicará y será visible en el apartado de Planificación > Oferta de turnos vacantes.

Aspectos que tener en cuenta

Los turnos (shifts) deben coincidir con el día para el que se publica la vacante (day). El campo to puede ser posterior en turnos que terminan después de las 00:00.

Las horas se deben enviar en UTC o con la zona horaria correspondiente y la publicación se realiza considerando el huso horario del servicio.

No se valida el solape con otras vacantes o asignaciones existentes en el mismo día y turno — solo se comprueban incidencias (arriba) y, si aplica, la pertenencia al producto.

Los siblings de un producto son los demás productos que cuelgan del mismo nodo en la estructura organizativa.

Se pueden publicar diferentes vacantes para la misma fecha e intervalo siempre que los identificadores externos no coincidan.

Códigos de error

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

Código Mensaje Descripción

400 Bad Request

Id is required / Product is required / Day is required / Expiration is required / Employee ids are required

Falta alguno de los campos obligatorios.

Employee ids cannot be empty

El campo employees viene vacío.

Expiration can not be before now

La fecha expiration es anterior al momento actual.

Shifts must be less or equal than 2

Se han indicado más de dos turnos.

Start is required / End is required / Start must be after day / End must be after day / Start date for a Shift must be included in the day / End date for a Shift must be included in the day or in the next day / Shift has a wrong date range

Alguno de los turnos (shifts) no cumple el formato o el rango esperado respecto a day.

Employees do not belong to product <id>: [ids]

Con "publishToSiblings": false, alguno de los empleados indicados no pertenece al producto de la vacante.

Vacancy already exists

El identificador externo (id) ya está en uso por otra vacante.

Any of the employees has an incidence overlapping with the vacancy

Alguno de los empleados indicados tiene una incidencia que solapa con la vacante.

Enlaces de interés

¿Qué es una vacante?