Nómina electrónica

Nómina electrónica (102) y su nota de ajuste (103, Reemplazar y Eliminar) por la API de Trevol.

Emite el documento soporte de pago de nómina electrónica (102) de cada trabajador y, si hay que cambiarlo, su nota de ajuste (103): Reemplazar o Eliminar. Trevol calcula los totales, numera, firma y envía a la DIAN.

Antes de emitir

La nómina de la empresa tiene que estar habilitada ante la DIAN (en la app: Nómina → Configurar habilitación). Con una llave de producción (tvl_live_…) debe estar habilitada; con una de pruebas basta con el set de pruebas registrado. GET /v1/company → capabilities.payroll.status dice enabled, testing, not_registered o not_enabled para el ambiente de tu llave. Si no, 422 company_not_enabled con reason: "payroll_not_enabled", antes de numerar.
Los prefijos de la nómina (capabilities.payroll.prefixes) se cambian en la app.

Emitir una nómina

POST /v1/payrolls

cURL

curl -X POST "https://api.trevol.si/v1/payrolls" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "NOM-2026-09-001",
  "period": {
    "hire_date": "2024-03-01",
    "start": "2026-09-01",
    "end": "2026-09-30"
  },
  "pay_period": "5",
  "notes": [
    "Nómina de septiembre de 2026"
  ],
  "employee": {
    "type": "01",
    "subtype": "00",
    "high_risk_pension": false,
    "document_type": "13",
    "document_number": "1000000101",
    "first_surname": "PRUEBA",
    "second_surname": "NOMINA01",
    "first_name": "TRABAJADOR",
    "other_names": "DE PRUEBA",
    "workplace": {
      "country": "CO",
      "municipality_code": "76001",
      "address": "Calle 1 # 1-1"
    },
    "integral_salary": false,
    "contract_type": "2",
    "salary": "1423500",
    "code": "TRAB-01"
  },
  "payment": {
    "form": "1",
    "method": "42",
    "bank": "Banco de Pruebas",
    "account_type": "Ahorros",
    "account_number": "0001234501"
  },
  "payment_dates": [
    "2026-09-30"
  ],
  "earnings": {
    "basic": {
      "days": 30,
      "amount": "1423500"
    },
    "transport": [
      {
        "allowance": "200000"
      }
    ]
  },
  "deductions": {
    "health": {
      "percent": "4",
      "amount": "56940"
    },
    "pension": {
      "percent": "4",
      "amount": "56940"
    }
  }
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "payroll",
  "environment": "live",
  "status": "accepted",
  "number": "NE15",
  "prefix": "NE",
  "external_id": "NOM-2026-09-001",
  "origin": "api",
  "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "submission": "sync",
  "period": {
    "hire_date": "2024-03-01",
    "start": "2026-09-01",
    "end": "2026-09-30"
  },
  "pay_period": "5",
  "currency": "COP",
  "notes": [
    "Nómina de septiembre de 2026"
  ],
  "employee": {
    "type": "01",
    "subtype": "00",
    "high_risk_pension": false,
    "document_type": "13",
    "document_number": "1000000101",
    "first_surname": "PRUEBA",
    "second_surname": "NOMINA01",
    "first_name": "TRABAJADOR",
    "other_names": "DE PRUEBA",
    "workplace": {
      "country": "CO",
      "municipality_code": "76001",
      "address": "Calle 1 # 1-1"
    },
    "integral_salary": false,
    "contract_type": "2",
    "salary": "1423500",
    "code": "TRAB-01"
  },
  "payment": {
    "form": "1",
    "method": "42",
    "bank": "Banco de Pruebas",
    "account_type": "Ahorros",
    "account_number": "0001234501"
  },
  "payment_dates": [
    "2026-09-30"
  ],
  "earnings": {
    "basic": {
      "days": 30,
      "amount": "1423500"
    },
    "transport": [
      {
        "allowance": "200000"
      }
    ]
  },
  "deductions": {
    "health": {
      "percent": "4",
      "amount": "56940"
    },
    "pension": {
      "percent": "4",
      "amount": "56940"
    }
  },
  "totals": {
    "earnings": "1623500.00",
    "deductions": "113880.00",
    "net": "1509620.00"
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "files": {
    "xml": true,
    "zip": true,
    "dian_response": true
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Reemplazar o eliminar: la nota de ajuste

Reemplazar: la nómina completa corregida, más type y predecessor. Eliminar: solo el predecesor y las notas.

POST /v1/payroll_adjustments

cURL

curl -X POST "https://api.trevol.si/v1/payroll_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "NOM-2026-09-001-R",
  "period": {
    "hire_date": "2024-03-01",
    "start": "2026-09-01",
    "end": "2026-09-30"
  },
  "pay_period": "5",
  "notes": [
    "Nómina de septiembre de 2026"
  ],
  "employee": {
    "type": "01",
    "subtype": "00",
    "high_risk_pension": false,
    "document_type": "13",
    "document_number": "1000000101",
    "first_surname": "PRUEBA",
    "second_surname": "NOMINA01",
    "first_name": "TRABAJADOR",
    "other_names": "DE PRUEBA",
    "workplace": {
      "country": "CO",
      "municipality_code": "76001",
      "address": "Calle 1 # 1-1"
    },
    "integral_salary": false,
    "contract_type": "2",
    "salary": "1423500",
    "code": "TRAB-01"
  },
  "payment": {
    "form": "1",
    "method": "42",
    "bank": "Banco de Pruebas",
    "account_type": "Ahorros",
    "account_number": "0001234501"
  },
  "payment_dates": [
    "2026-09-30"
  ],
  "earnings": {
    "basic": {
      "days": 30,
      "amount": "1423500"
    },
    "transport": [
      {
        "allowance": "210000"
      }
    ]
  },
  "deductions": {
    "health": {
      "percent": "4",
      "amount": "56940"
    },
    "pension": {
      "percent": "4",
      "amount": "56940"
    }
  },
  "type": "replace",
  "predecessor": {
    "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  }
}'

Probar en el Playground

POST /v1/payroll_adjustments

cURL

curl -X POST "https://api.trevol.si/v1/payroll_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "NOM-2026-09-001-E",
  "type": "delete",
  "predecessor": {
    "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "notes": [
    "Enviada por error"
  ]
}'

Probar en el Playground

Lo que hay que saber

Un 102 por trabajador y por mes en producción. Otro igual es 409 duplicate_document (con existing_id, solo de la misma empresa y ambiente); para cambiarlo se usa la nota de ajuste. Dos pedidos simultáneos del mismo trabajador y mes no pasan los dos.
Set de pruebas. En habilitación con el set pendiente, la respuesta es 202 con status: "validating" en las dos versiones; reintentar con la misma clave o POST …/send no lo reenvía, y PUT en ese estado es 409 invalid_state.
Sin PDF ni correo. Se descargan …/xml, …/zip y …/dian_response.
Datos del trabajador. Solo salen en las respuestas de tu llave. Los avisos (webhooks) llevan un resumen sin trabajador ni montos, el registro de peticiones no guarda cuerpos, y lo que se guarda para repetir una Idempotency-Key es solo {id, object, status, number}. Por eso no se puede filtrar por la cédula: las listas se filtran por employee_code (tu código interno del empleado), external_id y period_end_from / period_end_to.
El second_surname del trabajador es obligatorio.
El external_id es único entre las nóminas y sus ajustes (aparte de las facturas).
Cobro por empleado: cada nómina o nota de ajuste de producción se cobra con la lista de nómina del canal API; la habilitación no cobra.

Las respuestas son las de toda la API. Referencia: Nómina electrónica y sus ajustes.