POST /api/nomina/nomina/

Nómina electrónica y su nota de ajuste.

Comparte el ciclo de vida de los documentos electrónicos —borrador, firmado, enviado, aceptado o rechazado— pero no su pipeline: la nómina no es UBL y va por SendNominaSync.

Sin PUT ni PATCH, por lo mismo que en DocumentoViewSet: un documento fiscal es un hecho con fecha, número y firma, y editarlo en sitio abre la puerta a que lo que se emitió y lo que se guarda dejen de coincidir. Mientras es borrador, corregirlo es borrarlo y volver a crearlo; una vez emitido, lo que corrige una nómina es su nota de ajuste (tipo_xml 103), que la DIAN tiene prevista justamente para esto.

Lo que cambia el documento son las acciones, cada una con su regla. El estado no es un campo que se escriba.

operationId: nomina_nomina_create

Autenticación

Cualquiera de estas credenciales:

LlaveApi — Llave de API de una integración. El valor completo es Api-Key <prefijo>.<secreto>, tal como lo imprime manage.py crear_llave_api. La llave alcanza exactamente los mismos emisores que la persona a cuyo nombre se creó.

Cuerpo de la petición

Tipo de contenido: application/json · obligatorio.

Campos

Campo	Tipo	Obligatorio	Descripción
`emisor`	integer	sí
`empleado`	`EmpleadoAnidadoRequest`	sí	El empleado tal como viaja dentro de la nómina. Igual que el de su endpoint pero sin `emisor` —lo pone la nómina, que ya lo trae— y sin el validador de unicidad, porque aquí el par emisor + identificación no identifica un error sino al empleado que hay que crear o actualizar: la nómina hace ese upsert al guardarse. Estricto: una clave que no sea un campo escribible responde 400. Aquí importa más que en el endpoint del empleado, porque un campo mal escrito haría heredar a la nómina el valor viejo del maestro sin que nadie se enterara.
`prefijo`	string	no	Lo elige el emisor: la nómina no se numera con resolución de la DIAN (regla NIE010).
`consecutivo`	integer (int64)	sí
`tipo_xml`	any	no
`tipo_nota`	any	no	Vacío en la nómina; obligatorio en la nota de ajuste. * `1` - Reemplazar * `2` - Eliminar
`nomina_predecesora`	string (uuid)	no	Admite `null`.
`periodo_nomina`	integer (int64)	sí	Valor del catálogo `periodo-nomina`: se envía el `id`.
`fecha_liquidacion_inicio`	string (date)	sí
`fecha_liquidacion_fin`	string (date)	sí
`tiempo_laborado`	integer	sí	Días laborados en el periodo (numeral 8.3.1).
`fecha_generacion`	string (date)	sí
`hora_generacion`	string (time)	sí
`fecha_pago`	string (date)	sí
`moneda`	integer (int64)	sí	Valor del catálogo `moneda`: se envía el `id`.
`trm`	string (decimal)	no	Solo cuando la moneda no es COP. Admite `null`.
`notas`	string	no
`novedad`	boolean	no
`cune_novedad`	string	no
`total_devengados`	string (decimal)	no
`total_deducciones`	string (decimal)	no
`redondeo`	string (decimal)	no
`total_comprobante`	string (decimal)	no	Devengados menos deducciones, más el redondeo.
`conceptos`	`array<NominaConceptoRequest>`	no
`codigo_trabajador`	string	no	Va en NumeroSecuenciaXML, que identifica el documento.
`alto_riesgo_pension`	boolean	no
`salario_integral`	boolean	no
`sueldo`	string (decimal)	no
`tipo_trabajador`	integer (int64)	no	Valor del catálogo `tipo-trabajador`: se envía el `id`.
`subtipo_trabajador`	integer (int64)	no	Valor del catálogo `subtipo-trabajador`: se envía el `id`.
`tipo_contrato`	integer (int64)	no	Valor del catálogo `tipo-contrato`: se envía el `id`.
`lugar_trabajo_pais`	integer (int64)	no	Valor del catálogo `pais`: se envía el `id`.
`lugar_trabajo_departamento`	integer (int64)	no	Valor del catálogo `departamento`: se envía el `id`.
`lugar_trabajo_municipio`	integer (int64)	no	Valor del catálogo `municipio`: se envía el `id`.
`lugar_trabajo_direccion`	string	no
`forma_pago`	integer (int64)	no	Valor del catálogo `forma-pago`: se envía el `id`.
`medio_pago`	integer (int64)	no	Valor del catálogo `medio-pago`: se envía el `id`.
`banco`	string	no
`tipo_cuenta`	any	no
`numero_cuenta`	string	no
`fecha_retiro`	string (date)	no	Admite `null`.

