Guía de errores de la API de Nómina Electrónica

Este artículo cubre los errores más comunes al integrar la API v2 de Nómina Electrónica de Dataico. Para cada error se incluye el mensaje que devuelve la API, la causa y la solución.

En los endpoints individuales el error llega en la respuesta del POST, dentro de errors. En los envíos por lotes llega después: en el message de /job-status/{job-id} si se rechazó el lote completo, o en el elemento con "status": "FAILED" del resultado si falló un documento. Ver Envío en bloque de nómina electrónica: respuesta asíncrona con job-id.

---

Error: software no encontrado (pin y dian_id)

Detalle (response)

{
  "error-code": "not-found",
  "message": "Revisar los siguientes campos: pin, dian-id: uno de estos valores es incorrecto verifica los datos y corrigelo"
}

La respuesta trae además el path del objeto software y los valores que enviaste.

Explicación

Dataico busca el software de nómina de tu empresa con el pin y el dian_id del objeto software. El error ocurre cuando esos valores no coinciden con el software registrado, o cuando tu empresa aún no ha habilitado la nómina electrónica en Dataico.

El pin y el dian_id son iguales para todas las cuentas. El test_set_id es propio de cada empresa y no hace falta enviarlo; si lo envías, no se usa para identificar el software.

Solución

1. Asegúrate de que el objeto software sea:

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

2. Si los valores ya son esos, habilita la nómina electrónica de tu empresa en Dataico o escríbenos al chat de soporte.

---

Error: invalid-key o missing-key en accruals

Detalle (response)

{ "error-code": "invalid-key", "path": ["accruals", 1, "amount-n"] }

{ "error-code": "missing-key", "message": "Falta un atributo ..." }

Explicación

• invalid-key: el campo indicado en path no existe en ese objeto. El nombre está mal escrito (por ejemplo amount-n en lugar de amount-ns, o dias en lugar de days). Los nombres aceptan guion o guion bajo y no distinguen mayúsculas: amount-ns y amount_ns son el mismo campo.
• missing-key: el concepto exige un campo que no enviaste. Pasa, por ejemplo, cuando un concepto que solo admite valor no salarial se envía con amount en lugar de amount-ns.

Solución

1. Ubica el devengado: en el ejemplo, la posición 1 del arreglo accruals.
2. Compara sus campos con la tabla de conceptos de la Documentación Técnica de Nómina. DOTACION, APOYO_PRACTICA, BONIFICACION_RETIRO, INDEMNIZACION, VACACION_COMPENSADA y CESANTIAS exigen amount-ns. Por ejemplo: si el concepto es DOTACION y lo enviaste con amount, cámbialo a amount-ns.
3. Corrige el nombre del campo o agrega el que falta, y reenvía el JSON.

---

Error: días fuera de rango en accruals

Las dos respuestas indican días fuera de rango, pero en conceptos distintos.

Detalle (response, variante 1)

{
  "errors": [
    {
      "error-code": "invalid-value",
      "path": ["accruals", 3],
      "message": "unknown error"
    }
  ]
}

Aparece en VACACION o LICENCIA_PATERNIDAD: days debe ser mayor que 0 y como máximo 30.

Detalle (response, variante 2)

{
  "errors": [
    {
      "path": [0, "accruals", 0, 0, 0, "base-salary", "days"],
      "in": ["accruals", 3, "precise-days"],
      "value": 50.0
    }
  ]
}

Aparece en BASICO cuando days supera el máximo admitido (acepta decimales). El mismo formato aparece en PRIMA si days supera 180; en ese caso el path dice prima. En in, el número indica la posición del devengado en accruals.

Días admitidos por devengado

Solución

Revisa el devengado en la posición indicada y corrige days para que esté dentro del rango de la tabla.

---

Error: operación deshabilitada (modelo de empleado con fecha de vigencia)

Detalle (response)

{
  "errors": [
    {
      "error-code": "bt-employee-active",
      "message": "Operación deshabilitada: la gestión de empleados por tiempo de negocio (BT) está activa para esta empresa. Por favor, contacte a soporte."
    }
  ]
}

En un envío por lotes, el mismo mensaje llega en errors de /job-status/{job-id} con "status": "failed".

Explicación

Tu empresa registra los cambios de sus empleados con fecha de vigencia (la ficha del empleado con el panel Añadir novedad). Con este modelo, la API no acepta nóminas ni notas de reemplazo, ni individuales ni por lotes. Las empresas nuevas tienen este modelo activo desde su creación. Las notas de eliminación y las consultas sí funcionan.

Solución

Escríbenos al chat de soporte: este modelo solo lo puede cambiar el equipo de soporte.

---

Si el error no aparece en esta guía, consulta el Swagger de la API v2 de Nómina Electrónica o escríbenos al chat de soporte con el response completo y el JSON que estás enviando.

Recursos Adicionales

• Documentación Técnica de la API de Dataico para Nómina Electrónica
• Envío en bloque de nómina electrónica: respuesta asíncrona con job-id
• Consultar nómina por API
• Crear nota de reemplazo
• Crear nota de eliminación