Documentación Técnica de la API de Dataico: Nómina Electrónica

Swagger de la API v2: https://app.dataico.com/payroll-docs/v2. El enlace sin /v2 (https://app.dataico.com/payroll-docs) muestra la versión anterior de la API.

URL base de la API v2: https://api.dataico.com/direct/payroll-api/v2

Autenticación

La API se autentica solo con el header Auth-token: el token de tu cuenta Dataico o una llave API creada por tu empresa. La API de nómina no usa dataico_account_id.

Obtener Auth-token

En la interfaz de Dataico, haz clic en las opciones en la parte superior y selecciona Configuración. También puedes crear una llave API para tu integración: ver ¿Cómo crear y revocar llaves API en Dataico?.

Software

Cada documento lleva el objeto software, y Dataico lo valida contra el software de nómina electrónica registrado en tu empresa:

"software": {
  "pin": "4123412",
  "dian_id": "d0e88268-a4ab-447d-918c-19c1c248b5c3"
}

Nota: El pin y el dian_id son los mismos para todos los clientes. Para que la API los acepte, tu empresa debe haber habilitado la nómina electrónica en Dataico. El test_set_id no es fijo (lo asigna la DIAN a cada empresa) y no hace falta enviarlo.

Ambiente

El campo env indica el ambiente del documento ante la DIAN: PRUEBAS o PRODUCCION.

Empresas con el modelo de empleado con fecha de vigencia

Si tu empresa registra los cambios de sus empleados con fecha de vigencia (la ficha del empleado con el panel Añadir novedad, ver ¿Cómo usar el panel de novedades del empleado (Añadir novedad)?), la API no acepta nóminas ni notas de reemplazo, ni individuales ni por lotes. La respuesta es:

Operación deshabilitada: la gestión de empleados por tiempo de negocio (BT) está activa para esta empresa. Por favor, contacte a soporte.

Las empresas nuevas tienen este modelo activo desde su creación. Si vas a enviar nómina por API, escríbenos al chat de soporte antes de empezar la integración: este modelo solo lo puede cambiar el equipo de soporte. Las notas de eliminación y las consultas no tienen esta restricción.

Numeración

Para obtener los datos de tu numeración o consecutivo de nómina electrónica:

Nómina > Configuración > Nómina Electrónica > Numeraciones

Tipos de conceptos

Devengados

Cada devengado lleva su code y los campos que exige ese concepto. amount es el valor salarial y amount-ns el valor no salarial.

Concepto (`code`)	Valor	Otros campos obligatorios
BASICO	`amount`	`days` (acepta decimales)
AUXILIO_DE_TRANSPORTE, COMISION, PAGO_TERCERO, ANTICIPO, REINTEGRO	`amount`
HORA_EXTRA_DIURNA, HORA_EXTRA_NOCTURNA, HORA_RECARGO_NOCTURNO, HORA_EXTRA_DIURNA_DF, HORA_EXTRA_NOCTURNA_DF, HORA_RECARGO_DIURNA_DF, HORA_RECARGO_NOCTURNO_DF	`amount`	`hours`. El `percentage` es opcional; si lo envías, debe ser el porcentaje legal (ver la tabla siguiente)
LICENCIA_PATERNIDAD	`amount`	`days` (más de 0 y hasta 30)
LICENCIA_REMUNERADA	`amount`	`days`
VACACION	`amount` (opcional)	`days` (más de 0 y hasta 30)
INCAPACIDAD	`amount` (opcional)	`days` y `medical-leave-type`
VIATICO, BONIFICACION, AUXILIO, BONO_EPCTV, BONO_EPCTV_ALIMENTACION, TELETRABAJO	`amount` o `amount-ns`
PRIMA	`amount` y/o `amount-ns` (al menos uno mayor que 0)	`days` (hasta 180)
OTRO_CONCEPTO	`amount` y/o `amount-ns` (al menos uno mayor que 0)	`description`
DOTACION, APOYO_PRACTICA, BONIFICACION_RETIRO, INDEMNIZACION	`amount-ns`
VACACION_COMPENSADA	`amount-ns`	`days` (mayor que 0)
CESANTIAS	`amount-ns`	`percentage` y `cesantias-interest`
COMPENSACION	`ordinary-compensation` y/o `extraordinary-compensation`
LICENCIA_NO_REMUNERADA, HUELGA_LEGAL	Sin valor	`days`

