Envío en bloque de nómina electrónica: respuesta asíncrona con job-id

Los endpoints de envío en bloque de nómina electrónica responden de forma asíncrona. No devuelven el resultado del procesamiento en la misma llamada: guardan el lote, lo encolan y responden de inmediato con un identificador de trabajo (job-id).

Aplica a la API v2: https://api.dataico.com/direct/payroll-api/v2. Sin /v2 responde la versión anterior de la API, que no sigue este flujo. El cuerpo de un envío en bloque es {"entries": [ ... ]}, con un documento en cada posición.

Cambio de comportamiento

Todas las validaciones del lote corren dentro del trabajo asíncrono, no durante la petición:

la importación del JSON (formato y campos de cada documento),
el cupo de documentos de tu plan,
un único prefijo y un único periodo por lote (en nóminas y notas de reemplazo),
la restricción de las empresas con el modelo de empleado con fecha de vigencia, que no pueden enviar nóminas ni notas de reemplazo por API (ver Documentación Técnica de la API de Nómina Electrónica),
las validaciones de cada documento.

Antes	Ahora
Un lote inválido respondía `400` de forma sincrónica con la lista de errores	La petición responde `201` con el `job-id`; los errores se consultan después en `/job-status/{job-id}`

Un cliente que esperaba el 400 sincrónico debe migrar al flujo de consulta de estado.

Paso 1: enviar el lote

Método	Endpoint	Qué envía
`POST`	`https://api.dataico.com/direct/payroll-api/v2/payroll-entries-batch`	Comprobantes de nómina
`POST`	`https://api.dataico.com/direct/payroll-api/v2/payroll-replacements-batch`	Notas de reemplazo
`POST`	`https://api.dataico.com/direct/payroll-api/v2/payroll-deletions-batch`	Notas de eliminación

Respuesta (HTTP 201):

{ "job-id": "3f2a…" }

Paso 2: consultar el estado

GET https://api.dataico.com/direct/payroll-api/v2/job-status/{job-id}

HTTP	`status`	Significado
`202`	`queued` o `in-progress`	El trabajo sigue procesando. `progress` indica el porcentaje.
`200`	`done`	El lote terminó de procesarse. `progress` es `100`. Revisa el resultado: cada documento que no se pudo crear aparece con `"status": "FAILED"` y su lista de `errors`.
`200`	`failed`	El lote completo se rechazó. Trae `errors`, un arreglo de objetos con `message` explicando cada motivo.
`404`	`not-found`	No se encontró el trabajo.

Ejemplo de un lote rechazado (HTTP 200):

{
  "job-id":   "3f2a…",
  "status":   "failed",
  "progress": 100,
  "errors":   [ { "message": "…motivo del fallo…" } ]
}

Importante: un lote rechazado responde 200, no un código de error. Lo que indica el fallo es el campo status con valor failed. Al recibirlo, deja de consultar el estado y revisa errors.

Si el único mensaje es La importación falló!, alguno de los documentos tiene un error de formato (por ejemplo, un campo con un nombre que no existe o un valor fuera de rango) y la respuesta del lote no indica cuál. Para ver el campo exacto, envía ese documento al endpoint individual en ambiente de pruebas ("env": "PRUEBAS"): su respuesta trae el path del error.

Este endpoint aplica una demora deliberada de medio segundo en cada respuesta, para desincentivar la consulta en bucle cerrado. Consulta con intervalos razonables.

Paso 3: obtener el resultado

GET https://api.dataico.com/direct/payroll-api/v2/batch-result/{job-id}

Responde con una redirección (HTTP 307) al archivo con el resultado del lote. Tu cliente HTTP debe seguir la redirección; la mayoría lo hace por defecto.

El resultado es un arreglo con un elemento por documento del lote:

Un documento creado trae los mismos campos que una consulta: cune, number, dian_status, email_status, dian_messages, qrcode, request_xml, response_xml y pdf. Ver Consultar nómina por API.
Un documento que no se pudo crear trae "status": "FAILED" y el motivo:

{
  "number": "N38",
  "status": "FAILED",
  "errors": [ { "message": "…motivo…" } ]
}

Si el resultado todavía no está disponible, /batch-result/{job-id} responde HTTP 404:

{ "message": "No se encuentra ese 'job'. Quizas no esta terminado de processar" }

Ese mensaje significa que el resultado aún no está listo: consulta /job-status/{job-id} y vuelve a pedir el resultado cuando el status sea done.

Flujo recomendado

POST al endpoint en bloque y guarda el job-id de la respuesta 201.
Consulta /job-status/{job-id} con intervalos razonables.
Si status es failed, detente y procesa errors.
Si status es done, pide /batch-result/{job-id} y revisa los documentos con "status": "FAILED".