GET

Listar nóminas

Scope:accounting:payrolls.read

https://api.holded.com/api/v2/payslips

Devuelve las nóminas ordenadas por creación, las más recientes primero. La respuesta se pagina por cursor: incluye un valor `cursor` y un booleano `has_more`. Pasa el `cursor` en la siguiente petición para obtener la página siguiente. Una nómina es el recibo de salario que calcula el motor de nóminas de Holded para un periodo de liquidación, con su propio desglose de cotizaciones e IRPF. NO es lo mismo que un registro salarial, que es el apunte contable introducido a mano y que se sirve en `/api/v2/salary-records`. Este endpoint nunca devuelve registros salariales, y `/api/v2/salary-records` nunca devuelve nóminas: elige el endpoint que corresponda al documento que el usuario ha nombrado. Las nóminas solo existen en cuentas que generan nómina con la gema de Recursos Humanos; una cuenta sin esa gema no puede crear nuevas, pero este endpoint sigue devolviendo las que ya tiene. Por tanto, una lista vacía significa o que no hay nóminas en el rango o que la cuenta nunca ha usado nóminas. El filtro `start_date` / `end_date` aplica a la fecha de devengo, no a la fecha de creación ni al periodo de liquidación.

Parámetros

Parámetros de consulta

cursorstringopcional

Cursor de paginación devuelto en la respuesta anterior. Omítelo para empezar por la primera página

limitintegeropcional= 50

Número máximo de nóminas a devolver por página. Por defecto 50, máximo 200

employee_idstringopcional

Filtra por empleado. Acepta el nombre del empleado, que se resuelve a su identificador en el servidor

start_datestring<date-time>opcional

Devuelve las nóminas con fecha de devengo igual o posterior a esta fecha (ISO 8601)

end_datestring<date-time>opcional

Devuelve las nóminas con fecha de devengo igual o anterior a esta fecha (ISO 8601)

kindstringopcional

Filtra por tipo de nómina: `nomina_ordinaria`, `gratificacion_no_cuantificable` o `finiquito`

"nomina_ordinaria""gratificacion_no_cuantificable""finiquito"

is_draftbooleanopcional

Filtra por estado de borrador: `true` devuelve solo las no aprobadas, `false` solo las aprobadas. Omítelo para devolver ambas

Petición

python

import requests

url = "https://api.holded.com/api/v2/payslips?cursor=value&limit=50&employee_id=507f1f77bcf86cd799439012"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Respuestas

Respuesta

json

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "employee_id": "507f1f77bcf86cd799439012",
      "employee_name": "Jane Doe",
      "payslip_kind": "nomina_ordinaria",
      "date": "2024-03-31",
      "period_start": "2024-03-01",
      "period_end": "2024-03-31",
      "total_days": 30,
      "description": "March 2024",
      "tags": [
        "office-madrid"
      ],
      "accounting_account_id": "507f1f77bcf86cd799439013",
      "is_draft": false,
      "net_salary": "1663.00",
      "total_company_cost": "2640.00",
      "payment_total": "1663.00",
      "payment_pending": "0.00",
      "payment_status": "PENDING"
    }
  ],
  "cursor": "string",
  "has_more": true
}

Respuestas exitosas

200Listado de nóminasapplication/json

object

items[]object[]

idstring

Unique identifier of the payslip

employee_idstring | null

Identifier of the employee this payslip belongs to. Null when the employee has been deleted.

employee_namestring

Snapshot of the employee's full name at the time the payslip was created

payslip_kindstring

Kind of payslip: `nomina_ordinaria` (ordinary monthly payslip), `gratificacion_no_cuantificable` (non-quantifiable bonus regularisation) or `finiquito` (final settlement).

Enum:nomina_ordinariagratificacion_no_cuantificablefiniquitoatrasos

datestring<date>

Accrual date of the payslip (ISO 8601)

period_startstring<date> | null

First day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.

period_endstring<date> | null

Last day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.

total_daysinteger

Days paid in the liquidation period

descriptionstring

Free-form description of the payslip

tags[]string[]

List of tags attached to the payslip

accounting_account_idstring | null

Accounting account where the payroll expense is posted

is_draftboolean

Whether the payslip is still a draft. A draft has not been approved and is not posted to the ledger.

net_salarystring

Amount the employee receives (salario neto), as a decimal string. Equals the sum of `earnings` minus the sum of `deductions`.

total_company_coststring

Total cost for the company (gross salary plus employer contributions), as a decimal string.

payment_totalstring

Total amount already paid, as a decimal string

payment_pendingstring

Amount still pending payment, as a decimal string

payment_statusstring

Payment status of the payslip

Enum:PENDINGPAIDPARTIALLY_PAID

cursorstring | null

Opaque cursor pointing to the next page. Pass this value as the `cursor` query parameter in the next request. Null when there is no next page.

has_moreboolean

Whether more pages are available after this one

Respuestas de error

400Solicitud incorrectaapplication/json

401API key inválida o no proporcionadaapplication/json

403Permisos insuficientesapplication/json

429Límite de solicitudes excedidoapplication/json