Porcentajes de horas extra y recargos

Si envías percentage en una hora extra o un recargo, Dataico lo compara con el porcentaje legal vigente en la fecha de inicio del periodo (initial-settlement-date). Los porcentajes de dominicales y festivos (códigos terminados en _DF) cambian cada 1 de julio:

Código	Antes del 1/07/2025	Desde el 1/07/2025	Desde el 1/07/2026	Desde el 1/07/2027
HORA_EXTRA_DIURNA_DF	100	105	115	125
HORA_RECARGO_DIURNA_DF	75	80	90	100
HORA_EXTRA_NOCTURNA_DF	150	155	165	175
HORA_RECARGO_NOCTURNO_DF	110	115	125	135

Los demás no cambian: HORA_EXTRA_DIURNA 25, HORA_EXTRA_NOCTURNA 75 y HORA_RECARGO_NOCTURNO 35.

Deducciones

Concepto (`code`)	Campos obligatorios
SALUD, FONDO_PENSION, FONDO_SOLIDARIDAD_PENSIONAL, FONDO_SUBSISTENCIA, SINDICATO	`amount` y `percentage`
LIBRANZA, OTRA_DEDUCCION	`amount` y `description`
SANCION	`public-sanction` y/o `private-sanction` (al menos uno mayor que 0)
PAGO_TERCERO, ANTICIPO, PENSION_VOLUNTARIA, RETENCION_FUENTE, AFC, COOPERATIVA, EMBARGO_FISCAL, PLANES_COMPLEMENTARIOS, EDUCACION, REINTEGRO, DEUDA	`amount`

Creación de nómina electrónica

Crear nómina electrónica (individual)

Método: POST

Endpoint: https://api.dataico.com/direct/payroll-api/v2/payroll-entries

Headers

Content-type: application/json
Auth-token: el token de tu cuenta Dataico o una llave API de tu empresa.

La respuesta trae el documento procesado, con los mismos campos que Consultar nómina por API.

Crear nómina electrónica (por lotes)

Método: POST

Endpoint: https://api.dataico.com/direct/payroll-api/v2/payroll-entries-batch

Headers

Content-type: application/json
Auth-token: el token de tu cuenta Dataico o una llave API de tu empresa.

El cuerpo del lote es {"entries": [ ... ]}. Todas las nóminas de un lote deben tener el mismo prefijo y pertenecer al mismo periodo.

El envío por lotes es asíncrono: responde 201 con un job-id y el resultado se consulta después. Ver Envío en bloque de nómina electrónica: respuesta asíncrona con job-id.

Estructura JSON

El Swagger de la API v2 tiene el esquema de cada campo y un ejemplo de nómina. Si un ejemplo usa porcentajes de horas extra, verifica que correspondan a la fecha de tu periodo.

Recomendaciones clave

Elementos que no deben enviarse vacíos

No envíes campos de texto opcionales con un texto vacío (""): code, other-names, second-last-name, bank y account-number responden "El texto no puede ser vacío". account-type-kw y fire-date tampoco se envían vacíos: el primero solo acepta los valores de su lista y el segundo una fecha dd/mm/aaaa.

Si un empleado no tiene el dato, omite el campo en el JSON. Un campo con valor null se ignora.

Variables necesarias para la transmisión a la DIAN

Para que el documento se transmita a la DIAN, envía "send_dian": true. Si no lo envías, Dataico guarda el documento y su PDF pero no lo transmite a la DIAN.