Documentación / API / Nómina

Vista previa de un recibo de nómina (sin timbrar)

POSThttps://api.cfdi.express/v1/nominas/previewAPI key

Desde la v1.54.0, valida un recibo de nómina y lo arma exactamente como se timbraría, con todos los totales calculados, sin timbrarlo: no cobra, no aparta folio y no guarda nada.

Recibe el mismo cuerpo que POST /v1/nominas (el recibo de un empleado por periodo; la guía está en facturas de nómina con la API) y corre las mismas validaciones, con el mismo código: claves de los catálogos de Nómina del SAT y las reglas de consistencia NOMxx.

Responde los totales que se calculan del lado del servidor (totalPercepciones, totalDeducciones, totalOtrosPagos, subtotal, discount y total, el neto a pagar), los datos del CFDI 4.0 con complemento Nómina 1.2 sin sellar y html: la representación impresa con la misma plantilla que el PDF, la marca de agua PREVIEW y la leyenda «VISTA PREVIA — SIN VALIDEZ FISCAL», sin UUID, sellos ni QR.

Es opcional: POST /v1/nominas no la exige. No pide Idempotency-Key, no consume timbre ni saldo, no incrementa el folio del emisor y no crea ningún recurso. Para timbrar lo que se aprobó, manda el mismo cuerpo a POST /v1/nominas con tu Idempotency-Key.

La serie es NOM. folio es el del cuerpo o, si no lo mandas, el siguiente folio del emisor (folioIsProjected: true): puede cambiar si se timbran otros documentos antes. fecha es la hora de la vista previa.

Autenticación
Authorization: Bearer sk_test_... | sk_live_...

El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.

Ejemplos

cURL
curl -X POST https://api.cfdi.express/v1/nominas/preview \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
    "tipoNomina": "O",
    "fechaPago": "2026-11-15",
    "fechaInicialPago": "2026-11-01",
    "fechaFinalPago": "2026-11-15",
    "numDiasPagados": 15,
    "registroPatronal": "B5510768108",
    "employee": {
      "rfc": "CACX7605101P8",
      "name": "XOCHILT CASAS CHAVEZ",
      "zip": "36257",
      "curp": "CACX760510MGTSSL09",
      "numSeguridadSocial": "12345678901",
      "tipoContrato": "01",
      "tipoRegimen": "02",
      "numEmpleado": "0042",
      "periodicidadPago": "04",
      "claveEntFed": "GUA"
    },
    "percepciones": [
      { "tipoPercepcion": "001", "clave": "SUE", "concepto": "Sueldo quincenal", "importeGravado": 12000, "importeExento": 0 }
    ],
    "deducciones": [
      { "tipoDeduccion": "002", "clave": "ISR", "concepto": "ISR retenido", "importe": 1450 }
    ]
  }'

Respuesta

200 OK
{
  "object": "nomina_preview",
  "livemode": false,
  "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
  "emisor": { "rfc": "EKU9003173C9", "name": "ESCUELA KEMPER URGATE" },
  "serie": "NOM",
  "folio": "56",
  "folioIsProjected": true,
  "fecha": "2026-11-18T09:00:00",
  "tipoNomina": "O",
  "fechaPago": "2026-11-15",
  "fechaInicialPago": "2026-11-01",
  "fechaFinalPago": "2026-11-15",
  "employee": { "rfc": "CACX7605101P8", "name": "XOCHILT CASAS CHAVEZ", "numEmpleado": "0042" },
  "totalPercepciones": 12000,
  "totalDeducciones": 1450,
  "totalOtrosPagos": 0,
  "subtotal": 12000,
  "discount": 1450,
  "total": 10550,
  "cfdi": { "Version": "4.0", "TipoDeComprobante": "N", "...": "recortado" },
  "html": "<!DOCTYPE html>…"
}

Errores

StatuscodeCuándo aparece
400validation_errorEl mismo cuerpo lo rechazaría POST /v1/nominas: mismo detail, subcode y errors que el timbrado. Incluye claves que no están en los catálogos de Nómina del SAT (errors[] con path y el catálogo a consultar), reglas NOMxx que no se cumplen (errors[]) y un emisor archivado (merchant_archived) o sin CSD (csd_missing).
401unauthorizedFalta el header Authorization o la llave es inválida.
403forbiddenNo eres miembro de la cuenta del header x-account-id.
404not_foundEl merchantId no existe en tu cuenta.
429rate_limitedExcediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After.

Notas

  • Nunca responde 402: la vista previa no usa saldo. Un rechazo del SAT (sat_rejected) solo puede aparecer al timbrar.
  • Por MCP es la herramienta preview_nomina, con la misma tarjeta que la factura: «Autorizar y timbrar» (llama create_nomina), «Pedir cambios» y «Descargar PDF». Para varias nóminas del mismo periodo, las instrucciones le piden al agente una vista previa por recibo, o preguntarte si basta un resumen. Ver el servidor MCP.

Continuar