Generación Nomina
POST
/api/externalPayrollController/process
NETransmisiónNómina ElectrónicaNómina Electrónica de AjusteNómina Electrónica de Eliminación
Última modificación:2026-07-31 14:14:07
Descripción
procesamiento indicando si la DIAN aceptó el documento. Un mismo endpoint atiende los tres
tipos de documento: nómina normal, nota de ajuste y nota de eliminación.
x-api-key, x-company-id y x-user-id.Método y ruta
POST /api/externalPayrollController/processHeaders
| Header | Tipo | Requerido | Descripción |
|---|---|---|---|
x-api-key | string | Sí | Clave de acceso (API Key) de tu compañía. |
x-company-id | integer | Sí | Identificador de la compañía emisora. |
x-user-id | integer | Sí | Identificador del usuario responsable del envío. |
Content-Type | string | Sí | application/json |
Tipo de documento (campo TipoNota)
| TipoNota | Documento | Bloque requerido |
|---|---|---|
| (ausente o vacío) | Nómina normal | Bloques de nómina a nivel raíz. |
1 | Nota de ajuste | Reemplazar |
2 | Nota de eliminación | Eliminar |
Respuesta
| Campo | Tipo | Descripción |
|---|---|---|
Errors | array<string> | Errores o motivos de rechazo de la DIAN. |
IsValid | boolean | true si la DIAN aceptó el documento. |
ResultCode | integer | Código de resultado (ver tabla). |
Warning | array<string> | Notificaciones no bloqueantes de la DIAN. |
ResultData | string | Mensaje descriptivo del resultado. |
Códigos de resultado
| ResultCode | HTTP | IsValid | Significado |
|---|---|---|---|
| 200 | 200 | true | Nómina aceptada por la DIAN. |
| 422 | 200 | false | Nómina rechazada por la DIAN (ver Errors). |
| 401 | 401 | false | Falta el header x-api-key. |
| 400 | 400 | false | Falta x-company-id/x-user-id/cuerpo, o el cuerpo es inválido. |
| 502 | 502 | false | Error de comunicación con la DIAN. |
| 500 | 500 | false | Error inesperado al procesar la nómina. |
Ejemplos de respuesta
200 · Aceptada
{ "Errors": [], "IsValid": true, "ResultCode": 200, "Warning": [], "ResultData": "Procesado Correctamente." }422 · Rechazada por la DIAN (HTTP 200)
{ "Errors": ["Regla XXXX: ..."], "IsValid": false, "ResultCode": 422, "Warning": [], "ResultData": "Regla XXXX: ..." }401 · Falta x-api-key
{ "Errors": ["El header 'x-api-key' es obligatorio."], "IsValid": false, "ResultCode": 401, "Warning": [], "ResultData": "El header 'x-api-key' es obligatorio." }400 · Cuerpo/headers inválidos
{ "Errors": ["El header 'x-user-id' es obligatorio."], "IsValid": false, "ResultCode": 400, "Warning": [], "ResultData": "El header 'x-user-id' es obligatorio." }502 · Error de comunicación con la DIAN
{ "Errors": ["Error comunicando con el servicio de la DIAN: <detalle>"], "IsValid": false, "ResultCode": 502, "Warning": [], "ResultData": "Error comunicando con el servicio de la DIAN: <detalle>" }500 · Error inesperado
{ "Errors": ["Error procesando la nomina: <detalle>"], "IsValid": false, "ResultCode": 500, "Warning": [], "ResultData": "Error procesando la nomina: <detalle>" }Solicitud
Parámetros de Header
Parámetros del Body application/jsonRequerido
Respuestas
Solicitud Ejemplo de Solicitud
Shell
JavaScript
Java
Swift
cURL
curl --location --globoff 'https://{{ur_basel}}/api/externalPayrollController/process' \
--header 'x-api-key: {{api_key}}' \
--header 'x-company-id: {{company_id}}' \
--header 'x-user-id: {{user-id}}' \
--header 'Content-Type: application/json' \
--data '{
"FechasPagos": [
{
"FechaPago": "2021-06-29"
}
],
"Periodo": {
"FechaIngreso": "2021-07-01",
"FechaLiquidacionInicio": "2021-07-01",
"FechaLiquidacionFin": "2021-07-07",
"TiempoLaborado": "7",
"FechaGen": "2021-07-07"
},
"NumeroSecuenciaXML": {
"Prefijo": "FTNO",
"Consecutivo": "1"
},
"LugarGeneracionXML": {
"Pais": "CO",
"DepartamentoEstado": "11",
"MunicipioCiudad": "11001",
"Idioma": "es"
},
"InformacionGeneral": {
"FechaHoraGen": "2021-07-08T00:00:00",
"PeriodoNomina": "1",
"TipoMoneda": "COP",
"TRM": "10"
},
"Notas": [
"Nota de prueba"
],
"Empleador": {
"NIT": "string"
},
"Trabajador": {
"TipoTrabajador": "47",
"SubTipoTrabajador": "00",
"AltoRiesgoPension": "true",
"TipoDocumento": "48",
"NumeroDocumento": "123456789",
"PrimerApellido": "Primer Apellido",
"SegundoApellido": "Segundo Apellido",
"PrimerNombre": "Primer Nombre",
"OtrosNombres": "Otros Nombres",
"LugarTrabajoPais": "CO",
"LugarTrabajoDepartamentoEstado": "11",
"LugarTrabajoMunicipioCiudad": "11001",
"LugarTrabajoDireccion": "Direccion",
"SalarioIntegral": "true",
"TipoContrato": "1",
"Sueldo": "2800000",
"CodigoTrabajador": "47",
"CorreoElectronico": "string"
},
"Pago": {
"Forma": "1",
"Metodo": "11"
},
"Devengados": {
"Basico": {
"DiasTrabajados": "7",
"SueldoTrabajado": "2800000.00"
},
"Transporte": [
{
"AuxilioTransporte": "20000.00",
"ViaticoManutAlojS": "50000.00",
"ViaticoManutAlojNS": "10000.00"
}
],
"HEDs": [
{
"Cantidad": "3",
"Porcentaje": "100",
"Pago": "300000.00"
}
],
"HENs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "10000.00"
}
],
"HEDDFs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "5500.00"
}
],
"HENDFs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "5700.00"
}
],
"HRNs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "500.00"
}
],
"HRDDFs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "8500.00"
}
],
"HRNDFs": [
{
"Cantidad": "1",
"Porcentaje": "100",
"Pago": "7800.00"
}
],
"Vacaciones": {
"VacacionesComunes": [
{
"Cantidad": "1",
"Pago": "450000.00"
}
],
"VacacionesCompensadas": [
{
"Cantidad": "1",
"Pago": "102000.00"
}
]
},
"Primas": {
"Cantidad": "1",
"Pago": "100000.00",
"PagoNS": "50000.00"
},
"Cesantias": {
"Pago": "1500000.00",
"Porcentaje": "100",
"PagoIntereses": "20000.00"
},
"Incapacidades": [
{
"Cantidad": "1",
"Tipo": "1",
"Pago": "15000.00"
},
{
"Cantidad": "1",
"Tipo": "2",
"Pago": "30000.00"
}
],
"Licencias": {
"LicenciaMP": [
{
"Cantidad": "1",
"Pago": "450000.00"
}
],
"LicenciaR": [
{
"Cantidad": "1",
"Pago": "38000.00"
}
],
"LicenciaNR": [
{
"Cantidad": "1"
}
]
},
"Bonificaciones": [
{
"BonificacionS": "10000.00",
"BonificacionNS": "3500.00"
}
],
"Auxilios": [
{
"AuxilioS": "800.00",
"AuxilioNS": "700.00"
}
],
"OtrosConceptos": [
{
"DescripcionConcepto": "Descripcion Concepto",
"ConceptoS": "350.00",
"ConceptoNS": "950.00"
}
],
"Compensaciones": [
{
"CompensacionO": "9600.00",
"CompensacionE": "7850.00"
}
],
"BonoEPCTVs": [
{
"PagoS": "8000.00",
"PagoNS": "650.00",
"PagoAlimentacionS": "750.00",
"PagoAlimentacionNS": "450.00"
}
],
"Comisiones": [
{
"Comision": "96000.00"
}
],
"PagosTerceros": [
{
"PagoTercero": "45000.00"
}
],
"Anticipos": [
{
"Anticipo": "15000.00"
}
],
"Dotacion": "5000.00",
"ApoyoSost": "20000.00",
"Teletrabajo": "95000.00",
"BonifRetiro": "75000.00",
"Indemnizacion": "80000.00",
"Reintegro": "15000.00"
},
"Deducciones": {
"Salud": {
"Porcentaje": "1.00",
"Deduccion": "35000.00"
},
"FondoPension": {
"Porcentaje": "1.00",
"Deduccion": "510000.00"
},
"FondoSP": {
"Porcentaje": "1.00",
"Deduccion": "24900.00",
"PorcentajeSub": "1.00",
"DeduccionSub": "96300.00"
},
"Sindicatos": [
{
"Porcentaje": "1.00",
"Deduccion": "127500.00"
}
],
"Sanciones": [
{
"SancionPublic": "7000.00",
"SancionPriv": "9000.00"
}
],
"Libranzas": [
{
"Descripcion": "Banco",
"Deduccion": "780000.00"
}
],
"PagosTerceros": [
{
"PagoTercero": "10000.00"
}
],
"Anticipos": [
{
"Anticipo": "85000.00"
}
],
"OtrasDeducciones": [
{
"OtraDeduccion": "96300.00"
}
],
"PensionVoluntaria": "500000.00",
"RetencionFuente": "500.00",
"AFC": "2800.00",
"Cooperativa": "350.00",
"EmbargoFiscal": "450320.00",
"PlanComplementarios": "510.00",
"Educacion": "35820.00",
"Reintegro": "9850.00",
"Deuda": "23450.00"
},
"DevengadosTotal": "4999850.00",
"DeduccionesTotal": "2793300.00",
"ComprobanteTotal": "2206550.00",
"Redondeo": "2.00",
"CorrelationDocumentId": "string"
}'Respuesta Ejemplo de Respuesta
Ejemplo Error
{
"Errors": [
"Error al consumir el servicio"
],
"IsValid": false,
"ResultCode": 400,
"Warning": [],
"ResultData": "Error al consumir el servicio"
}Modificado en 2026-07-31 14:14:07