Crear

Descripcion general

Este endpoint permite crear uno o varios puestos dentro de tu organización. Acepta tanto un objeto como un arreglo de hasta 100 objetos, y la respuesta refleja la forma del cuerpo enviado. El único campo obligatorio por fila es name; el resto son opcionales. Una solicitud exitosa devuelve 201 con los puestos creados, incluyendo los campos generados por el servidor (id, job_position_number, created_at, updated_at). A diferencia de los departamentos, los puestos no tienen jerarquía: no existen parent_id ni depth, es una creación plana.

En modo lote, si cualquier fila falla la validación, ningún puesto se crea — la respuesta lista los problemas por fila para corregirlos en una sola pasada.

Las bandas salariales (salary_band_min, salary_band_max) se aceptan como números JSON en el cuerpo, pero se serializan como strings decimales en la respuesta (por ejemplo "15000.00") para preservar la precisión.

Endpoint

{ "name": "Vendedor" }

{
  "name": "Gerente de Ventas",
  "code": "GER-VEN",
  "description": "Gerencia comercial",
  "salary_band_min": 15000,
  "salary_band_max": 35000,
  "is_active": true,
  "sort_order": 0
}

[
  { "name": "Vendedor", "code": "VEN" },
  { "name": "Cajero", "code": "CAJ" },
  { "name": "Almacenista", "code": "ALM", "salary_band_min": 8000, "salary_band_max": 12000 }
]

Reglas de los campos

El puesto no lleva clase de riesgo IMSS: si envías risk_class, con cualquier valor, la respuesta es 400 con ese campo. La clase de riesgo se captura en el registro patronal.

Forma de las respuestas

201 — solicitud única

Cuando el cuerpo es un objeto, la respuesta es el objeto del puesto creado.

{
  "id": "ck...",
  "job_position_number": 5,
  "name": "Gerente de Ventas",
  "code": "GER-VEN",
  "description": "Gerencia comercial",
  "salary_band_min": "15000.00",
  "salary_band_max": "35000.00",
  "is_active": true,
  "sort_order": 0,
  "created_at": "2026-05-24T10:00:00.000Z",
  "updated_at": "2026-05-24T10:00:00.000Z"
}

201 — solicitud por lote

Cuando el cuerpo es un arreglo, la respuesta envuelve los resultados en summary + created[].

{
  "summary": { "total": 3, "created": 3 },
  "created": [
    { "id": "ck...", "job_position_number": 6, "name": "Vendedor", "...": "..." },
    { "id": "ck...", "job_position_number": 7, "name": "Cajero", "...": "..." },
    { "id": "ck...", "job_position_number": 8, "name": "Almacenista", "...": "..." }
  ]
}

Errores

400 — validación fallida (solicitud única)

Para fallas de validación de esquema (campo faltante, tipo incorrecto), errors es un objeto indexado por campo:

{
  "message": "Validation failed.",
  "errors": { "name": ["Ingresa el nombre."] }
}

400 — validación fallida (solicitud por lote)

Reporte por fila. Ningún puesto del lote fue creado.

{
  "message": "Validation failed for 2 job position(s). No job positions were created.",
  "summary": { "total": 3, "with_errors": 2 },
  "errors": [
    {
      "index": 0,
      "job_position": { "name": "Vendedor", "code": "VEN" },
      "issues": [
        {
          "field": "code",
          "code": "DUPLICATE_CODE",
          "message": "A job position with code 'VEN' already exists in this organization."
        }
      ]
    },
    {
      "index": 2,
      "job_position": { "name": "Cobranza", "code": "VEN" },
      "issues": [
        {
          "field": "code",
          "code": "DUPLICATE_CODE_IN_BATCH",
          "message": "Code 'VEN' appears multiple times in this batch."
        }
      ]
    }
  ]
}

• index — posición 0-based de la fila que falló dentro del arreglo enviado.
• job_position.name / job_position.code — extraídos de tu entrada para que identifiques la fila sin contar.
• issues[] — todos los problemas de esa fila listados juntos para corregirlos antes de reintentar.

409 — condición de carrera

Otra solicitud reclamó un code entre el momento en que validamos el tuyo y el momento en que escribimos. En modo lote, la transacción completa hace rollback — ningún puesto es creado. Reintenta la misma solicitud.

Vocabulario de códigos de error

Estos códigos aparecen dentro de issues[].code (o como code en el cuerpo de error en single) y son estables — tu cliente puede ramificar lógica con base en ellos: