Emitir nómina de ajuste
const url = 'https://example.com/v1/payroll-adjustments?wait=true';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"adjustmentType":"1","predecessor":{"documentId":"example"},"replacement":{"period":{"hireDate":"2026-04-15","retirementDate":"2026-04-15","settlementStartDate":"2026-04-15","settlementEndDate":"2026-04-15","workedTime":1},"employee":{"workerType":"example","workerSubtype":"example","highRiskPension":true,"idType":"11","idNumber":"example","firstSurname":"example","secondSurname":"example","firstName":"example","otherNames":"example","workplace":{"line":"example","cityCode":"example","cityName":"example","departmentCode":"example","departmentName":"example","postalCode":"example","countryCode":"CO","countryName":"example"},"integralSalary":true,"contractType":"example","salary":1,"employeeCode":"example"},"payment":{"form":"1","method":"example","bank":"example","accountType":"example","accountNumber":"example"},"paymentDates":["2026-04-15"],"payrollPeriod":"example","currency":"example","exchangeRate":1,"notes":["example"],"earnings":{"basic":{"workedDays":1,"amount":1},"transport":{"allowance":1,"viaticSalary":1,"viaticNonSalary":1},"overtime":[{"type":"HED","startTime":"example","endTime":"example","quantity":1,"percentage":1,"amount":1}],"vacations":{"common":[{"startDate":"2026-04-15","endDate":"2026-04-15","days":1,"amount":1}],"compensated":[{"days":1,"amount":1}]},"bonus":{"quantity":1,"amount":1,"nonSalaryAmount":1},"severance":{"amount":1,"percentage":1,"interestAmount":1},"incapacities":[{"startDate":"2026-04-15","endDate":"2026-04-15","quantity":1,"type":"1","amount":1}],"licenses":{"maternity":[{"startDate":"2026-04-15","endDate":"2026-04-15","quantity":1,"amount":1}],"paid":[{"startDate":"2026-04-15","endDate":"2026-04-15","quantity":1,"amount":1}],"unpaid":[{"startDate":"2026-04-15","endDate":"2026-04-15","quantity":1}]},"bonuses":[{"salary":1,"nonSalary":1}],"aids":[{"salary":1,"nonSalary":1}],"otherConcepts":[{"salary":1,"nonSalary":1,"description":"example"}],"commissions":[1],"endowment":1,"support":1,"telecommuting":1,"compensations":[{"ordinary":1,"extraordinary":1}],"strikes":[{"startDate":"2026-04-15","endDate":"2026-04-15","days":1}],"vouchers":[{"salary":1,"nonSalary":1,"foodSalary":1,"foodNonSalary":1}],"thirdPartyPayments":[1],"advances":[1],"retirementBonus":1,"indemnity":1,"refund":1},"deductions":{"health":{"percentage":1,"amount":1},"pension":{"percentage":1,"amount":1},"solidarityFund":{"percentage":1,"amount":1,"subsistencePercentage":1,"subsistenceAmount":1},"unions":[{"percentage":1,"amount":1}],"sanctions":[{"public":1,"private":1}],"libranzas":[{"description":"example","amount":1}],"thirdPartyPayments":[1],"advances":[1],"otherDeductions":[1],"voluntaryPension":1,"withholdingTax":1,"afc":1,"cooperative":1,"taxLien":1,"supplementaryPlan":1,"education":1,"refund":1,"debt":1},"rounding":1,"generationPlace":{"countryCode":"example","departmentCode":"example","cityCode":"example"}},"notes":["example"],"rangeId":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://example.com/v1/payroll-adjustments?wait=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "adjustmentType": "1", "predecessor": { "documentId": "example" }, "replacement": { "period": { "hireDate": "2026-04-15", "retirementDate": "2026-04-15", "settlementStartDate": "2026-04-15", "settlementEndDate": "2026-04-15", "workedTime": 1 }, "employee": { "workerType": "example", "workerSubtype": "example", "highRiskPension": true, "idType": "11", "idNumber": "example", "firstSurname": "example", "secondSurname": "example", "firstName": "example", "otherNames": "example", "workplace": { "line": "example", "cityCode": "example", "cityName": "example", "departmentCode": "example", "departmentName": "example", "postalCode": "example", "countryCode": "CO", "countryName": "example" }, "integralSalary": true, "contractType": "example", "salary": 1, "employeeCode": "example" }, "payment": { "form": "1", "method": "example", "bank": "example", "accountType": "example", "accountNumber": "example" }, "paymentDates": [ "2026-04-15" ], "payrollPeriod": "example", "currency": "example", "exchangeRate": 1, "notes": [ "example" ], "earnings": { "basic": { "workedDays": 1, "amount": 1 }, "transport": { "allowance": 1, "viaticSalary": 1, "viaticNonSalary": 1 }, "overtime": [ { "type": "HED", "startTime": "example", "endTime": "example", "quantity": 1, "percentage": 1, "amount": 1 } ], "vacations": { "common": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "days": 1, "amount": 1 } ], "compensated": [ { "days": 1, "amount": 1 } ] }, "bonus": { "quantity": 1, "amount": 1, "nonSalaryAmount": 1 }, "severance": { "amount": 1, "percentage": 1, "interestAmount": 1 }, "incapacities": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "quantity": 1, "type": "1", "amount": 1 } ], "licenses": { "maternity": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "quantity": 1, "amount": 1 } ], "paid": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "quantity": 1, "amount": 1 } ], "unpaid": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "quantity": 1 } ] }, "bonuses": [ { "salary": 1, "nonSalary": 1 } ], "aids": [ { "salary": 1, "nonSalary": 1 } ], "otherConcepts": [ { "salary": 1, "nonSalary": 1, "description": "example" } ], "commissions": [ 1 ], "endowment": 1, "support": 1, "telecommuting": 1, "compensations": [ { "ordinary": 1, "extraordinary": 1 } ], "strikes": [ { "startDate": "2026-04-15", "endDate": "2026-04-15", "days": 1 } ], "vouchers": [ { "salary": 1, "nonSalary": 1, "foodSalary": 1, "foodNonSalary": 1 } ], "thirdPartyPayments": [ 1 ], "advances": [ 1 ], "retirementBonus": 1, "indemnity": 1, "refund": 1 }, "deductions": { "health": { "percentage": 1, "amount": 1 }, "pension": { "percentage": 1, "amount": 1 }, "solidarityFund": { "percentage": 1, "amount": 1, "subsistencePercentage": 1, "subsistenceAmount": 1 }, "unions": [ { "percentage": 1, "amount": 1 } ], "sanctions": [ { "public": 1, "private": 1 } ], "libranzas": [ { "description": "example", "amount": 1 } ], "thirdPartyPayments": [ 1 ], "advances": [ 1 ], "otherDeductions": [ 1 ], "voluntaryPension": 1, "withholdingTax": 1, "afc": 1, "cooperative": 1, "taxLien": 1, "supplementaryPlan": 1, "education": 1, "refund": 1, "debt": 1 }, "rounding": 1, "generationPlace": { "countryCode": "example", "departmentCode": "example", "cityCode": "example" } }, "notes": [ "example" ], "rangeId": "example" }'Authorizations
Sección titulada «Authorizations»Parameters
Sección titulada «Parameters»Header Parameters
Sección titulada «Header Parameters»Id o NIT del facturador. Obligatorio con llaves de cuenta; ignorado con llaves restringidas.
Repetir la petición con la misma llave devuelve el mismo documento, sin emitir otro.
Solo con API keys de sandbox (sk_sandbox_…): elige el resultado de la DIAN simulada: accepted (por defecto), rejected:
Query Parameters
Sección titulada «Query Parameters»True: espera la respuesta de la DIAN en la misma petición
Request Bodyrequired
Sección titulada «Request Bodyrequired»Un ajuste a una nómina aceptada: la reemplaza o la elimina
object
1 = reemplazar, 2 = eliminar
La nómina aceptada que se ajusta
Documento emitido por esta API
object
Id de la nómina en esta API
Un documento emitido por fuera de esta API
object
Su número completo, con prefijo
Su CUNE: 96 caracteres hexadecimales
Fecha en que se generó
La nómina corregida, completa; obligatoria al reemplazar (1)
object
Fechas de la relación laboral y de la liquidación
object
Fecha de ingreso del empleado
Fecha de retiro, para una liquidación final
Primer día que liquida esta nómina
Último día que liquida esta nómina; no antes del primero
El empleado
object
Tipo de trabajador (tabla 5.5.3): 01 dependiente, 02 servicio doméstico, 12 aprendiz…
Subtipo de trabajador: 00 no aplica, 01 pensionado que sigue trabajando
Si el cargo es de alto riesgo para pensión (aumenta el aporte)
Tipo de documento de identidad (tabla 13.2.1): 11 registro civil, 12 tarjeta de identidad, 13 cédula de ciudadanía, 21 tarjeta de extranjería, 22 cédula de extranjería, 31 NIT, 41 pasaporte, 42 documento de identificación extranjero, 47 PEP, 48 PPT, 50 NIT de otro país, 91 NUIP
Número del documento de identidad del empleado
Primer apellido
Segundo apellido, si lo tiene
Primer nombre
Otros nombres
Lugar de trabajo del empleado
object
La dirección, ej. “Calle 100 # 10-20”
Código DIVIPOLA del municipio, 5 dígitos, ej. 11001 (Bogotá)
Nombre del municipio
Código DIVIPOLA del departamento, 2 dígitos, ej. 11 (Bogotá D.C.)
Nombre del departamento
Código postal
País, ISO 3166-1 alfa-2; CO por defecto
Nombre del país en español; Colombia si el país es CO y no se envía
Si el salario es integral (ya incluye las prestaciones; no genera cesantías)
Tipo de contrato (tabla 5.5.6): 1 término fijo, 2 término indefinido, 3 obra o labor, 4 aprendizaje, 5 prácticas
Código propio del empleador para el empleado
Cómo se le paga al empleado
object
Forma de pago: 1 contado (por defecto; la nómina nunca es a crédito)
Medio de pago (tabla 13.3.4.2 del anexo de facturación): 10 efectivo, 42 consignación bancaria, 47 transferencia…
Nombre del banco, para una transferencia
Tipo de cuenta (ahorros, corriente), para una transferencia
Número de cuenta, para una transferencia
Fechas de pago; al menos una
Periodicidad de pago (tabla 5.5.1): 1 semanal, 2 decenal, 3 catorcenal, 4 quincenal, 5 mensual, 6 otro
Moneda, ISO 4217; COP si no se envía
Notas de texto libre
Devengados del periodo; solo basic es obligatorio
object
Auxilio de transporte y viáticos
object
Horas extra y recargos, una entrada por tipo
object
HED hora extra diurna (+25 %), HEN hora extra nocturna (+75 %), HRN recargo nocturno (+35 %), HEDDF hora extra diurna dominical o festiva (+100 %), HRDDF recargo diurno dominical o festivo (+75 %), HENDF hora extra nocturna dominical o festiva (+150 %), HRNDF recargo nocturno dominical o festivo (+110 %)
Cuándo empezaron las horas (YYYY-MM-DDTHH:mm:ss), si se registró
Cuándo terminaron las horas, si se registró
Vacaciones, disfrutadas o compensadas
object
Incapacidades por enfermedad o accidente
object
Primer día
Último día
Origen de la incapacidad: 1 común, 2 profesional, 3 laboral
Licencias en el periodo
object
Otras licencias remuneradas, ej. por luto o por ser jurado de votación
Comisiones por ventas, un valor cada una
Pagos con bonos electrónicos o de papel, tarjetas, cheques o recargas (BonoEPCTVs)
object
Pagos que el empleador hizo a terceros a nombre del trabajador, un valor por cada uno
Anticipos de nómina pagados en el periodo, un valor por cada uno
Deducciones del periodo; salud y pensión son obligatorias
object
Fondo de solidaridad pensional, para salarios de cuatro mínimos o más
object
Pagos a terceros ordenados por el empleado
Anticipos de salario que se están devolviendo
Otras deducciones que no tienen elemento propio en el esquema de la DIAN
Lugar donde se genera el XML; la dirección del empleador si no se envía
object
País, ISO 3166-1 alfa-2
Código DIVIPOLA del departamento
Código DIVIPOLA del municipio
Notas de texto libre; al reemplazar, sustituyen las de la nómina de reemplazo
Rango de numeración a usar, por su id; si no se envía, el rango activo más reciente del facturador para ese tipo
Responses
Sección titulada «Responses»Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)
object
Documento creado (201) o el mismo de antes con la misma Idempotency-Key (200)
object
Id del documento
Tipo de documento
Pending → sent → accepted / rejected; retrying y failed cuando la DIAN no responde
Ambiente DIAN: 1 = producción, 2 = habilitación (pruebas)
True cuando se emitió con una API key de sandbox (DIAN simulada, sin consumir bolsa)
Número completo (prefijo + consecutivo)
Prefijo del rango de numeración (puede estar vacío)
Consecutivo dentro del rango
CUFE, CUDE, CUDS o CUNE
Tipo y algoritmo del código único, ej. CUFE-SHA384
Cuándo se emitió; la fecha y hora del XML son este instante en hora de Bogotá
Sus valores y su contraparte
object
Valor del documento: el total a pagar, o el total de la nómina
Valor antes de impuestos (en nómina, los devengados)
Impuestos (en nómina, las deducciones)
Moneda, ISO 4217
Número de identificación de la contraparte: el comprador, el vendedor o el empleado
Nombre de la contraparte
Contenido del código QR de la representación gráfica
Lo que respondió la DIAN
object
Último código de estado de la DIAN: 00 procesado correctamente, 99 rechazado (null: aún sin respuesta)
Último texto de estado de la DIAN (null: aún sin respuesta)
Reglas de validación que la DIAN reportó
Llave de seguimiento de la DIAN (ZipKey), para documentos enviados al set de pruebas (null en los demás)
Cuántas veces se envió o se consultó su estado
Último error transitorio (la DIAN caída, un timeout); null una vez pasa
Documento al que hace referencia: una nota, a su factura; un ajuste, a su nómina (null: ninguno)
Cuándo se creó
Cuándo cambió por última vez
Example
{ "data": { "kind": "invoice", "status": "pending", "environment": "1", "issuedAt": "2026-01-15T15:30:00.000Z", "nextAttemptAt": "2026-01-15T15:30:00.000Z", "acceptedAt": "2026-01-15T15:30:00.000Z", "createdAt": "2026-01-15T15:30:00.000Z", "updatedAt": "2026-01-15T15:30:00.000Z" }}La petición no cumple el esquema (VALIDATION_ERROR, con details por campo)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Falta la credencial o no es válida (UNAUTHORIZED)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Sin saldo de documentos (INSUFFICIENT_BALANCE)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}La llave no puede hacer esto (FORBIDDEN)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}No existe, o no es de esta cuenta (NOT_FOUND)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Conflicto con el estado actual (CONFLICT, INVALID_STATE)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Regla de negocio (VALIDATION_ERROR, NUMBERING_*, CERTIFICATE_UNAVAILABLE…)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Demasiadas peticiones para esta cuenta (RATE_LIMITED; vea X-RateLimit-* y Retry-After)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}Error del servicio o de la DIAN (DIAN_UNAVAILABLE, DIAN_PROTOCOL_ERROR)
Un error: un código estable para los programas y un mensaje para los desarrolladores
object
El error
object
Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)
Qué salió mal, para desarrolladores (puede cambiar; compare por code)
Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué
Id de la petición, para soporte
Example generated
{ "error": { "code": "example", "message": "example", "details": "example", "requestId": "example" }}