GET

Obtener una nómina

Scope:accounting:payrolls.read

https://api.holded.com/api/v2/payslips/{payslipId}

Devuelve una nómina con el desglose que ha calculado el motor de nóminas: líneas de devengo, deducciones, aportaciones de empresa, las bases de cotización y el neto que percibe el empleado. Una nómina NO es un registro salarial, que se sirve en `/api/v2/salary-records`. Los identificadores de ambos son indistinguibles, así que si pides aquí el id de un registro salarial la respuesta es 404 indicando el recurso que sí lo sirve. Los importes y los porcentajes son strings decimales. El porcentaje se expresa como número, así que "12.50" significa 12,5%.

Parámetros

Parámetros de ruta

payslipIdstringobligatorio

ID de la nómina (ObjectId hexadecimal de 24 caracteres)

Petición

python

import requests

url = "https://api.holded.com/api/v2/payslips/507f1f77bcf86cd799439011"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

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

Respuestas

Respuesta

json

{
  "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",
  "is_ex_employee": false,
  "irpf_rate": "12.50",
  "extra_payments_prorata": "0.00",
  "bases": [
    {
      "concept": "cotizacion_contingencias_comunes",
      "amount": "2000.00"
    }
  ],
  "earnings": [
    {
      "name": "Salario base",
      "payroll_item_id": "earning.salario_base",
      "units": "30.00",
      "price": "50.00",
      "amount": "1500.00",
      "bases": [
        "cotizacion_contingencias_comunes"
      ],
      "is_remuneration": true,
      "is_paid_by_company": true
    }
  ],
  "deductions": [
    {
      "type": "contribution",
      "concept": "contingencias_comunes",
      "payroll_item_id": "deduction.anticipo_semanal",
      "name": "Anticipo",
      "units": "string",
      "price": "string",
      "percentage": "4.70",
      "amount": "94.00"
    }
  ],
  "company_contributions": [
    {
      "concept": "contingencias_comunes",
      "name": "Contingencias comunes",
      "base": "2000.00",
      "percentage": "23.60",
      "amount": "472.00"
    }
  ],
  "payments": [
    {
      "id": "507f1f77bcf86cd799439011",
      "amount": "1450.00",
      "date": "2026-02-01",
      "bank_account_id": "507f1f77bcf86cd799439012"
    }
  ]
}

Respuestas exitosas

200Nómina encontradaapplication/json

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

is_ex_employeeboolean

Whether the employee has since left the company

irpf_ratestring

Income tax rate applied, as a decimal string percentage (e.g. "12.50" means 12.5%)

extra_payments_proratastring

Share of the extra payments (pagas extra) accrued in this period, as a decimal string

bases[]object[]

Contribution and tax bases the payslip was computed on, one row per base. On a bonus regularisation (`gratificacion_no_cuantificable`) they come from the bases the employee has accumulated over the year, not from the lines in this payslip, so a line can feed one base while another still carries an amount.

conceptstring

Base identifier, the same values used by `earnings[].bases`

Enum:cotizacion_contingencias_comunescotizacion_at_eptributacion_irpf

amountstring

Base amount, as a decimal string

earnings[]object[]

Earning lines (percepciones). `amount` is the line total; `units` and `price` are only set on lines computed from a quantity.

namestring

Concept name as stored on the payslip

payroll_item_idstring | null

Opaque identifier of the payroll concept: treat it as a string and do not parse it. Concepts from the Holded catalogue use a `<type>.<id>` key such as `earning.salario_base`, and concepts an account creates are usually 24-character ObjectIds, but neither shape is guaranteed and neither tells you which of the two it is.

unitsstring | null

Units the line is computed from, as a decimal string

pricestring | null

Amount per unit, as a decimal string

amountstring

Line total, as a decimal string

bases[]string[]

Contribution and tax bases this line feeds

is_remunerationboolean

Whether the line is remuneration (percepción salarial)

is_paid_by_companyboolean

Whether the company pays this line, as opposed to social security

deductions[]object[]

Deduction lines. Every `amount` is a positive magnitude to subtract, so `net_salary` equals the sum of `earnings` minus the sum of this array. `type` tells them apart: `discount` is a deduction entered on the payslip, `contribution` is an employee social-security contribution and `retention` is the income tax withheld. On a bonus regularisation (`gratificacion_no_cuantificable`) an amount is the difference against what the employee already contributed over the year, so it may not equal `base` times `percentage`.

typestring

Deduction family

Enum:discountcontributionretention

conceptstring | null

Stable concept key. Set on `contribution` and `retention` lines, null on `discount` lines, which carry `payroll_item_id` instead.

payroll_item_idstring | null

Opaque identifier of the payroll concept, set on `discount` lines: treat it as a string and do not parse it. It may be a `<type>.<id>` catalogue key or a 24-character ObjectId, and the shape is not part of the contract.

namestring | null

Human-readable concept name in the account language. Null when the concept has no label available.

unitsstring | null

Units the line is computed from, as a decimal string

pricestring | null

Amount per unit, as a decimal string

percentagestring | null

Rate applied, as a decimal string percentage. Null when the domain exposes no rate for the concept.

amountstring

Deducted amount as a positive decimal string

company_contributions[]object[]

Employer social-security contributions, one row per concept. Every row carries its own amount, so the array sums with no double counting.

conceptstring

Stable contribution concept key

Enum:contingencias_comunesmeiaccidentes_de_trabajo_y_enfermedad_profesionaldesempleofogasaformacion_profesionalcotizacion_solidaridad

namestring | null

Human-readable concept name in the account language. Null when the concept has no label available.

basestring | null

Base the contribution is computed on, as a decimal string

percentagestring | null

Rate applied, as a decimal string percentage. Null when the domain exposes no rate for the concept.

amountstring

Contribution amount, as a decimal string

payments[]object[]

Payments registered against this payslip. Empty when nothing has been paid yet. `id` is the only place a payment id is exposed, and it is what `DELETE /api/v2/payslips/{payslipId}/payments/{paymentId}` takes. The order of this array is not part of the contract: identify a payment by its `amount` and `date`, never by its position.

idstring

Payment identifier (24-character hexadecimal ObjectId)

amountstring

Amount paid, as a decimal string

datestring<date>

Payment date

bank_account_idstring | null

Treasury account the payment is tied to. Null when the payment was registered without one.

Respuestas de error

401API key inválida o no proporcionadaapplication/json

403Permisos insuficientesapplication/json

404Nómina no encontradaapplication/json

429Límite de solicitudes excedidoapplication/json