Nómina electrónica

Emitir una nómina electrónica

POST /v1/payrolls · createPayroll

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.

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 (PayrollInput, 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).
• periodPayrollPeriodobligatorio
  El periodo que se liquida y el tiempo laborado (time_worked se calcula si no se manda: años de 360 días y meses de 30).
• pay_periodtextoobligatorio
  Periodo de nómina (tabla 5.5.1): "1" semanal, "2" decenal, "3" catorcenal, "4" quincenal, "5" mensual, "6" otro.
• currencytexto
  Moneda (ISO 4217). Por defecto COP; con otra va exchange_rate.
• exchange_ratedecimal
  Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP.
• noveltyPayrollNovelty
  El CUNE del documento con la novedad contractual, si la hay. Solo en la nómina.
• noteslista de texto
  Máximo 20.
• employeePayrollEmployeeobligatorio
  El trabajador. Sus datos solo salen en las respuestas a esta llave (la del empleador): nunca en webhooks, en el registro de peticiones ni en lo que se guarda de la idempotencia.
• paymentPayrollPaymentobligatorio
• payment_dateslista de fecha (AAAA-MM-DD)obligatorio
  Las fechas de pago (1 a 31). Máximo 31.
• earningsPayrollEarningsobligatorio
• deductionsPayrollDeductionsobligatorio
• roundingdecimal
  Redondeo hasta 2.00; no suma a los totales.
• generation_placePayrollPlace
  Dónde se generó el documento. Por defecto, el municipio de la empresa.
• employerPayrollEmployer
  Solo si la empresa es persona natural: sus apellidos y nombres (si la razón social no se separa bien en «apellido1 apellido2 nombre1»).

Respuestas

Calcular una nómina electrónica sin emitirla

POST /v1/payrolls/preview · previewPayroll

Valida y calcula los totales de la nómina sin reservar un número ni enviar nada. No pide Idempotency-Key y no se cobra. El trabajador que mandaste vuelve en la respuesta; Trevol no lo guarda.

Cuerpo (PayrollInput, 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).
• periodPayrollPeriodobligatorio
  El periodo que se liquida y el tiempo laborado (time_worked se calcula si no se manda: años de 360 días y meses de 30).
• pay_periodtextoobligatorio
  Periodo de nómina (tabla 5.5.1): "1" semanal, "2" decenal, "3" catorcenal, "4" quincenal, "5" mensual, "6" otro.
• currencytexto
  Moneda (ISO 4217). Por defecto COP; con otra va exchange_rate.
• exchange_ratedecimal
  Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP.
• noveltyPayrollNovelty
  El CUNE del documento con la novedad contractual, si la hay. Solo en la nómina.
• noteslista de texto
  Máximo 20.
• employeePayrollEmployeeobligatorio
  El trabajador. Sus datos solo salen en las respuestas a esta llave (la del empleador): nunca en webhooks, en el registro de peticiones ni en lo que se guarda de la idempotencia.
• paymentPayrollPaymentobligatorio
• payment_dateslista de fecha (AAAA-MM-DD)obligatorio
  Las fechas de pago (1 a 31). Máximo 31.
• earningsPayrollEarningsobligatorio
• deductionsPayrollDeductionsobligatorio
• roundingdecimal
  Redondeo hasta 2.00; no suma a los totales.
• generation_placePayrollPlace
  Dónde se generó el documento. Por defecto, el municipio de la empresa.
• employerPayrollEmployer
  Solo si la empresa es persona natural: sus apellidos y nombres (si la razón social no se separa bien en «apellido1 apellido2 nombre1»).

Respuestas

Reenviar una pendiente o en error

POST /v1/payrolls/{id}/send · sendPayroll

Vuelve a enviar una nómina pending o error. Si el set de pruebas la valida (validating), solo consulta.

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

Listar (nómina electrónica)

GET /v1/payrolls · listPayrolls

Paginación por cursor y filtros status, external_id, created_from, created_to, employee_code (el código interno del empleado) y period_end_from / period_end_to. No se filtra por el documento del trabajador: la cédula en la URL quedaría en los registros del servidor.

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

Una nómina electrónica

GET /v1/payrolls/{id} · retrievePayroll

La nómina tal como se emitió, con el trabajador, los devengados, las deducciones y los totales (earnings, deductions, net).

Respuestas

Archivo xml

GET /v1/payrolls/{id}/xml · downloadPayrollXml

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

Respuestas

Archivo zip

GET /v1/payrolls/{id}/zip · downloadPayrollZip

El ZIP del documento (application/zip).

Respuestas

Archivo dian_response

GET /v1/payrolls/{id}/dian_response · downloadPayrollDianResponse

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

Respuestas

Corregir una nómina electrónica rechazada (mismo número) y reenviarla

PUT /v1/payrolls/{id} · correctPayroll

Corrige una nómina rechazada con el mismo número y la vuelve a enviar. 409 invalid_state si el set de pruebas la está validando.

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 (PayrollInput, 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).
• periodPayrollPeriodobligatorio
  El periodo que se liquida y el tiempo laborado (time_worked se calcula si no se manda: años de 360 días y meses de 30).
• pay_periodtextoobligatorio
  Periodo de nómina (tabla 5.5.1): "1" semanal, "2" decenal, "3" catorcenal, "4" quincenal, "5" mensual, "6" otro.
• currencytexto
  Moneda (ISO 4217). Por defecto COP; con otra va exchange_rate.
• exchange_ratedecimal
  Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP.
• noveltyPayrollNovelty
  El CUNE del documento con la novedad contractual, si la hay. Solo en la nómina.
• noteslista de texto
  Máximo 20.
• employeePayrollEmployeeobligatorio
  El trabajador. Sus datos solo salen en las respuestas a esta llave (la del empleador): nunca en webhooks, en el registro de peticiones ni en lo que se guarda de la idempotencia.
• paymentPayrollPaymentobligatorio
• payment_dateslista de fecha (AAAA-MM-DD)obligatorio
  Las fechas de pago (1 a 31). Máximo 31.
• earningsPayrollEarningsobligatorio
• deductionsPayrollDeductionsobligatorio
• roundingdecimal
  Redondeo hasta 2.00; no suma a los totales.
• generation_placePayrollPlace
  Dónde se generó el documento. Por defecto, el municipio de la empresa.
• employerPayrollEmployer
  Solo si la empresa es persona natural: sus apellidos y nombres (si la razón social no se separa bien en «apellido1 apellido2 nombre1»).

Respuestas