# Vista previa de un recibo de nómina (sin timbrar) > `POST https://api.cfdi.express/v1/nominas/preview` — 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. URL de esta página: https://cfdi.express/docs/api/vista-previa-nomina Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`) Header `x-account-id`: indica la cuenta. Si no eres miembro, la respuesta es 403. 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](https://cfdi.express/blog/facturas-de-nomina-cfdi-express-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. ## Ejemplos ### cURL ```bash 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 ```json { "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": "…" } ``` ## 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» (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](https://cfdi.express/docs/api/mcp). ## Relacionados - [POST /v1/nominas/preview/pdf](https://cfdi.express/docs/api/vista-previa-nomina-pdf) — Vista previa de nómina en PDF - [GET /v1/nominas](https://cfdi.express/docs/api/listar-nominas) — Listar nómina --- Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express