---
title: "Documentación Técnica de la API de Dataico: Nómina Electrónica"
description: "Guía técnica para crear nómina electrónica individual y por lotes mediante la API v2 de Dataico: autenticación, software, ambiente, restricción por…"
---

[Ir directamente al contenido](https://portaldelcliente.dataico.com/es/knowledge/documentación-técnica-de-la-api-de-dataico-nómina-electrónica#main-content)

Español

Traducciones de Mostrar submenú de

![facturaelectronica.dataico.comhs-fshubfslogoDataico2-1.png\]](https://portaldelcliente.dataico.com/hs-fs/hubfs/social-suggested-images/facturaelectronica.dataico.comhs-fshubfslogoDataico2-1.png?height=40&name=facturaelectronica.dataico.comhs-fshubfslogoDataico2-1.png)

Abrir navegación principal

Cerrar navegación principal

- Español
  
  Traducciones de Mostrar submenú de
- <https://www.dataico.com/>

<https://www.dataico.com/>

 ¿Cómo podemos ayudarte?

- No hay sugerencias porque el campo de búsqueda está vacío.

1. [Centro de Ayuda](https://portaldelcliente.dataico.com/es/knowledge?hsLang=es)
2. [Integración API DATAICO S.A.S](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es)
3. [Nómina Electrónica.](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#n%C3%B3mina-electr%C3%B3nica)

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

## Guía Práctica

**Swagger de la API v2:** [https://app.dataico.com/payroll-docs/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?](https://portaldelcliente.dataico.com/es/knowledge/super-llave-api?hsLang=es).

**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)?](https://portaldelcliente.dataico.com/es/knowledge/como-usar-panel-de-novedades-del-empleado-a%C3%B1adir-novedad?hsLang=es)), 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](https://portaldelcliente.dataico.com/es/knowledge/consultar-n%C3%B3minas-por-consecutivo?hsLang=es).

#### **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](https://portaldelcliente.dataico.com/es/knowledge/envio-en-bloque-asincrono-job-id?hsLang=es).

El [Swagger de la API v2](https://app.dataico.com/payroll-docs/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.

#### **Provisiones mensuales**

La API no tiene un concepto de provisión. Todo lo que envíes como devengado (por ejemplo `CESANTIAS`, `PRIMA` u `OTRO_CONCEPTO` con descripción "Provisión de vacaciones") se reporta a la DIAN como **pagado** en ese periodo. Si tu sistema calcula provisiones cada mes, no las envíes como conceptos: reporta las prestaciones en el periodo en que se pagan.

#### **Rutas con `/v2`**

Usa siempre las rutas con `/v2` (`/payroll-api/v2/...`). Las rutas sin `/v2` siguen respondiendo, pero son de la versión anterior: en un envío por lotes, su consulta de estado no muestra los errores de un lote fallido.

### **Recursos Adicionales**

- [Swagger de la API v2 de Nómina Electrónica](https://app.dataico.com/payroll-docs/v2)
- [Guía de errores de la API de Nómina Electrónica](https://portaldelcliente.dataico.com/es/knowledge/gu%C3%ADa-de-soluci%C3%B3n-de-problemas-api-dataico-n%C3%B3mina-electr%C3%B3nica?hsLang=es)
- [Consultar nómina por API](https://portaldelcliente.dataico.com/es/knowledge/consultar-n%C3%B3minas-por-consecutivo?hsLang=es)
- [Crear nota de reemplazo](https://portaldelcliente.dataico.com/es/knowledge/crear-notas-de-reemplazo?hsLang=es)
- [Crear nota de eliminación](https://portaldelcliente.dataico.com/es/knowledge/crear-nota-de-eliminaci%C3%B3n-por-api?hsLang=es)

- [Módulo de Terceros](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-terceros?hsLang=es#main-content)

    - [Conceptos](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-terceros?hsLang=es#conceptos)
- [Módulo de Ventas](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#main-content)

    - [Onboarding Facturación](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#onboarding-facturaci%C3%B3n)
    - [Generales](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#generales)
    - [Facturas](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#facturas)
    - [Cotizaciones](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#cotizaciones)
    - [Notas crédito](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#notas-cr%C3%A9dito)
    - [Notas débito](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#notas-d%C3%A9bito)
    - [Facturación electrónica](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#facturaci%C3%B3n-electr%C3%B3nica)
    - [Onboarding POS Electrónico](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#onboarding-pos-electr%C3%B3nico)
    - [Generalidades de Documento Equivalente POS Electrónico](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#generalidades-de-documento-equivalente-pos-electr%C3%B3nico)
    - [Notas de Ajuste POS Electrónico](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-ventas?hsLang=es#notas-de-ajuste-pos-electr%C3%B3nico)
- [Módulo de Contabilidad](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#main-content)

    - [Onboarding y conceptos](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#onboarding-y-conceptos)
    - [Configuración del módulo contable](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#configuraci%C3%B3n-del-m%C3%B3dulo-contable)
    - [Reglas y automatización](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#reglas-y-automatizaci%C3%B3n)
    - [Asientos y comprobantes](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#asientos-y-comprobantes)
    - [Reportes financieros](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#reportes-financieros)
    - [Certificados y exógena](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-contabilidad?hsLang=es#certificados-y-ex%C3%B3gena)
- [Módulo de Nómina](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#main-content)

    - [Onboarding y conceptos](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#onboarding-y-conceptos)
    - [Configuración de Nómina](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#configuraci%C3%B3n-de-n%C3%B3mina)
    - [Empleados, contratos y terminaciones](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#empleados-contratos-y-terminaciones)
    - [Novedades y horas extras](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#novedades-y-horas-extras)
    - [Liquidación de Nómina](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#liquidaci%C3%B3n-de-n%C3%B3mina)
    - [Prestaciones Sociales](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#prestaciones-sociales)
    - [Colillas de Pago](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#colillas-de-pago)
    - [Nómina Electrónica](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-n%C3%B3mina?hsLang=es#n%C3%B3mina-electr%C3%B3nica)
- [Módulo de Compras](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#main-content)

    - [Compras](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#compras)
    - [Documento Soporte](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#documento-soporte)
    - [Habilitar Documento Soporte](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#habilitar-documento-soporte)
    - [Eventos de Recepción](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#eventos-de-recepci%C3%B3n)
    - [Errores, notificaciones y rechazos de Eventos de Recepción](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#errores-notificaciones-y-rechazos-de-eventos-de-recepci%C3%B3n)
    - [Facturas Electrónicas de Compra](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-compras?hsLang=es#facturas-electr%C3%B3nicas-de-compra)
- [Módulo de Cartera](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-cartera?hsLang=es#main-content)

    - [Onboarding](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-cartera?hsLang=es#onboarding)
    - [Cuentas por Cobrar y cuentas por Pagar](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-cartera?hsLang=es#cuentas-por-cobrar-y-cuentas-por-pagar)
    - [Bancos.](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-cartera?hsLang=es#bancos)
    - [Configuración Módulo de Cartera](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-cartera?hsLang=es#configuraci%C3%B3n-m%C3%B3dulo-de-cartera)
- [Módulo de Productos e Inventarios](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-productos-e-inventarios?hsLang=es#main-content)

    - [Productos](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-productos-e-inventarios?hsLang=es#productos)
    - [Inventarios.](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-productos-e-inventarios?hsLang=es#inventarios)
    - [Ajuste de inventarios.](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-productos-e-inventarios?hsLang=es#ajuste-de-inventarios)
    - [Productos de compra.](https://portaldelcliente.dataico.com/es/knowledge/m%C3%B3dulo-de-productos-e-inventarios?hsLang=es#productos-de-compra)
- [Suscripciones](https://portaldelcliente.dataico.com/es/knowledge/suscripciones?hsLang=es)
- [Integración API DATAICO S.A.S](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#main-content)

    - [Modelo de Integración API DATAICO S.A.S](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#modelo-de-integraci%C3%B3n-api-dataico-s-a-s)
    - [Factura Electrónica.](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#factura-electr%C3%B3nica)
    - [Guía de Solución de Problemas API DATAICO FE](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#gu%C3%ADa-de-soluci%C3%B3n-de-problemas-api-dataico-fe)
    - [Nómina Electrónica.](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#n%C3%B3mina-electr%C3%B3nica)
    - [Documento Soporte (DS)](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#documento-soporte-ds)
    - [Eventos de Recepción (EV)](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#eventos-de-recepci%C3%B3n-ev)
    - [Sector Salud](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#sector-salud)
    - [POS ELECTRÓNICO](https://portaldelcliente.dataico.com/es/knowledge/integraci%C3%B3n-api-dataico-s-a-s?hsLang=es#pos-electr%C3%B3nico)
- [Importaciones](https://portaldelcliente.dataico.com/es/knowledge/importaciones?hsLang=es#main-content)

    - [General](https://portaldelcliente.dataico.com/es/knowledge/importaciones?hsLang=es#general)
    - [Contabilidad](https://portaldelcliente.dataico.com/es/knowledge/importaciones?hsLang=es#contabilidad)
    - [Productos](https://portaldelcliente.dataico.com/es/knowledge/importaciones?hsLang=es#productos)
    - [Terceros](https://portaldelcliente.dataico.com/es/knowledge/importaciones?hsLang=es#terceros)
- [Preguntas frecuentes (FAQ)](https://portaldelcliente.dataico.com/es/knowledge/preguntas-frecuentes-faq?hsLang=es)
- [Anexos Técnicos y Resoluciones](https://portaldelcliente.dataico.com/es/knowledge/anexos-t%C3%A9cnicos-y-resoluciones?hsLang=es#main-content)

    - [Resolución 000119 de 2024.](https://portaldelcliente.dataico.com/es/knowledge/anexos-t%C3%A9cnicos-y-resoluciones?hsLang=es#resoluci%C3%B3n-000119-de-2024)
    - [Anexo 1.9](https://portaldelcliente.dataico.com/es/knowledge/anexos-t%C3%A9cnicos-y-resoluciones?hsLang=es#anexo-1-9)
- [Recursos adicionales](https://portaldelcliente.dataico.com/es/knowledge/recursos-adicionales?hsLang=es)
- [Shopify](https://portaldelcliente.dataico.com/es/knowledge/shopify?hsLang=es)

[![Chill listening crop-3](https://portaldelcliente.dataico.com/hs-fs/hubfs/Lod%20DT.png?width=110&height=32&name=Lod%20DT.png "Chill listening crop-3")](https://www.dataico.com/)

Copyright © 2026, DATAICO S.A.S