Nómina electrónica

1 · Qué es el documento soporte de pago de nómina

No es una factura. Es el documento con el que un empleador le reporta a la DIAN lo que le pagó a un trabajador en un periodo, para poder deducir ese pago como costo o gasto. Se emite por trabajador y por periodo, no uno por empresa.

Su código es 102 y su identificador único se llama CUNE, el equivalente del CUFE de una factura. Como el CUFE, se calcula desde los valores del documento: la DIAN recalcula el total devengado y el total deducido a partir de los conceptos, de modo que un concepto cuyo valor no cuadre con su cantidad y su porcentaje cambia el CUNE y produce un rechazo.

2 · Cómo se corrige: dos notas, no una

Un documento de nómina ya reportado no se modifica. Se corrige con una nota de ajuste —103— y lo que distingue las dos clases es el campo tdnota:

• tdnota = 1 · Reemplazar — sustituye el documento por completo. Se envía con la liquidación completa y corregida, no con la diferencia: todo lo que trajera el original y no venga en la nota se pierde. Es el error más frecuente al integrar el ajuste por primera vez.
• tdnota = 2 · Eliminar — anula el documento sin poner otro en su lugar. No lleva devengos ni deducciones, porque no hay liquidación que reemplazar: solo identifica el documento que se anula.

En los dos casos el documento afectado va en docreferencia, identificado por su CUNE, y la nota genera su propio CUNE.

3 · Los códigos td… del nivel raíz

Igual que en facturación, todo campo que empieza por td es un código del anexo técnico de la DIAN, no un texto libre, y el módulo los modela como listas cerradas: un valor fuera de la lista no produce un error de formato, se descarta al asignarlo y llega vacío al XML, que cuesta más de diagnosticar.

Estos son los del nivel raíz, los que se resuelven antes de armar cualquier bloque. Los que viven dentro de un objeto —la clase de trabajador, su subclase y el tipo de contrato en TTrabajador, la forma y el medio de pago en TPago, el origen de una incapacidad en las formas de un concepto— están en la tabla de su objeto, en la sección siguiente.

Desliza la tabla para verla completa.

4 · Anatomía del JSON de nómina

El documento responde tres preguntas: quién paga, a quién y cuánto. El «cuánto» es lo que ocupa más espacio, porque son dos árboles de conceptos.

• empleador

  Quien paga. En el sandbox su identidad se reemplaza por la de la empresa de pruebas, porque es el único NIT habilitado ante la DIAN.

• trabajador

  A quien se le paga, con su tipo de documento, su tipo de trabajador, su tipo de contrato, si es de alto riesgo y si devenga salario integral. El sandbox NO lo reemplaza: es tuyo por completo.

• periodoliquidar · periodocontrato · qdiaslaborados · tdperiodo

  Qué periodo se liquida, desde cuándo está vigente el contrato, cuántos días se laboraron y con qué periodicidad se paga. La DIAN cuenta el mes comercial de 30 días.

• pago

  Forma y medio de pago, la cuenta destino y las fechas en que efectivamente se paga.

• devengos

  Todo lo que suma: básico, auxilio de transporte, horas extra y recargos, vacaciones, prestaciones, incapacidades, licencias, bonificaciones y conceptos libres. Cada concepto es un arreglo, porque puede ocurrir varias veces en el mismo periodo — tres incapacidades, dos primas. Solo básico es obligatorio.

• deducciones

  Todo lo que se descuenta: salud, pensión, fondo de solidaridad, retención en la fuente, libranzas, anticipos y aportes voluntarios. Misma estructura de arreglos por concepto.

La tabla de datos de cada ficha nombra el tipo de cada campo —TTrabajador, TDevengos— y desde ahí enlaza a estos títulos, que son los que dicen qué va dentro. Los objetos que nómina comparte con facturación —el empleador como TTercero, la ubicación, la resolución y la referencia al documento que se ajusta— están documentados en el concepto de facturación, y las fichas enlazan allá: es el mismo objeto.

El asterisco marca lo que hay que enviar, igual que en la tabla de datos de cada ficha, y «no se envía» los que calcula el Proveedor Tecnológico: van en la respuesta y en el XML, pero mandarlos no cambia nada porque se recalculan siempre. Lo que depende de otro dato lo dice la explicación del atributo.

5 · En qué se diferencia de facturación

6 · Cómo lo resuelve el sandbox

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"])

Los tres procesos que siguen son iguales para todas las funciones del portal. El primero contesta por que el documento que recibes de vuelta no es idéntico al que enviaste —en nómina, con una diferencia que vale la pena retener: el trabajador se conserva, porque la DIAN no lo valida contra la empresa habilitada—. El segundo, por qué un reenvío puede responder 409 con la regla 90; en nómina conviene leerlo con atención, porque la nota de ajuste responde 409 en todo reenvío. El tercero, por qué una función puede responder 401 aunque tu JSON esté perfecto.

flowchart TD
    J(["Documento que envía el desarrollador"]) --> A["Ambiente: siempre habilitación"]
    A --> B["Identidad del emisor y del receptor:<br/>la de la empresa de pruebas"]
    B --> C["Se conservan ubicación, responsabilidades<br/>fiscales y datos de contacto"]
    C --> D["Resolución y numeración:<br/>las del sandbox, si están registradas"]
    D --> E["Todo lo demás viaja como se envió:<br/>ítems, tributos, descuentos y totales"]
    E --> F(["Se reporta a la DIAN"])

flowchart TD
    A(["Se envía un documento<br/>con una numeración"]) --> B{"¿Esa numeración ya se reportó?"}
    B -- No --> S(["Sigue el proceso normal de emisión"])
    B -- Sí --> C{"¿El documento sigue siendo el mismo?"}
    C -- Sí --> D(["200 · devuelve el que ya se reportó,<br/>sin duplicarlo"])
    C -- No --> E(["409 · regla 90, rechazo, y entrega<br/>el XML del documento"])

flowchart TD
    R(["Petición del desarrollador<br/>Authorization: Bearer idToken"]) --> T{"¿Viene el token?"}
    T -- No --> E1(["400 · No se especificó el token<br/>de autenticación"])
    T -- Sí --> F{"¿El token es válido?"}
    F -- No --> E2(["401 · Token de autenticación no válido"])
    F -- Sí --> Q{"¿Perfil registrado y activo?"}
    Q -- No --> E4(["401 · Perfil no registrado o suspendido,<br/>con el motivo en el mensaje"])
    Q -- Sí --> OK(["200 · Autorizado, continúa la operación"])