Nómina Electrónica

Genera y transmite documentos de nómina electrónica ante la DIAN conforme a la resolución vigente.

POST/v1/payroll

Crea un documento de nómina electrónica individual.

CampoTipoReq.Descripción
companyIdstring✅UUID de la empresa empleadora
employeeobject✅Datos del empleado (documento, nombre, cargo)
periodobject✅Período de nómina (fechas inicio y fin)
earningsobject✅Devengados (salario, horas extra, comisiones)
deductionsobject✅Deducciones (salud, pensión, retención)
curl -X POST https://api.mercalo.co/v1/payroll \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "uuid-empresa",
    "employee": {
      "documentType": "CC",
      "document": "12345678",
      "name": "Juan Pérez",
      "position": "Desarrollador Senior"
    },
    "period": {
      "start": "2026-03-01",
      "end": "2026-03-31"
    },
    "earnings": {
      "salary": 5000000,
      "overtime": 300000,
      "transportAllowance": 162000
    },
    "deductions": {
      "health": 200000,
      "pension": 200000,
      "retention": 150000
    }
  }'

Response (200 OK)

{
  "id": "pr_ghi789",
  "cune": "g7h8i9...",
  "status": "ACCEPTED",
  "employeeName": "Juan Pérez",
  "netPay": 4912000,
  "xmlUrl": "https://api.mercalo.co/v1/payroll/pr_ghi789/xml",
  "createdAt": "2026-03-31T18:00:00Z"
}
GET/v1/payroll/:id

Consulta un documento de nómina.

curl https://api.mercalo.co/v1/payroll/pr_ghi789 \
  -H "Authorization: Bearer sk_live_xxx"
GET/v1/payroll

Lista documentos de nómina con filtros por período y empleado.

curl "https://api.mercalo.co/v1/payroll?companyId=xxx&period=2026-03" \
  -H "Authorization: Bearer sk_live_xxx"
POST/v1/payroll/:id/adjust

Emite una nota de ajuste sobre un documento de nómina previamente transmitido.

curl -X POST https://api.mercalo.co/v1/payroll/pr_ghi789/adjust \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Corrección horas extra", "earnings": { "overtime": 450000 } }'

Errores comunes

CódigoDescripciónSolución
400Datos de empleado incompletosVerificar documento, nombre y tipo
422Período inválidoLas fechas deben corresponder a un mes calendario
Notas DébitoDoc. Soporte