Enviar nómina

Resumen

GridBilling transmite nómina electrónica (e individuales / ajustes) a la DIAN con el mismo modelo Bearer + UBL 2.1.

Configuración previa

Además del certificado y ambiente:

PUT /api/ubl2.1/config/softwarepayroll
Authorization: Bearer <token>

Configura el software DIAN de nómina (ID, PIN, etc., igual que config/software de facturación).

Resoluciones de nómina: PUT /api/ubl2.1/config/resolution con el type_document_id de nómina.

Endpoints

POST /api/ubl2.1/payroll
POST /api/ubl2.1/payroll/{testSetId}
POST /api/ubl2.1/payroll-adjust-note
POST /api/ubl2.1/payroll-adjust-note/{testSetId}
Authorization: Bearer <token_empresa>
Content-Type: application/json

Vista previa PDF (sin enviar a DIAN):

POST /api/ubl2.1/payroll/preeliminar-view

Consecutivo:

GET /api/ubl2.1/payroll/current_number/{type}/{prefix?}

Estructura del body

El JSON de nómina es extenso: periodo, trabajador, pago, accrued (devengados), deductions (deducciones).

Consejo

Empieza con el ejemplo listo: payroll-ubl21.example.json
o la request Sendpayroll de la colección Postman.

Ejemplo mínimo (1 trabajador)

{
  "type_document_id": 9,
  "prefix": "NI",
  "consecutive": 1,
  "payroll_period_id": 5,
  "period": {
    "admision_date": "2024-01-15",
    "settlement_start_date": "2026-06-01",
    "settlement_end_date": "2026-06-30",
    "worked_time": "240.00",
    "issue_date": "2026-06-28"
  },
  "worker": {
    "type_worker_id": 1,
    "sub_type_worker_id": 1,
    "payroll_type_document_identification_id": 3,
    "municipality_id": 149,
    "type_contract_id": 1,
    "identification_number": 1001001001,
    "surname": "PEREZ",
    "second_surname": "GOMEZ",
    "first_name": "ANA",
    "salary": "1500000.00"
  },
  "payment": {
    "payment_method_id": 1,
    "bank_name": "BANCO EJEMPLO",
    "account_type": "AHORROS",
    "account_number": "123456789"
  },
  "payment_dates": [{ "payment_date": "2026-06-30" }],
  "accrued": {
    "worked_days": 30,
    "salary": "1500000.00",
    "transportation_allowance": "140606.00",
    "accrued_total": "1640606.00"
  },
  "deductions": {
    "eps_type_law_deductions_id": 1,
    "eps_deduction": "60000.00",
    "pension_type_law_deductions_id": 1,
    "pension_deduction": "60000.00",
    "deductions_total": "120000.00"
  }
}

Casos reales suelen agregar horas extras, primas, retenciones, etc. dentro de accrued / deductions (ver Postman).

La nota de ajuste (payroll-adjust-note) referencia la nómina previa (similar a NC sobre factura).

Consultar estado

Igual que facturas:

• POST /api/ubl2.1/status/zip/{ZipKey}
• POST /api/ubl2.1/status/document/{CUNE}

Ver Consultar estado y descargar.

Email de nómina al empleado:

POST /api/ubl2.1/send-email-document-payroll

Checklist

1. softwarepayroll + resolución de nómina
2. Certificado vigente
3. Ejemplo Postman adaptado
4. Sandbox con testSetId → luego producción
5. Guarda CUNE / ZipKey

WhatsApp nómina