Ejemplo

curl -X POST "https://api.rededoc.uk/api/nomina/nomina/" \
  -H "Authorization: <llaveapi>" \
  -H "Content-Type: application/json" \
  -d '{
    "emisor": 1,
    "empleado": {
      "tipo_identificacion": -9223372036854776000,
      "numero_documento": "texto",
      "primer_apellido": "texto",
      "segundo_apellido": "texto",
      "primer_nombre": "texto",
      "otros_nombres": "texto",
      "codigo_trabajador": "texto",
      "tipo_trabajador": -9223372036854776000,
      "subtipo_trabajador": -9223372036854776000,
      "tipo_contrato": -9223372036854776000,
      "alto_riesgo_pension": true,
      "salario_integral": true,
      "sueldo": "0.00",
      "fecha_ingreso": "2026-01-31",
      "pais": -9223372036854776000,
      "departamento": -9223372036854776000,
      "municipio": -9223372036854776000,
      "direccion": "texto",
      "forma_pago": -9223372036854776000,
      "medio_pago": -9223372036854776000,
      "banco": "texto",
      "tipo_cuenta": null,
      "numero_cuenta": "texto"
    },
    "prefijo": "texto",
    "consecutivo": 0,
    "tipo_xml": null,
    "tipo_nota": null,
    "nomina_predecesora": "00000000-0000-0000-0000-000000000000",
    "periodo_nomina": -9223372036854776000,
    "fecha_liquidacion_inicio": "2026-01-31",
    "fecha_liquidacion_fin": "2026-01-31",
    "tiempo_laborado": 0,
    "fecha_generacion": "2026-01-31",
    "hora_generacion": "texto",
    "fecha_pago": "2026-01-31",
    "moneda": -9223372036854776000,
    "trm": "0.00",
    "notas": "texto",
    "novedad": true,
    "cune_novedad": "texto",
    "total_devengados": "0.00",
    "total_deducciones": "0.00",
    "redondeo": "0.00",
    "total_comprobante": "0.00",
    "conceptos": [
      {
        "grupo": "devengado",
        "concepto": "basico",
        "cantidad": "0.00",
        "porcentaje": "0.00",
        "valor": "0.00",
        "valor_no_salarial": "0.00",
        "fecha_inicio": "2026-01-31",
        "fecha_fin": "2026-01-31",
        "hora_inicio": "2026-01-31T10:00:00-05:00",
        "hora_fin": "2026-01-31T10:00:00-05:00",
        "descripcion": "texto",
        "tipo_incapacidad": null
      }
    ],
    "codigo_trabajador": "texto",
    "alto_riesgo_pension": true,
    "salario_integral": true,
    "sueldo": "0.00",
    "tipo_trabajador": -9223372036854776000,
    "subtipo_trabajador": -9223372036854776000,
    "tipo_contrato": -9223372036854776000,
    "lugar_trabajo_pais": -9223372036854776000,
    "lugar_trabajo_departamento": -9223372036854776000,
    "lugar_trabajo_municipio": -9223372036854776000,
    "lugar_trabajo_direccion": "texto",
    "forma_pago": -9223372036854776000,
    "medio_pago": -9223372036854776000,
    "banco": "texto",
    "tipo_cuenta": null,
    "numero_cuenta": "texto",
    "fecha_retiro": "2026-01-31"
  }'

Respuestas

Código	Descripción
`201`
`400`	Error
`401`	Error
`429`	Error

`201` — cuerpo

