Crea un documento soporte de pago de nómina electrónica

POST/api/v1/documents/payrolls

Un documento por trabajador y período. El empleador es la cuenta (perfil /issuer). Rango de tipo payroll (sin resolución). Los porcentajes de horas extra los pone factuROA según la tabla 5.5.5 del Anexo. Comprobante = devengados − deducciones (no puede ser negativo).

Parámetros de consulta

waitinteger
Segundos (máximo 10) que la petición espera el resultado de la DIAN. Si llega, responde 200 con número, CUFE y estado final; si no, 202 y el resultado llega por webhook. mínimo 0, máximo 10.

Cuerpo de la petición application/json

Montos, cantidades y tarifas van como texto decimal: "5000.00", "19".

external_idstring· máx. 128 caracteresobligatorio
Ejemplo: nomina-2026-11-emp-1
numbering_range_idstring · uuid
Opcional si la cuenta tiene un solo rango activo del tipo de documento
issued_atstring · date-time
notesarray<string>
employeeobjectobligatorio
+ Ver 14 campos− Ocultar 14 campos
- worker_typestringobligatorio
  Tabla 5.5.3 (01 dependiente, 02 servicio doméstico, 12/19 aprendices SENA, 51 tiempo parcial...)
  Ejemplo: 01
- worker_subtypestringobligatorio
  00 no aplica, 01 dependiente pensionado por vejez activo
  Valores: 00 · 01
- high_risk_pensionboolean
- document_typestringobligatorio
  Valores: 11 · 12 · 13 · 21 · 22 · 31 · 41 · 42 · 47 · 50 · 91
- document_numberstringobligatorio
  Ejemplo: 1020304050
- first_surnamestringobligatorio
- second_surnamestring
  Opcional: quien tiene un solo apellido lo omite (aceptado por la DIAN, NE5)
- first_namestringobligatorio
- other_namesstring
- work_addressobjectobligatorio
  + Ver 8 campos− Ocultar 8 campos
  - linestring
    Ejemplo: Cra 7 # 71-21
  - city_codestring
    DIVIPOLA del municipio (5 dígitos)
    Ejemplo: 11001
  - city_namestring
    Ejemplo: Bogotá, D.C.
  - department_codestring
    DIVIPOLA del departamento (2 dígitos)
    Ejemplo: 11
  - department_namestring
    Ejemplo: Bogotá
  - postal_zonestring
  - country_codestring
    ISO 3166-1; vacío = CO
  - country_namestring
- integral_salaryboolean
- contract_typestringobligatorio
  1 término fijo, 2 indefinido, 3 obra o labor, 4 aprendizaje, 5 prácticas
  Valores: 1 · 2 · 3 · 4 · 5
- salarystringobligatorio
  Ejemplo: 5000.00
- codestring
  Código interno del trabajador
periodobjectobligatorio
+ Ver 6 campos− Ocultar 6 campos
- admission_datestring · dateobligatorio
  Ejemplo: 2026-11-30
- retirement_datestring · date
  Ejemplo: 2026-11-30
- settlement_startstring · dateobligatorio
  Ejemplo: 2026-11-30
- settlement_endstring · dateobligatorio
  Ejemplo: 2026-11-30
- payroll_periodstringobligatorio
  1 semanal, 2 decenal, 3 catorcenal, 4 quincenal, 5 mensual, 6 otro
  Valores: 1 · 2 · 3 · 4 · 5 · 6
- payment_datesarray<string · date>obligatorio
paymentobjectobligatorio
+ Ver 5 campos− Ocultar 5 campos
- formstring· por defecto 1
- methodstringobligatorio
  Medio de pago DIAN (10 efectivo, 42 consignación, 47 transferencia...)
  Ejemplo: 42
- bankstring
- account_typestring
- account_numberstring
earningsobjectobligatorio
+ Ver 27 campos− Ocultar 27 campos
- worked_daysinteger· máximo 31obligatorio
- salarystringobligatorio
  Ejemplo: 5000.00
