El recurso payrolls te permite gestionar las nóminas de tus empleados. Puedes crear nóminas, consultarlas, actualizarlas, eliminarlas y registrar sus pagos.

Las nóminas en FacturaDirecta registran la información contable de las percepciones del empleado, las retenciones de IRPF y las cotizaciones a la Seguridad Social.

💡 Recomendación: Antes de empezar a desarrollar, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras llamadas sin afectar tus datos reales.

Endpoints disponibles

Método	Endpoint	Descripción
GET	/{companyId}/payrolls	Lista de nóminas (con filtros y paginación)
POST	/{companyId}/payrolls	Crear una nómina
GET	/{companyId}/payrolls/{id}	Obtener una nómina por ID
PUT	/{companyId}/payrolls/{id}	Actualizar una nómina
DELETE	/{companyId}/payrolls/{id}	Eliminar una nómina
POST	/{companyId}/payrolls/{id}/payments	Registrar pagos de la nómina
PUT	/{companyId}/payrolls/{id}/tags	Actualizar etiquetas de la nómina

Ejemplos de código

Nómina básica

Una nómina típica con percepción salarial, retención IRPF del trabajador y cotizaciones a la Seguridad Social.

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "payroll",
      "main": {
        "date": "2026-01-31",
        "contact": "con_40000000-0000-4000-8000-000000000000",
        "modelo190": {
          "clavePercepcion": "A"
        },
        "lines": [
          {
            "type": "debit",
            "label": "Percepción salarial",
            "account": "640000",
            "lineTotal": 2000
          },
          {
            "type": "ss_employee",
            "label": "Aportación Seg.Soc. trabajador",
            "account": "476000",
            "base": 2000,
            "lineTotal": 120
          },
          {
            "type": "irpf_employee",
            "label": "Retenciones IRPF (Percepciones dinerarias)",
            "account": "475100",
            "base": 2000,
            "lineTotal": 240
          },
          {
            "type": "ss_company",
            "label": "Aportaciones Cotización Seg.Soc. Empresa",
            "account": "642000",
            "base": 2000,
            "lineTotal": 600
          }
        ]
      }
    }
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/payrolls

Desglose:

Salario bruto: 2.000€
Seg. Social trabajador (6%): -120€
IRPF (12%): -240€
Neto a pagar: 1.640€
Coste Seg. Social empresa (30%): 600€
Coste total empresa: 2.600€

Nómina con pago registrado

Crea la nómina y registra el pago en un solo paso.

{
  "content": {
    "type": "payroll",
    "main": {
      "date": "2026-01-31",
      "contact": "con_40000000-0000-4000-8000-000000000000",
      "modelo190": {
        "clavePercepcion": "A"
      },
      "lines": [
        {
          "type": "debit",
          "label": "Percepción salarial",
          "account": "640000",
          "lineTotal": 2000
        },
        {
          "type": "ss_employee",
          "label": "Aportación Seg.Soc. trabajador",
          "account": "476000",
          "base": 2000,
          "lineTotal": 120
        },
        {
          "type": "irpf_employee",
          "label": "Retenciones IRPF",
          "account": "475100",
          "base": 2000,
          "lineTotal": 240
        },
        {
          "type": "ss_company",
          "label": "Aportaciones Cotización Seg.Soc. Empresa",
          "account": "642000",
          "base": 2000,
          "lineTotal": 600
        }
      ]
    }
  },
  "payments": [
    {
      "bank": "ban_10000000-0000-4000-8000-000000000000"
    }
  ]
}

Campos importantes

Campos del objeto main

Campo	Tipo	Descripción
contact	string	ID del empleado (obligatorio)
date	string	Fecha de la nómina (formato YYYY-MM-DD)
lines	array	Líneas de la nómina (obligatorio)
modelo190	object	Información para el modelo 190 de IRPF

Tipos de líneas de nómina

Cada línea debe indicar su tipo para la correcta contabilización:

Tipo	Descripción	Cuenta típica
debit	Percepciones salariales (sueldos, complementos)	640000
ss_employee	Aportación a Seg. Social del trabajador	476000
irpf_employee	Retención IRPF del trabajador	475100
ss_company	Cotización a Seg. Social de la empresa	642000

Campos de cada línea

Campo	Tipo	Descripción
type	string	Tipo de línea (ver tabla anterior)
label	string	Descripción de la línea
account	string	Cuenta contable
base	number	Base de cálculo (para retenciones y cotizaciones)
lineTotal	number	Importe de la línea

Campos del modelo 190

Campo	Tipo	Descripción
clavePercepcion	string	Clave de percepción para el modelo 190 de IRPF

Claves de percepción comunes:

A: Rendimientos del trabajo por cuenta ajena
B: Pensiones y haberes pasivos
C: Prestaciones por desempleo

Registrar pagos

Puedes registrar el pago de una nómina existente con el endpoint de pagos:

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "payments": [
      {
        "bank": "ban_xxxxx",
        "date": "2026-01-31"
      }
    ]
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/payrolls/pay_xxxxx/payments

Errores comunes

Error: "contact is required"

El campo contact es obligatorio. Asegúrate de incluir el ID de un empleado existente.

Error: "contact must be an employee"

El contacto indicado no tiene el rol de empleado. Verifica que el contacto sea un empleado.

Error: "lines must have at least 1 item"

Una nómina necesita al menos una línea. Verifica que el array lines no está vacío.

API: Nóminas (payrolls)