Campo	Tipo	Descripción
`id`	string (uuid)	Solo lectura.
`emisor`	integer
`empleado`	`EmpleadoAnidado`	El empleado tal como viaja dentro de la nómina. Igual que el de su endpoint pero sin `emisor` —lo pone la nómina, que ya lo trae— y sin el validador de unicidad, porque aquí el par emisor + identificación no identifica un error sino al empleado que hay que crear o actualizar: la nómina hace ese upsert al guardarse. Estricto: una clave que no sea un campo escribible responde 400. Aquí importa más que en el endpoint del empleado, porque un campo mal escrito haría heredar a la nómina el valor viejo del maestro sin que nadie se enterara.
`prefijo`	string	Lo elige el emisor: la nómina no se numera con resolución de la DIAN (regla NIE010).
`consecutivo`	integer (int64)
`numero`	string	Número del documento. Si se omite, se arma como prefijo + consecutivo. Solo lectura.
`tipo_xml`	any
`tipo_nota`	any	Vacío en la nómina; obligatorio en la nota de ajuste. * `1` - Reemplazar * `2` - Eliminar
`nomina_predecesora`	string (uuid)	Admite `null`.
`periodo_nomina`	integer (int64)	Valor del catálogo `periodo-nomina`: se envía el `id`.
`fecha_liquidacion_inicio`	string (date)
`fecha_liquidacion_fin`	string (date)
`tiempo_laborado`	integer	Días laborados en el periodo (numeral 8.3.1).
`fecha_generacion`	string (date)
`hora_generacion`	string (time)
`fecha_pago`	string (date)
`moneda`	integer (int64)	Valor del catálogo `moneda`: se envía el `id`.
`trm`	string (decimal)	Solo cuando la moneda no es COP. Admite `null`.
`notas`	string
`novedad`	boolean
`cune_novedad`	string
`total_devengados`	string (decimal)
`total_deducciones`	string (decimal)
`redondeo`	string (decimal)
`total_comprobante`	string (decimal)	Devengados menos deducciones, más el redondeo.
`conceptos`	`array<NominaConcepto>`
`codigo_trabajador`	string	Va en NumeroSecuenciaXML, que identifica el documento.
`alto_riesgo_pension`	boolean
`salario_integral`	boolean
`sueldo`	string (decimal)
`tipo_trabajador`	integer (int64)	Valor del catálogo `tipo-trabajador`: se envía el `id`.
`subtipo_trabajador`	integer (int64)	Valor del catálogo `subtipo-trabajador`: se envía el `id`.
`tipo_contrato`	integer (int64)	Valor del catálogo `tipo-contrato`: se envía el `id`.
`lugar_trabajo_pais`	integer (int64)	Valor del catálogo `pais`: se envía el `id`.
`lugar_trabajo_departamento`	integer (int64)	Valor del catálogo `departamento`: se envía el `id`.
`lugar_trabajo_municipio`	integer (int64)	Valor del catálogo `municipio`: se envía el `id`.
`lugar_trabajo_direccion`	string
`forma_pago`	integer (int64)	Valor del catálogo `forma-pago`: se envía el `id`.
`medio_pago`	integer (int64)	Valor del catálogo `medio-pago`: se envía el `id`.
`banco`	string
`tipo_cuenta`	any
`numero_cuenta`	string
`fecha_retiro`	string (date)	Admite `null`.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "emisor": 1,
  "empleado": {
    "id": 1,
    "tipo_identificacion": -9223372036854776000,
    "tipo_identificacion_codigo": "texto",
    "numero_documento": "texto",
    "primer_apellido": "texto",
    "segundo_apellido": "texto",
    "primer_nombre": "texto",
    "otros_nombres": "texto",
    "nombre_completo": "texto",
    "codigo_trabajador": "texto",
    "tipo_trabajador": -9223372036854776000,
    "subtipo_trabajador": -9223372036854776000,
    "tipo_contrato": -9223372036854776000,
    "alto_riesgo_pension": true,
    "salario_integral": true,
    "sueldo": "0.00",
    "fecha_ingreso": "2026-01-31",
    "pais": -9223372036854776000,
    "departamento": -9223372036854776000,
    "municipio": -9223372036854776000,
    "direccion": "texto",
    "forma_pago": -9223372036854776000,
    "medio_pago": -9223372036854776000,
    "banco": "texto",
    "tipo_cuenta": null,
    "numero_cuenta": "texto",
    "activo": true,
    "creado_en": "2026-01-31T10:00:00-05:00",
    "actualizado_en": "2026-01-31T10:00:00-05:00"
  },
  "prefijo": "texto",
  "consecutivo": 0,
  "numero": "texto",
  "tipo_xml": null,
  "tipo_nota": null,
  "nomina_predecesora": "00000000-0000-0000-0000-000000000000",
  "periodo_nomina": -9223372036854776000,
  "fecha_liquidacion_inicio": "2026-01-31",
  "fecha_liquidacion_fin": "2026-01-31",
  "tiempo_laborado": 0,
  "fecha_generacion": "2026-01-31",
  "hora_generacion": "texto",
  "fecha_pago": "2026-01-31",
  "moneda": -9223372036854776000,
  "trm": "0.00",
  "notas": "texto",
  "novedad": true,
  "cune_novedad": "texto",
  "total_devengados": "0.00",
  "total_deducciones": "0.00",
  "redondeo": "0.00",
  "total_comprobante": "0.00",
  "conceptos": [
    {
      "id": 1,
      "grupo": "devengado",
      "concepto": "basico",
      "concepto_nombre": "texto",
      "cantidad": "0.00",
      "porcentaje": "0.00",
      "valor": "0.00",
      "valor_no_salarial": "0.00",
      "fecha_inicio": "2026-01-31",
      "fecha_fin": "2026-01-31",
      "hora_inicio": "2026-01-31T10:00:00-05:00",
      "hora_fin": "2026-01-31T10:00:00-05:00",
      "descripcion": "texto",
      "tipo_incapacidad": null
    }
  ],
  "codigo_trabajador": "texto",
  "alto_riesgo_pension": true,
  "salario_integral": true,
  "sueldo": "0.00",
  "tipo_trabajador": -9223372036854776000,
  "subtipo_trabajador": -9223372036854776000,
  "tipo_contrato": -9223372036854776000,
  "lugar_trabajo_pais": -9223372036854776000,
  "lugar_trabajo_departamento": -9223372036854776000,
  "lugar_trabajo_municipio": -9223372036854776000,
  "lugar_trabajo_direccion": "texto",
  "forma_pago": -9223372036854776000,
  "medio_pago": -9223372036854776000,
  "banco": "texto",
  "tipo_cuenta": null,
  "numero_cuenta": "texto",
  "fecha_retiro": "2026-01-31"
}

`400` — cuerpo

Campo	Tipo	Descripción
`detail`	string	Mensaje para mostrar a la persona.
`errores`	`array<object>`	Nunca vacía. Cada error trae `codigo`, que es lo que el cliente mapea —los de DRF tal cual (`required`, `invalid`, `does_not_exist`, `not_found`…) y los propios en español (`campo_desconocido`, `solicitud_invalida`…)—, y `mensaje`, para la persona. Si el error es de un campo, su ruta va delante del mensaje: `detalles[0].impuestos[0].tributo: Este campo es obligatorio.`

{
  "detail": "texto",
  "errores": [
    {
      "codigo": "texto",
      "mensaje": "texto"
    }
  ]
}

`401` — cuerpo

Campo	Tipo	Descripción
`detail`	string	Mensaje para mostrar a la persona.
`errores`	`array<object>`	Nunca vacía. Cada error trae `codigo`, que es lo que el cliente mapea —los de DRF tal cual (`required`, `invalid`, `does_not_exist`, `not_found`…) y los propios en español (`campo_desconocido`, `solicitud_invalida`…)—, y `mensaje`, para la persona. Si el error es de un campo, su ruta va delante del mensaje: `detalles[0].impuestos[0].tributo: Este campo es obligatorio.`

{
  "detail": "texto",
  "errores": [
    {
      "codigo": "texto",
      "mensaje": "texto"
    }
  ]
}

`429` — cuerpo

Campo	Tipo	Descripción
`detail`	string	Mensaje para mostrar a la persona.
`errores`	`array<object>`	Nunca vacía. Cada error trae `codigo`, que es lo que el cliente mapea —los de DRF tal cual (`required`, `invalid`, `does_not_exist`, `not_found`…) y los propios en español (`campo_desconocido`, `solicitud_invalida`…)—, y `mensaje`, para la persona. Si el error es de un campo, su ruta va delante del mensaje: `detalles[0].impuestos[0].tributo: Este campo es obligatorio.`

{
  "detail": "texto",
  "errores": [
    {
      "codigo": "texto",
      "mensaje": "texto"
    }
  ]
}

RedEDoc es un servicio de Semántica Digital S.A.S.