Cargos

Puestos

GET: Obtener puestos

Descripción del API
Este endpoint permite listar los puestos dentro del sistema. Los puestos representan roles o cargos dentro de un equipo, con información asociada como nombre y equipo al que pertenece.

Endpoint

GET /api/positions

Parámetros de entrada

Atributo	Requerido	Tipo	Descripción	Ejemplo
(sin parámetros de entrada)

JSON de ejemplo (entrada)

{}

Parámetros de salida

Atributo	Tipo	Descripción	Ejemplo
id	integer	Identificador único del puesto	1916
name	string	Nombre del puesto	"Jefe ssoma"
team_id	integer	ID del equipo asociado	1
created_at	timestamp	Fecha y hora de creación	"2023-10-11T04:20:55.000Z"
updated_at	timestamp	Fecha y hora de última actualización	"2023-10-11T04:20:55.000Z"

JSON de ejemplo (salida)

• Respuesta 200 OK:

[
    {
        "id": 1916,
        "name": "Jefe ssoma",
        "team_id": 1,
        "created_at": "2023-10-11T04:20:55.000Z",
        "updated_at": "2023-10-11T04:20:55.000Z"
    },
    {
        "id": 1917,
        "name": "Supervisor de Seguridad",
        "team_id": 1,
        "created_at": "2023-10-12T08:25:10.000Z",
        "updated_at": "2023-10-12T08:25:10.000Z"
    },
    {
        "id": 1918,
        "name": "Coordinador de Salud Ocupacional",
        "team_id": 1,
        "created_at": "2023-10-13T10:30:20.000Z",
        "updated_at": "2023-10-13T10:30:20.000Z"
    }
]

POST: Crear un nuevo cargo

Descripción del API
Este endpoint permite crear una nueva posición en el sistema. Se debe enviar el nombre de la posición. El sistema valida que el nombre no esté ya registrado en el mismo equipo, sin importar las mayúsculas o minúsculas. Si el nombre ya existe, se devolverá un mensaje de error. Si la creación es exitosa, se devuelve un mensaje de éxito con el ID de la posición recién creada.

Método HTTP

POST /api/positions

Parámetros de entrada

Atributo	Requerido	Tipo	Descripción	Ejemplo
name	Sí	String	Nombre del cargo.	"Prueba"

JSON de ejemplo

{
    "name": "Nuevo cargo"
}

Parámetros de salida

Atributo	Tipo	Descripción	Ejemplo
status	String	Estado de la operación, puede ser 'success' o 'error'.	'success'
message	String	Mensaje descriptivo del resultado de la operación.	'Centro de costo creado exitosamente.'
id	Number	ID del cargo creado si la operación fue exitosa.	1

JSON de ejemplo: Caso de éxito

{
  "status": "success",
  "message": "Cargo creado exitosamente.",
  "id": 1
}

JSON de ejemplo: Caso de error (Código ya registrado)

{
  "status": "error",
  "message": "El cargo con el nombre Nuevo cargo ya está registrada en este equipo.",
  "id": 1
}

PUT: Actualizar un cargo

Descripción del API
Este endpoint permite actualizar un cargo existente en el sistema. Se debe enviar el nuevo nombre del cargo (name). El sistema valida que el nombre del cargo no esté registrado en otro cargo dentro del mismo equipo. Si el nombre ya existe en otro cargo, se devolverá un mensaje de error. Si la actualización es exitosa, se devuelve un mensaje de éxito con el ID del cargo actualizado.

Método HTTP

POST /api/positions/{id}

Parámetros de entrada

URL Parameters

Parámetro	Descripción
id	El ID del cargo que se desea actualizar

JSON de ejemplo

{
  "name": "Nuevo Cargo"
}

Parámetros de salida

JSON de ejemplo

{
  "status": "success",
  "message": "Cargo actualizado exitosamente.",
  "id": 1
}

Casos de error

1. Error: El cargo con el nombre ya existe en este equipo

{
  "status": "error",
  "message": "El nombre del cargo ya existe en este equipo.",
  "name": "Nombre del cargo"
}

2. Error: Cargo no encontrado

{
  "status": "error",
  "message": "Cargo con ID 123 no encontrado para el equipo 1.",
  "id": 123
}