Endpoints — API de Zelta Nómina

Base URL: https://api.zelta.dev/v1/nomina

Todos los endpoints requieren autenticación mediante token Bearer. Consulta la para obtener tu token.

Empleados

Listar empleados

GET /employees

Parámetros de consulta:

Parámetro	Tipo	Descripción
page	integer	Número de página (default: 1)
per_page	integer	Resultados por página (default: 25, max: 100)
status	string	active, inactive, terminated
department	string	Filtrar por departamento
search	string	Buscar por nombre, RFC o número de empleado
sort_by	string	name, hire_date, department

Ejemplo:

curl -X GET "https://api.zelta.dev/v1/nomina/employees?status=active&department=ventas" \
  -H "Authorization: Bearer {token}"

Respuesta:

{
  "data": [
    {
      "id": "emp_abc123",
      "employee_number": "EMP-001",
      "name": "Juan Pérez García",
      "rfc": "PEGJ900101XXX",
      "curp": "PEGJ900101HDFRRL09",
      "nss": "12345678901",
      "department": "Ventas",
      "position": "Ejecutivo de ventas",
      "hire_date": "2024-03-01",
      "daily_salary": 650.00,
      "integrated_daily_salary": 682.05,
      "status": "active",
      "created_at": "2024-03-01T08:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 25
  }
}

Crear empleado

POST /employees

Cuerpo de la petición:

{
  "name": "María López Hernández",
  "rfc": "LOHM950515XXX",
  "curp": "LOHM950515MDFRRL01",
  "nss": "98765432101",
  "hire_date": "2026-03-15",
  "contract_type": "indeterminate",
  "work_shift": "daytime",
  "department": "Tecnología",
  "position": "Desarrolladora",
  "daily_salary": 850.00,
  "bank": "BBVA",
  "clabe": "012345678901234567"
}

Scope requerido: nomina:write

Obtener empleado

GET /employees/{employee_id}

Actualizar empleado

PATCH /employees/{employee_id}

Dar de baja empleado

POST /employees/{employee_id}/terminate

{
  "termination_date": "2026-03-31",
  "reason": "voluntary_resignation",
  "notes": "Renuncia voluntaria por motivos personales"
}

Scope requerido: nomina:admin

Atención

Dar de baja un empleado genera automáticamente el movimiento de baja ante el IMSS y calcula el finiquito o liquidación correspondiente.

---

Nóminas (Payrolls)

Listar periodos de nómina

GET /payrolls

Parámetros de consulta:

Parámetro	Tipo	Descripción
year	integer	Filtrar por año
month	integer	Filtrar por mes
status	string	draft, calculated, approved, stamped
type	string	ordinary, aguinaldo, ptu, settlement

Respuesta:

{
  "data": [
    {
      "id": "pay_xyz789",
      "period_number": 5,
      "type": "ordinary",
      "frequency": "biweekly",
      "start_date": "2026-03-01",
      "end_date": "2026-03-15",
      "payment_date": "2026-03-15",
      "status": "stamped",
      "total_perceptions": 420000.00,
      "total_deductions": 112500.00,
      "total_net": 307500.00,
      "employees_count": 25
    }
  ]
}

Crear periodo de nómina

POST /payrolls

Calcular nómina

POST /payrolls/{payroll_id}/calculate

Aprobar nómina

POST /payrolls/{payroll_id}/approve

Scope requerido: nomina:admin

Timbrar recibos

POST /payrolls/{payroll_id}/stamp

Scope requerido: nomina:admin

Obtener recibos de un periodo

GET /payrolls/{payroll_id}/receipts

---

Deducciones

Listar deducciones de un empleado

GET /employees/{employee_id}/deductions

Respuesta:

{
  "data": [
    {
      "id": "ded_001",
      "type": "isr",
      "description": "ISR retenido",
      "amount": 1050.75,
      "period": "2026-03-Q1"
    },
    {
      "id": "ded_002",
      "type": "imss",
      "description": "Cuota obrera IMSS",
      "amount": 296.50,
      "period": "2026-03-Q1"
    },
    {
      "id": "ded_003",
      "type": "infonavit",
      "description": "Crédito Infonavit",
      "amount": 500.00,
      "period": "2026-03-Q1"
    }
  ]
}

Registrar deducción voluntaria

POST /employees/{employee_id}/deductions

{
  "type": "savings_fund",
  "description": "Caja de ahorro",
  "amount": 300.00,
  "frequency": "biweekly",
  "start_date": "2026-04-01",
  "end_date": null
}

Actualizar deducción

PATCH /deductions/{deduction_id}

Cancelar deducción

DELETE /deductions/{deduction_id}

---

Reportes

Obtener reporte de nómina

GET /reports/payroll

Parámetros de consulta:

Parámetro	Tipo	Descripción
payroll_id	string	ID del periodo de nómina
format	string	json, pdf, xlsx, csv
type	string	summary, detail, by_department

Obtener reporte de ISR

GET /reports/isr

Parámetro	Tipo	Descripción
year	integer	Ejercicio fiscal
month	integer	Mes (opcional, si se omite retorna anual)
employee_id	string	Filtrar por empleado (opcional)

Obtener reporte de IMSS

GET /reports/imss

Obtener acumulado anual

GET /reports/annual/{employee_id}

{
  "employee_id": "emp_abc123",
  "year": 2026,
  "total_perceptions": 195000.00,
  "total_taxable": 178500.00,
  "total_exempt": 16500.00,
  "total_isr_withheld": 26775.00,
  "total_imss_employee": 7119.00,
  "total_net_paid": 161106.00
}

---

Códigos de respuesta

Código	Descripción
200	Solicitud exitosa
201	Recurso creado exitosamente
204	Recurso eliminado exitosamente
400	Solicitud mal formada
401	No autenticado
403	Sin permisos suficientes
404	Recurso no encontrado
409	Conflicto (ej. nómina ya timbrada)
422	Error de validación
429	Límite de tasa excedido
500	Error interno del servidor

Nota sobre operaciones fiscales

Las operaciones de timbrado (/stamp) y cancelación de CFDI son irreversibles y se comunican directamente con el SAT. Asegúrate de que los datos sean correctos antes de ejecutar estas operaciones.