Nómina electrónica

1. 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.

2. Emitir una nómina

Emite el documento soporte de pago de nómina electrónica (102) de un trabajador para un periodo. Trevol valida todo el contrato (periodo, trabajador, devengados y deducciones) ANTES de reservar, calcula los totales, numera (prefijo de nómina de la empresa), firma y lo manda a la DIAN. En producción hay un solo 102 por trabajador y por mes (art. 1.5.3.2.2): otro es 409 duplicate_document con existing_id; para cambiarlo usa POST /v1/payroll_adjustments. La empresa debe tener la nómina habilitada ante la DIAN (company_not_enabled, payroll_not_enabled): con una llave live, habilitada; con una test, también el set de pruebas (GET /v1/company → capabilities.payroll). En el set de pruebas de habilitación responde 202 validating en las dos versiones y reintentar no lo reenvía. No hay PDF ni correo: xml, zip y dian_response. Se cobra por empleado. Los datos del trabajador solo salen al dueño de la llave: no van en los webhooks ni en el registro de peticiones, y la respuesta guardada para la idempotencia no los copia.

curl https://api.trevol.si/v1/payrolls \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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"
    }
  }
}'

HTTP/1.1 201 Created
Location: /v1/payrolls/pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b

{
  "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"
}

3. Reemplazar o eliminar: la nota de ajuste

Emite la nota de ajuste de nómina electrónica (103). type: "replace" (Reemplazar) lleva la nómina completa corregida; type: "delete" (Eliminar) solo el predecesor y las notas. El predecessor es una nómina de Trevol (pr_… o pra_…, validada) o una de otra plataforma (number, cune, issue_date); es de la misma empresa y ambiente de la llave, del mismo trabajador, y el último de su cadena. Una nómina eliminada no se ajusta.

Reemplazar: la nómina completa corregida, más type y predecessor.

curl https://api.trevol.si/v1/payroll_adjustments \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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"
  }
}'

Eliminar: solo el predecesor y las notas.

curl https://api.trevol.si/v1/payroll_adjustments \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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"
  ]
}'

4. 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 (quedaría en las direcciones que registran los servidores): 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: 201 cuando la DIAN valida, 422 dian_rejected con document cuando la rechaza, 422 validation_error si Trevol lo rechaza antes de numerar (no se gasta ningún número), 402 sin saldo, y con la DIAN sin contestar un 202 processing (versión 2026-10-22) o un 503 dian_unavailable (2026-10-21). Idempotency-Key es obligatoria al crear o corregir, y external_id es opcional.

5. Rutas

6. Avisos (webhooks)

Salen por cualquier camino. El data es un resumen sin el trabajador ni los montos.

{
  "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "event",
  "type": "payroll.accepted",
  "timestamp": "2026-10-23T14:15:03Z",
  "environment": "live",
  "api_version": "2026-10-22",
  "data": {
    "object": "payroll",
    "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
    "status": "accepted",
    "environment": "live",
    "number": "NE15",
    "prefix": "NE",
    "external_id": "NOM-2026-09-001",
    "origin": "api",
    "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
    "issued_at": "2026-10-23T09:15:02-05:00",
    "type": null,
    "predecessor": null,
    "submission": "sync",
    "dian": {
      "status_code": "00",
      "rules": [
        {
          "code": "NIE038",
          "severity": "notification"
        }
      ]
    }
  }
}

7. Campos

Nómina (cuerpo de POST y PUT)

Periodo (period)

Trabajador (employee)

Lugar de trabajo (employee.workplace)

Pago (payment)

Devengados (earnings)

Deducciones (deductions)

PayrollPlace

PayrollNovelty

PayrollEmployer

PayrollBasic

PayrollTransport

PayrollOvertime

PayrollPaidPeriod

PayrollCompensatedVacation

PayrollVacation

PayrollServiceBonus

PayrollSeverance

PayrollDisability

PayrollUnpaidPeriod

PayrollLeaves

PayrollSalaryAmounts

PayrollOtherConcept

PayrollCompensation

PayrollEpctvBonus

PayrollPercentAmount

PayrollSolidarityFund

PayrollSanction

PayrollLoan

Nota de ajuste (cuerpo)

Documento que se ajusta (predecessor)

• id (obligatorios: id)
• number, cune, issue_date (obligatorios: number, cune, issue_date)