- transportarray<object>
  + Ver 3 campos− Ocultar 3 campos
  - allowancestring
    Ejemplo: 5000.00
  - viatic_salarystring
    Ejemplo: 5000.00
  - viatic_non_salarystring
    Ejemplo: 5000.00
- overtimearray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestringobligatorio
    Valores: HED · HEN · HRN · HEDDF · HRDDF · HENDF · HRNDF
  - startstring · date-time
  - endstring · date-time
  - hoursstringobligatorio
    Ejemplo: 2
  - paymentstringobligatorio
    Ejemplo: 5000.00
- vacationsarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- compensated_vacationsarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- service_bonusobject
  + Ver 3 campos− Ocultar 3 campos
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
  - non_salarystring
    Ejemplo: 5000.00
- severanceobject
  + Ver 3 campos− Ocultar 3 campos
  - paymentstring
    Ejemplo: 5000.00
  - interest_ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - intereststring
    Ejemplo: 5000.00
- disabilitiesarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- maternity_leavesarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- paid_leavesarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- unpaid_leavesarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- strikesarray<object>
  + Ver 5 campos− Ocultar 5 campos
  - typestring
    Solo incapacidades: 1 común, 2 profesional, 3 laboral
    Valores: 1 · 2 · 3
  - startstring · date
    Ejemplo: 2026-11-30
  - endstring · date
    Ejemplo: 2026-11-30
  - daysinteger
  - paymentstring
    Ejemplo: 5000.00
- bonusesarray<object>
  + Ver 3 campos− Ocultar 3 campos
  - descriptionstring
    Solo other_concepts (obligatoria)
  - salarystring
    Ejemplo: 5000.00
  - non_salarystring
    Ejemplo: 5000.00
- aidsarray<object>
  + Ver 3 campos− Ocultar 3 campos
  - descriptionstring
    Solo other_concepts (obligatoria)
  - salarystring
    Ejemplo: 5000.00
  - non_salarystring
    Ejemplo: 5000.00
- other_conceptsarray<object>
  + Ver 3 campos− Ocultar 3 campos
  - descriptionstring
    Solo other_concepts (obligatoria)
  - salarystring
    Ejemplo: 5000.00
  - non_salarystring
    Ejemplo: 5000.00
- compensationsarray<object>
  + Ver 2 campos− Ocultar 2 campos
  - ordinarystring
    Ejemplo: 5000.00
  - extraordinarystring
    Ejemplo: 5000.00
- vouchersarray<object>
  + Ver 4 campos− Ocultar 4 campos
  - salarystring
    Ejemplo: 5000.00
  - non_salarystring
    Ejemplo: 5000.00
  - food_salarystring
    Ejemplo: 5000.00
  - food_non_salarystring
    Ejemplo: 5000.00
- commissionsarray<string>
- third_party_paymentsarray<string>
- advancesarray<string>
- endowmentstring
  Ejemplo: 5000.00
- support_paymentstring
  Ejemplo: 5000.00
- teleworkstring
  Ejemplo: 5000.00
- retirement_bonusstring
  Ejemplo: 5000.00
- indemnitystring
  Ejemplo: 5000.00
- refundstring
  Ejemplo: 5000.00
deductionsobjectobligatorio
+ Ver 18 campos− Ocultar 18 campos
- healthobjectobligatorio
  + Ver 2 campos− Ocultar 2 campos
  - ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - amountstring
    Ejemplo: 5000.00
- pensionobjectobligatorio
  + Ver 2 campos− Ocultar 2 campos
  - ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - amountstring
    Ejemplo: 5000.00
- pension_solidarityobject
  + Ver 4 campos− Ocultar 4 campos
  - ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - amountstring
    Ejemplo: 5000.00
  - subsistence_ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - subsistence_amountstring
    Ejemplo: 5000.00
- unionsarray<object>
  + Ver 2 campos− Ocultar 2 campos
  - ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - amountstring
    Ejemplo: 5000.00
- sanctionsarray<object>
  + Ver 2 campos− Ocultar 2 campos
  - publicstring
    Ejemplo: 5000.00
  - privatestring
    Ejemplo: 5000.00
