Enviar nota de ajuste de nómina
Corrige un documento de nómina ya reportado, reemplazando su liquidación.
/api/DocumentoNE La nota de ajuste —tddocumentoelectronico en 103 con tdnota en 1— reemplaza un documento de nómina ya reportado. Un documento de nómina no se modifica: se emite una nota que lo sustituye por completo.
Por eso la nota se envía con la liquidación completa y corregida, no solo con la diferencia: todo lo que traiga el documento original y no venga en la nota se pierde. El documento corregido va en docreferencia identificado por su CUNE, y la nota genera su propio CUNE.
Cómo resuelve el sandbox esta función
Lo primero que se mira es la numeración del documento. Si nunca se reportó, el documento sigue el proceso completo. Si ya se reportó, se compara con el que está guardado: llegando igual responde 200 con el estado del documento, su UUID y el documento adjunto, sin volver a reportarlo ni gastar otro consecutivo; llegando con datos distintos responde 409 con la regla 90 de la DIAN y entrega el XML del documento que sí quedó reportado. Para el documento nuevo siguen las validaciones: un incumplimiento responde 400 con una entrada por regla, cada una con su código de la DIAN, su código de InSoft y su mensaje. Solo cuando las pasa se construye el documento electrónico, se firma, se reporta a la DIAN y se espera su respuesta. Si la DIAN lo rechaza, el 400 trae sus mensajes; si no se pudo establecer conexión con ella, responde también 400 pidiendo reintentar más tarde, y en ese caso el documento no quedó reportado. Las validaciones van antes de construir, así que un documento que no va a ser aceptado se rechaza sin gastar un consecutivo.
Desliza el diagrama para verlo completo.
Ver la fuente Mermaid del diagrama
flowchart TD
A(["El documento llega en JSON"]) --> B{"¿Ya se reportó esa numeración?"}
B -- Sí --> G{"¿Llega igual que antes?"}
G -- Sí --> R0(["200 · estado, UUID y documento adjunto,<br/>sin volver a reportarlo"])
G -- No --> R1(["409 · regla 90, entrega el XML del documento"])
B -- No --> C{"¿Cumple las reglas?"}
C -- No --> R2(["400 · una entrada por regla incumplida,<br/>con su código DIAN y su código InSoft"])
C -- Sí --> D["Construye el documento y lo firma,<br/>lo reporta y espera a la DIAN"]
D --> E{"¿La DIAN lo aceptó?"}
E -- No --> R3(["400 · el rechazo de la DIAN, o «intente más tarde»<br/>si no hubo conexión"])
E -- Sí --> H(["200 · estado del documento, su UUID<br/>y el documento adjunto"])Datos que recibe
Encabezado
Cuerpo
Lo que el sandbox fuerza
El sandbox emite con una integración y una empresa de pruebas compartidas por todos los desarrolladores. Lo que envíes en estos campos no se usa: se sustituye antes de reportar el documento a la DIAN. Todo lo demás viaja tal como lo dejes.
tdambiente2 — Pruebas (habilitación)El sandbox solo emite contra el ambiente de habilitación de la DIAN, sin importar lo que llegue en el documento.
empleador.nitNIT de la empresa de pruebasEs el único NIT que el sandbox tiene habilitado ante la DIAN. El resto del empleador viaja como lo envíes.
resolucion.prefijoEl prefijo del número enviado, o el configurado en el sandboxLa DIAN no exige resolución de nómina en habilitación. Si falta el prefijo, el sandbox lo deduce del
numerodocumento; si tampoco viene, usa el suyo.numerodocumentoPrefijo más el siguiente consecutivo del sandboxCuando el campo no viaja, que es como lo publican los ejemplos: así el documento queda numerado de forma consistente sin que tengas que conseguirte un consecutivo. Ojo con la diferencia frente a facturación, que en su lugar reconoce el valor
<auto>.
Ejecutar la función
Ambiente de habilitación de la DIAN · los documentos son reales pero no tienen efectos tributariosuuid de docreferencia es el CUNE que la DIAN calcula al reportar la nómina, de modo que no hay forma de escribirlo: hay que generarlo. El orden es enviar una nómina electrónica, tomar el uuid que traiga su respuesta y pegarlo aquí antes de enviar la nota.
Lo que se envía
Reemplaza la nómina original agregando horas extra diurnas y recalculando los aportes.
POST https://proveedortecnologico-sandbox.azurewebsites.net/api/DocumentoNE Respuesta
Exportar a Postman
Respuestas
-
200La DIAN recibió el documento. Enrespuestaviajan el CUNE generado, el estado de la DIAN y sus mensajes de validación. -
400El documento no paso las validaciones del PT o de la DIAN. El mensaje indica la regla incumplida. -
401La credencial no llegó, ya venció, o la cuenta no tiene perfil registrado en el sandbox. En producción es además el código con el que se rechaza un emisor que la credencial no tiene autorizado — ver Credenciales y JWT. -
500Falla al firmar o al comunicarse con la DIAN.
Errores frecuentes
-
400El documento referenciado no existe en la DIANEl CUNE de
docreferenciano corresponde a un documento reportado en ese ambiente. En el sandbox debe ser el de una nómina emitida antes desde el propio sandbox. -
401El desarrollador autenticado no tiene un perfil registrado en el sandboxLa cuenta se autenticó pero nunca completó el registro de desarrollador. Se resuelve diligenciando el perfil desde el portal.
-
400El total devengado no corresponde con los conceptos reportadosLa DIAN recalcula el devengado y el deducido desde los conceptos. Un concepto con
valorque no cuadra con sucantidady suporcentajeproduce este rechazo. -
400Los días laborados no corresponden con el periodo liquidadoqdiaslaboradoses incompatible con el rango deperiodoliquidar. La DIAN cuenta el mes comercial de 30 días. -
500El sandbox no tiene registrada la configuración SANDBOX - CONFIG-NEEs un problema de montaje del ambiente, no de la petición. Hay que reportarlo al equipo de InSoft.
Ten en cuenta
- El CUNE no se escribe: se calcula. Lo calcula la DIAN al reportar el documento, de modo que el flujo para probar el ajuste son dos envíos: primero una nómina electrónica, y después esta nota con el CUNE que devolvió esa respuesta en
docreferencia.uuid. - La nota lleva la liquidación completa, no el delta. Es el error más frecuente al integrar el ajuste por primera vez.
- El trabajador no se reemplaza. Es una persona natural que define el desarrollador como parte de su caso de prueba, y la DIAN no lo valida contra la empresa habilitada.
- La resolución de nómina tampoco se fuerza: la DIAN no la exige en el ambiente de habilitación.
- Los devengos y las deducciones viajan sin modificación. Ahí es donde se prueba de verdad la liquidación.
- El sandbox emite con una integración compartida por todos los desarrolladores. El token con el que se reporta a la DIAN lo abre el propio servicio y nunca sale hacia el navegador.