Saltar la navegación de la documentación

Español API 2026-10-22

Documentación · Referencia · API v1 · versión 2026-10-22

Notas de ajuste de nómina

Las operaciones de Notas de ajuste de nómina de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Documento soporte de pago de nómina electrónica (102) y su nota de ajuste (103: Reemplazar o Eliminar). Un 102 por trabajador y por mes en producción (y en habilitación cuando la empresa ya pasó el set de pruebas). Sin PDF ni correo: xml, zip y dian_response. El trabajador solo sale al dueño de la llave.

Los ejemplos son peticiones con cURL. La llave va en TREVOL_API_KEY; los cuerpos de ejemplo son los de la especificación. Los errores comunes están en Errores.

Emitir una nota de ajuste de nómina

POST /v1/payroll_adjustments · createPayrollAdjustment

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.

Respuestas. 201 la DIAN lo validó (status: accepted). 202 solo en la versión 2026-10-22: la DIAN no contestó (processing), otra petición lo está enviando (sending) o, en habilitación, el set de pruebas todavía lo valida (validating, en las dos versiones); trae Location y Retry-After, y el resultado llega por GET y por webhook: no crees otro documento para la misma operación. 422 validation_error (se revisó a fondo ANTES de reservar: no se gastó el número, y errors[] dice el campo), dian_rejected (con document y las reglas traducidas; corrige con PUT y el mismo número), company_not_enabled o numbering_unavailable (con reason). 402 insufficient_balance (producción sin saldo: queda pending con su número). 409 external_id_in_use o duplicate_document (con existing_id). 503 dian_unavailable en la 2026-10-21. Pide Idempotency-Key: repetir la misma devuelve lo mismo sin enviar nada.

Parámetros

Idempotency-Keycabeceratextoobligatorio
Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).

Cuerpo (PayrollAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos).
typereplace | deleteobligatorio
"replace" (Reemplazar: el ajuste lleva todos los datos de la nómina menos novelty) o "delete" (Eliminar: solo predecessor, notes, generation_place y employer).
predecessorPayrollReferenceobligatorio
El documento que se ajusta: {"id": "pr_…"} (una nómina de Trevol) o {"id": "pra_…"} (otro ajuste, el último de la cadena), o sus datos {number, cune, issue_date}.
periodPayrollPeriod
pay_periodtexto
currencytexto
exchange_ratedecimal
Número o texto decimal con punto («150000.50»).
noteslista de texto
Máximo 20.
employeePayrollEmployee
paymentPayrollPayment
payment_dateslista de fecha (AAAA-MM-DD)
Máximo 31.
earningsPayrollEarnings
deductionsPayrollDeductions
roundingdecimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
generation_placePayrollPlace
employerPayrollEmployer

Respuestas

Estado	Qué pasó
201	El documento (PayrollAdjustment)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`). (PayrollAdjustment)
402	Error (application/problem+json) (Problem)
409	Error (application/problem+json) (Problem)
422	Error (application/problem+json) (Problem)
429	Error (application/problem+json) (Problem)
503	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

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

Calcular una nota de ajuste de nómina sin emitirla

POST /v1/payroll_adjustments/preview · previewPayrollAdjustment

Valida y calcula la nota de ajuste sin reservar un número ni enviar nada.

Cuerpo (PayrollAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos).
typereplace | deleteobligatorio
"replace" (Reemplazar: el ajuste lleva todos los datos de la nómina menos novelty) o "delete" (Eliminar: solo predecessor, notes, generation_place y employer).
predecessorPayrollReferenceobligatorio
El documento que se ajusta: {"id": "pr_…"} (una nómina de Trevol) o {"id": "pra_…"} (otro ajuste, el último de la cadena), o sus datos {number, cune, issue_date}.
periodPayrollPeriod
pay_periodtexto
currencytexto
exchange_ratedecimal
Número o texto decimal con punto («150000.50»).
noteslista de texto
Máximo 20.
employeePayrollEmployee
paymentPayrollPayment
payment_dateslista de fecha (AAAA-MM-DD)
Máximo 31.
earningsPayrollEarnings
deductionsPayrollDeductions
roundingdecimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
generation_placePayrollPlace
employerPayrollEmployer

Respuestas

Estado	Qué pasó
200	Totales (Preview)
Error	Error (application/problem+json) (Problem)

POST /v1/payroll_adjustments/preview

cURL

curl -X POST "https://api.trevol.si/v1/payroll_adjustments/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -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

Reenviar una pendiente o en error

POST /v1/payroll_adjustments/{id}/send · sendPayrollAdjustment

Vuelve a enviar una nota de ajuste pending o error.

Sin cuerpo. Con un documento accepted responde 200 con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (202); con uno rejected es 409 invalid_state (se corrige con PUT). No pide Idempotency-Key (reintentarlo es seguro).

Respuestas

Estado	Qué pasó
200	El documento (PayrollAdjustment)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`). (PayrollAdjustment)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