- loansarray<object>
  + Ver 2 campos− Ocultar 2 campos
  - descriptionstringobligatorio
  - amountstringobligatorio
    Ejemplo: 5000.00
- third_party_paymentsarray<string>
- advancesarray<string>
- othersarray<string>
- voluntary_pensionstring
  Ejemplo: 5000.00
- withholding_taxstring
  Ejemplo: 5000.00
- afcstring
  Ejemplo: 5000.00
- cooperativestring
  Ejemplo: 5000.00
- tax_lienstring
  Ejemplo: 5000.00
- complementary_plansstring
  Ejemplo: 5000.00
- educationstring
  Ejemplo: 5000.00
- refundstring
  Ejemplo: 5000.00
- debtstring
  Ejemplo: 5000.00

Respuestas

202Documento en fila (pending). El número, el CUFE y la firma se asignan al enviarlo a la DIAN.

idstring · uuid
account_idstring · uuid
Cuenta emisora; una casa de software la usa para saber de qué cliente es el aviso
document_typestring
Valores: invoice · credit_note · debit_note · support_document · support_document_adjustment · payroll · payroll_adjustment · pos · pos_adjustment · pos_debit_adjustment
external_idstring
reference_document_idstring · uuid
prefixstring
numberinteger
null hasta que se envía a la DIAN; un rechazo lo libera
full_numberstring
Ejemplo: SETP990000001
document_keystring
CUFE, CUDE, CUDS o CUNE según el tipo
Ejemplo: a3f1c9...e2
environmentinteger
1 producción, 2 habilitación
Valores: 1 · 2
stagingboolean
Documento de prueba (cuenta en staging): no fue a la DIAN y no tiene validez fiscal
issued_atstring · date-time
customer_idstring
Contraparte: adquirente, vendedor (documento soporte) o trabajador (nómina)
customer_namestring
Ejemplo: PÉREZ GÓMEZ ANA
currencystring
Siempre COP: el XML y los montos van en pesos (regla FAD15 del Anexo 1.9)
Ejemplo: COP
payable_amountstring
Ejemplo: 5000.00
foreignobject
Solo si se facturó en otra moneda: moneda, tasa usada y total en esa moneda
+ Ver 3 campos− Ocultar 3 campos
- currencystring
  Ejemplo: USD
- exchange_ratestring
  Ejemplo: 4123.45
- payable_amountstring
  Ejemplo: 5000.00
statusstring
pending esperando al worker, submitted enviado y esperando a la DIAN, accepted, rejected (por la DIAN, final) y failed (se agotaron los reintentos).
Valores: pending · submitted · accepted · rejected · failed
dianobject
+ Ver 5 campos− Ocultar 5 campos
- track_idstring
- status_codestring
  Ejemplo: 00
- status_descriptionstring
- errorsarray<string>
- rulesarray<object>
  errors separados: regla, tipo (rejection rechaza el documento; notification no impide la aceptación), mensaje de la DIAN y, si factuROA la conoce, cómo corregirla
  + Ver 4 campos− Ocultar 4 campos
  - rulestring
    Ejemplo: FAJ44b
  - typestring
    Valores: rejection · notification
  - messagestring
  - hintstring
    Ejemplo: Emisor persona natural: usa document_type 13 (cédula) en vez de 31.
attemptsinteger
errorobject
Solo si factuROA rechazó el documento sin enviarlo a la DIAN (p. ej. error.plan.no_documents: se quedó en fila cuando el plan se agotó o venció con la renovación cancelada)
+ Ver 2 campos− Ocultar 2 campos
- codestring
  Ejemplo: error.plan.no_documents
- messagestring
emailobject
Correo al adquiriente con el AttachedDocument y el PDF (solo facturas y notas aceptadas, con FACTUROA_EMAIL_FROM configurado).
+ Ver 6 campos− Ocultar 6 campos
- statusstring
  abandoned: sin correo válido del adquiriente o intentos agotados (ver last_error)
  Valores: pending · sent · abandoned
- attemptsinteger
- sent_atstring · date-time
- last_errorstring
- recipientstring
  Dirección del último reenvío (si se pidió otra)
