Vista previa de un recibo de nómina (sin timbrar)
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.
Authorization: Bearer sk_test_... | sk_live_...El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.
Ejemplos
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
{
"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
| Status | code | Cuándo aparece |
|---|---|---|
| 400 | validation_error | El 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). |
| 401 | unauthorized | Falta el header Authorization o la llave es inválida. |
| 403 | forbidden | No eres miembro de la cuenta del header x-account-id. |
| 404 | not_found | El merchantId no existe en tu cuenta. |
| 429 | rate_limited | Excediste 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» (llamacreate_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.