POST /v1/payroll_adjustments/{id}/send

cURL

curl -X POST "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/send" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Listar (nota de ajuste de nómina)

GET /v1/payroll_adjustments · listPayrollAdjustments

Paginación por cursor y los mismos filtros de GET /v1/payrolls (sin documento del trabajador).

Parámetros

limitconsultaentero
starting_afterconsultatexto
statusconsultatexto
external_idconsultatexto
created_fromconsultatexto
created_toconsultatexto
employee_codeconsultatexto
period_end_fromconsultafecha (AAAA-MM-DD)
period_end_toconsultafecha (AAAA-MM-DD)

Respuestas

Estado	Qué pasó
200	{object: list, data, has_more, next_cursor} (objeto)
Error	Error (application/problem+json) (Problem)

GET /v1/payroll_adjustments

cURL

curl "https://api.trevol.si/v1/payroll_adjustments?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Una nota de ajuste de nómina

GET /v1/payroll_adjustments/{id} · retrievePayrollAdjustment

La nota de ajuste, con type y predecessor (con el prefijo de la clase de su predecesor). El Eliminar no trae trabajador, devengados ni deducciones.

Respuestas

Estado	Qué pasó
200	El documento (PayrollAdjustment)
Error	Error (application/problem+json) (Problem)

GET /v1/payroll_adjustments/{id}

cURL

curl "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Archivo xml

GET /v1/payroll_adjustments/{id}/xml · downloadPayrollAdjustmentXml

El XML firmado que se mandó a la DIAN (application/xml).

Respuestas

Estado	Qué pasó
200	xml (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/payroll_adjustments/{id}/xml

cURL

curl "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o payroll_adjustment_xml.xml

Probar en el Playground

Archivo zip

GET /v1/payroll_adjustments/{id}/zip · downloadPayrollAdjustmentZip

El ZIP del documento (application/zip).

Respuestas

Estado	Qué pasó
200	zip (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/payroll_adjustments/{id}/zip

cURL

curl "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o payroll_adjustment_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/payroll_adjustments/{id}/dian_response · downloadPayrollAdjustmentDianResponse

El ApplicationResponse con que la DIAN contestó (application/xml), si la DIAN lo devolvió.

Respuestas

Estado	Qué pasó
200	dian_response (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/payroll_adjustments/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o payroll_adjustment_dian_response.xml

Probar en el Playground

Corregir una nota de ajuste de nómina rechazada (mismo número) y reenviarla

PUT /v1/payroll_adjustments/{id} · correctPayrollAdjustment

Corrige una nota de ajuste rechazada con el mismo número y la vuelve a enviar.

Solo si el documento está rejected, error o pending. Uno accepted no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es 409 invalid_state: espera el resultado. El external_id y la numeración no se cambian. Pide Idempotency-Key.

Parámetros

Idempotency-Keycabeceratextoobligatorio
Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).

Cuerpo (PayrollAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos).
typereplace | deleteobligatorio
"replace" (Reemplazar: el ajuste lleva todos los datos de la nómina menos novelty) o "delete" (Eliminar: solo predecessor, notes, generation_place y employer).
predecessorPayrollReferenceobligatorio
El documento que se ajusta: {"id": "pr_…"} (una nómina de Trevol) o {"id": "pra_…"} (otro ajuste, el último de la cadena), o sus datos {number, cune, issue_date}.
periodPayrollPeriod
pay_periodtexto
currencytexto
exchange_ratedecimal
Número o texto decimal con punto («150000.50»).
noteslista de texto
Máximo 20.
employeePayrollEmployee
paymentPayrollPayment
payment_dateslista de fecha (AAAA-MM-DD)
Máximo 31.
earningsPayrollEarnings
deductionsPayrollDeductions
roundingdecimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
generation_placePayrollPlace
employerPayrollEmployer

Respuestas

Estado	Qué pasó
200	El documento (PayrollAdjustment)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`). (PayrollAdjustment)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

PUT /v1/payroll_adjustments/{id}

cURL

curl -X PUT "https://api.trevol.si/v1/payroll_adjustments/pra_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -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