- resendsinteger
  Reenvíos pedidos (máximo 5)
created_atstring · date-time
updated_atstring · date-time

200Ya existía un documento con ese external_id; se devuelve sin crear otro.

idstring · uuid
account_idstring · uuid
Cuenta emisora; una casa de software la usa para saber de qué cliente es el aviso
document_typestring
Valores: invoice · credit_note · debit_note · support_document · support_document_adjustment · payroll · payroll_adjustment · pos · pos_adjustment · pos_debit_adjustment
external_idstring
reference_document_idstring · uuid
prefixstring
numberinteger
null hasta que se envía a la DIAN; un rechazo lo libera
full_numberstring
Ejemplo: SETP990000001
document_keystring
CUFE, CUDE, CUDS o CUNE según el tipo
Ejemplo: a3f1c9...e2
environmentinteger
1 producción, 2 habilitación
Valores: 1 · 2
stagingboolean
Documento de prueba (cuenta en staging): no fue a la DIAN y no tiene validez fiscal
issued_atstring · date-time
customer_idstring
Contraparte: adquirente, vendedor (documento soporte) o trabajador (nómina)
customer_namestring
Ejemplo: PÉREZ GÓMEZ ANA
currencystring
Siempre COP: el XML y los montos van en pesos (regla FAD15 del Anexo 1.9)
Ejemplo: COP
payable_amountstring
Ejemplo: 5000.00
foreignobject
Solo si se facturó en otra moneda: moneda, tasa usada y total en esa moneda
+ Ver 3 campos− Ocultar 3 campos
- currencystring
  Ejemplo: USD
- exchange_ratestring
  Ejemplo: 4123.45
- payable_amountstring
  Ejemplo: 5000.00
statusstring
pending esperando al worker, submitted enviado y esperando a la DIAN, accepted, rejected (por la DIAN, final) y failed (se agotaron los reintentos).
Valores: pending · submitted · accepted · rejected · failed
dianobject
+ Ver 5 campos− Ocultar 5 campos
- track_idstring
- status_codestring
  Ejemplo: 00
- status_descriptionstring
- errorsarray<string>
- rulesarray<object>
  errors separados: regla, tipo (rejection rechaza el documento; notification no impide la aceptación), mensaje de la DIAN y, si factuROA la conoce, cómo corregirla
  + Ver 4 campos− Ocultar 4 campos
  - rulestring
    Ejemplo: FAJ44b
  - typestring
    Valores: rejection · notification
  - messagestring
  - hintstring
    Ejemplo: Emisor persona natural: usa document_type 13 (cédula) en vez de 31.
attemptsinteger
errorobject
Solo si factuROA rechazó el documento sin enviarlo a la DIAN (p. ej. error.plan.no_documents: se quedó en fila cuando el plan se agotó o venció con la renovación cancelada)
+ Ver 2 campos− Ocultar 2 campos
- codestring
  Ejemplo: error.plan.no_documents
- messagestring
emailobject
Correo al adquiriente con el AttachedDocument y el PDF (solo facturas y notas aceptadas, con FACTUROA_EMAIL_FROM configurado).
+ Ver 6 campos− Ocultar 6 campos
- statusstring
  abandoned: sin correo válido del adquiriente o intentos agotados (ver last_error)
  Valores: pending · sent · abandoned
- attemptsinteger
- sent_atstring · date-time
- last_errorstring
- recipientstring
  Dirección del último reenvío (si se pidió otra)
- resendsinteger
  Reenvíos pedidos (máximo 5)
created_atstring · date-time
updated_atstring · date-time

402En producción la cuenta (o su casa de software) no tiene un plan activo: error.plan.inactive. No se crea el documento

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

400Datos inválidos (details trae los campos)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

401Falta la key o es inválida, está deshabilitada, vencida o revocada (error.missing_api_key, error.invalid_api_key, error.api_key.disabled, error.api_key.expired, error.api_key.revoked)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

409Conflicto con el estado actual (p. ej. documento referenciado no aceptado, rango agotado)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

422Faltan datos para generar el XML (error.document.incomplete, campos en details)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring