Nómina

Un recibo de nómina es un CFDI de tipo N con el complemento Nómina 1.2. Usted manda el empleado y el periodo; Fiscalisto calcula el sueldo de los días pagados, el ISR con la tarifa del artículo 96 y el subsidio para el empleo vigente, y las cuotas obreras del IMSS, como Nómina › Emitir recibos en la app. Nunca timbra montos que usted escriba a mano, así que un recibo siempre cuadra con lo que pide el SAT.

Cada recibo usa un timbre, como cualquier factura. En pruebas se timbra con los emisores de prueba del SAT, sin costo.

Antes del primer reciboCopiar enlace a esta sección

El emisor necesita su registro patronal del IMSS (11 caracteres) y, si es persona física, su CURP:

curl https://api.fiscalisto.com/v1/issuers/iss_OufpKqnrvx9p \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "employer_registration": "Y5412345109" }'

Sin él, un recibo contesta 422 payroll_invalid y lo dice.

Dar de alta un empleadoCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/employees \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "9",
    "name": "Ana Gómez Ruiz",
    "tax_id": "GORA800101AB1",
    "curp": "GORA800101MDFMZN09",
    "social_security_number": "12345678903",
    "zip": "06000",
    "email": "ana@example.com",
    "start_date": "2024-03-04",
    "daily_salary": 320,
    "integrated_daily_salary": 334.66,
    "periodicity": "04",
    "state": "CMX"
  }'

El nombre, el RFC y el código postal van como en la constancia de situación fiscal del empleado: el SAT los compara. Lo que no mande tiene el valor usual de Nuevo empleado:

La respuesta trae warnings con lo que el SAT podría rechazar antes de timbrar, por ejemplo un RFC o una CURP cuyo dígito verificador no corresponde. No impiden guardarlo: revíselos con el empleado.

Un RFC o un número de empleado que ya existe en el emisor contesta 400 employee_exists. Para cambiar un salario o dar de baja (end_date), use POST /v1/employees/{id} con solo lo que cambia; los recibos ya timbrados no cambian.

Ver el recibo antes de timbrarloCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/payroll_receipts/preview \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee": "emp_OufpKqnrvx9p4gtWHOcPMsq25QUp6Licjr",
    "period": { "start": "2026-10-01", "end": "2026-10-15" }
  }'

Contesta el recibo como se timbraría, sin timbrar ni usar timbres:

{
  "object": "payroll_receipt_preview",
  "periodicity": "04",
  "period": { "start": "2026-10-01", "end": "2026-10-15", "payment_date": "2026-10-15" },
  "days": 15,
  "perceptions": [{ "type": "001", "key": "001", "concept": "Sueldo", "taxed": 4800, "exempt": 0 }],
  "deductions": [
    { "type": "001", "key": "001", "concept": "Cuotas IMSS", "amount": 119.21 },
    { "type": "002", "key": "002", "concept": "ISR", "amount": 80.85 }
  ],
  "isr": { "tariff": 345.15, "subsidy": 264.3, "withheld": 80.85, "exempt_minimum": false },
  "totals": { "perceptions": 4800, "deductions": 200.06, "net": 4599.94 }
}

isr.tariff es el ISR de la tarifa, isr.subsidy el subsidio para el empleo que le toca y isr.withheld lo que se le retiene. El periodo va en hora de la Ciudad de México; payment_date (la fecha de pago) es su último día si no la manda, y days son todos los días pagables del periodo (sin los anteriores a su ingreso ni los posteriores a su baja). Mande days para pagar menos, por ejemplo con faltas.

TimbrarloCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/payroll_receipts \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nomina-2026-10-q1-9" \
  -d '{
    "employee": "emp_OufpKqnrvx9p4gtWHOcPMsq25QUp6Licjr",
    "period": { "start": "2026-10-01", "end": "2026-10-15" },
    "send_email": true,
    "metadata": { "corrida": "2026-19" }
  }'

La respuesta es una factura de type: "N" con su uuid, su PDF y su XML, y con el recibo en payroll. Llega también el webhook invoice.stamped. Con send_email el empleado recibe el PDF y el XML en su email; si no tiene, contesta 400 parameter_missing antes de timbrar.

Un empleado tiene un solo recibo por periodo: pedirlo otra vez (aun con otra Idempotency-Key) contesta el que ya tiene, sin timbrar otro. Un periodo que se cruza con otro recibo vigente del mismo empleado, o más largo que su periodicidad (un mes en una nómina semanal), contesta payroll_invalid, para no pagar dos veces los mismos días.

Corregir un reciboCopiar enlace a esta sección

Un recibo timbrado no se edita. Cancélelo con POST /v1/invoices/{id}/cancel (no pide aceptación del empleado) y vuelva a timbrar el periodo: un periodo con su recibo cancelado se puede timbrar de nuevo.

ListarlosCopiar enlace a esta sección

Los recibos son facturas de tipo N: GET /v1/invoices?type=N los da, los más recientes primero, y GET /v1/employees a los empleados.

Lo que no haceCopiar enlace a esta sección

• Nómina extraordinaria (aguinaldo, finiquito, PTU): solo nómina ordinaria.
• Percepciones o deducciones que usted escriba (bonos, préstamos, Infonavit): el recibo lleva el sueldo, el ISR, el subsidio y las cuotas del IMSS.