Employee management endpoints

The employee management endpoints let you create new employee accounts, retrieve the full employee roster, and update any profile field for an existing employee. Avatar images are accepted as multipart/form-data; all other fields are sent as JSON. Every endpoint requires a valid JWT bearer token.

List employees

Method: GET
Path: /api/rrhh/empleados
Authentication: Bearer JWT required Returns all employee records stored in the system.

curl -X GET "https://api.marbes.org/api/rrhh/empleados" \
  -H "Authorization: Bearer {token}"

success

boolean

required

true on a successful response.

empledos

object[]

Array of employee records.

Show employee fields

string

UUID of the employee.

nombre

string

First name.

apellido

string

Last name.

cedula_rif

string

National ID or tax ID. Format: V-12345678.

string

Email address (stored in lowercase).

telefono

string

Phone number. Format: 0424-1234567.

cargo

string

Job title.

departamento

string

Department name.

funciones

string[]

List of assigned functions.

canal

string

Slack channel.

code_slack

string

Slack member code.

grupo

string

Group assignment.

avatar

string

Relative path to the avatar image.

estatus

string

Account status: activo, desactivo, or suspendido.

fecha_registro

string

Registration date (ISO 8601).

created_at

string

Record creation timestamp (ISO 8601).

updated_at

string

Last update timestamp (ISO 8601).

200

{
  "success": true,
  "empledos": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "nombre": "María",
      "apellido": "González",
      "cedula_rif": "V-12345678",
      "email": "[email protected]",
      "telefono": "0424-1234567",
      "cargo": "Analista",
      "departamento": "Tecnología",
      "funciones": ["soporte", "desarrollo"],
      "avatar": "uploads/a1b2c3d4/avatar_1700000000000.jpg",
      "estatus": "activo",
      "created_at": "2024-03-01T10:00:00Z",
      "updated_at": "2024-03-15T08:30:00Z"
    }
  ]
}

500

{
  "message": "Error interno del servidor."
}

Create employee

POST /api/rrhh/empleados Creates a new employee account. On success, a Slack notification is posted to the all-equipo-marbes channel.

nombre

string

required

First name. Must start with an uppercase letter.

apellido

string

required

Last name. Must start with an uppercase letter.

cedula_rif

string

required

National ID or tax ID. Formats: V-12345678, E-12345678-9, J-12345678-9.

string

required

Email address. Stored in lowercase.

password

string

required

Plain-text password. Hashed with bcrypt (10 salt rounds) before storage.

telefono

string

Phone number. A leading 0 is added automatically if omitted. Final format: 0424-1234567.

cargo

string

Job title. Stored with title case (e.g., "Desarrollador Senior").

departamento

string

Department name. Stored with title case.

responsable

string

UUID of the employee responsible for this account.

fecha_registro

string

Registration date in ISO 8601 format. Defaults to the current timestamp if omitted.

curl -X POST "https://api.marbes.org/api/rrhh/empleados" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Juan",
    "apellido": "Pérez",
    "cedula_rif": "V-12345678",
    "email": "[email protected]",
    "password": "SecurePass123",
    "telefono": "4241234567",
    "cargo": "desarrollador senior",
    "departamento": "tecnología"
  }'

201

{
  "success": true,
  "message": "Empleado creado exitosamente",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nombre": "Juan",
    "apellido": "Pérez",
    "cedula_rif": "V-12345678",
    "email": "[email protected]",
    "telefono": "0424-1234567",
    "cargo": "Desarrollador Senior",
    "departamento": "Tecnología",
    "estatus": "activo",
    "created_at": "2024-05-06T12:00:00Z"
  }
}

400

{
  "success": false,
  "message": "Los campos nombre, apellido, cedula_rif, email y password son requeridos"
}

401

{
  "success": false,
  "message": "Usuario no autenticado"
}

Edit employee

PUT /api/rrhh/user/editar?userId={userId} Updates one or more fields on an existing employee. All body fields are optional; at least one field (or an avatar file) must be provided. The authenticated user is recorded as update_by.

Avatar uploads use multipart/form-data. When sending only JSON fields, set Content-Type: application/json. When including an avatar, omit the Content-Type header and let your HTTP client set it to multipart/form-data with the correct boundary.

userId

string

required

UUID of the employee to update.

nombre

string

First name. Formatted as title case (first letter uppercase, rest lowercase). No numbers or special characters allowed.

apellido

string

Last name. Same formatting rules as nombre. Example: "Pérez González".

cedula_rif

string

National ID or tax ID. Accepted formats: V-12345678, E-12345678-9, J-12345678-9. Hyphens are inserted automatically (e.g., "V12345678" → "V-12345678").

string

Email address. Converted to lowercase automatically.

telefono

string

Phone number. A leading 0 is added if missing. Minimum 10 digits. Final format: 0424-1234567.

cargo

string

Job title. Formatted as title case (e.g., "desarrollador senior" → "Desarrollador Senior").

departamento

string

Department name. Formatted as title case.

password

string

New password in plain text. Hashed with bcrypt (10 salt rounds) before storage.

estatus

string

Account status. Accepted values: activo, desactivo, suspendido. Converted to lowercase automatically.

avatar

file

Profile image. Sent as multipart/form-data. Accepted types: JPEG, PNG, GIF, WebP. Maximum size: 5 MB. The image is automatically resized to 300 × 300 px and saved to uploads/{userId}/avatar_{timestamp}.jpg. The previous avatar is deleted.

curl -X PUT "https://api.marbes.org/api/rrhh/user/editar?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María",
    "apellido": "González"
  }'

success

boolean

required

true on a successful update.

message

string

Human-readable result message.

data

object

Updated employee record.

Show fields

string

Employee UUID.

nombre

string

First name (formatted).

apellido

string

Last name (formatted).

cedula_rif

string

ID with hyphens.

string

Lowercased email.

telefono

string

Formatted phone number.

cargo

string

Job title (title case).

departamento

string

Department (title case).

avatar

string

Relative path to the avatar file.

estatus

string

Current account status.

updated_at

string

ISO 8601 timestamp of the update.

200

{
  "success": true,
  "message": "Empleado actualizado exitosamente",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nombre": "María",
    "apellido": "González",
    "cedula_rif": "V-12345678",
    "email": "[email protected]",
    "telefono": "0424-1234567",
    "cargo": "Gerente",
    "departamento": "Tecnología",
    "avatar": "uploads/a1b2c3d4/avatar_1700000000123.jpg",
    "estatus": "activo",
    "updated_at": "2024-05-06T14:00:00Z"
  }
}

400 – validation error

{
  "success": false,
  "message": "Formato de cédula/RIF inválido. Use: V-12345678, E-12345678-9, J-12345678-9"
}

400 – no fields provided

{
  "success": false,
  "message": "Debe proporcionar al menos un campo para actualizar"
}

401

{
  "success": false,
  "message": "Usuario no autenticado"
}

500

{
  "success": false,
  "message": "Error interno del servidor"
}

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Employee management endpoints

List employees

Create employee

Edit employee

Build docs developers (and LLMs) love

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​List employees

​Create employee

​Edit employee

Build docs developers (and LLMs) love

List employees

Create employee

Edit employee