API DE NÓMINA ELECTRÓNICA
Timbra la nómina completa en una corrida
Conecta tu sistema de recursos humanos y timbra los recibos de toda la plantilla cada quincena, sin exportar layouts ni subir archivos a ningún portal.
¿Qué es el CFDI de nómina?
Es el recibo de pago de tus trabajadores en formato fiscal. Cada vez que pagas nómina — semanal, quincenal o mensual— debes timbrar un CFDI por empleado con el desglose de lo que le pagaste y lo que le retuviste.
No es opcional ni sustituible por un recibo interno: es lo que le permite al trabajador comprobar ingresos y lo que te permite a ti deducir la nómina como gasto. Si el timbrado falla, esa deducción se cae.
El endpoint
Es el mismo de CFDI, con el complemento de nómina incorporado. Autenticación HTTP Basic.
La estructura del complemento se organiza en cuatro bloques que reflejan cómo se arma un recibo real:
- Percepciones — sueldo, horas extra, aguinaldo, prima vacacional, bonos.
- Deducciones — ISR retenido, cuotas del IMSS, crédito Infonavit, préstamos.
- Otros pagos — donde va el subsidio al empleo, que no es una percepción normal.
- Incapacidades — cuando el periodo incluye días cubiertos por el IMSS.
El subsidio al empleo: el campo que más se equivoca
El subsidio no va en percepciones. Va en otros pagos, con su propia clave. Es un error tan frecuente que vale la pena decirlo antes que nada: si lo metes como percepción, el recibo cuadra visualmente pero el XML queda mal armado.
La lógica de fondo: el subsidio no es dinero que tú pagas por el trabajo, es un beneficio fiscal que entregas por cuenta del gobierno. Por eso tiene tratamiento aparte, y por eso el SAT lo quiere identificado.
Los casos que rompen las integraciones
La nómina ordinaria de un empleado de planta es la parte fácil. Lo que suele faltar cuando alguien monta la integración a las prisas:
- Finiquitos y liquidaciones. Llevan claves de percepción distintas — indemnización, prima de antigüedad— con su propio tratamiento fiscal. No es una nómina normal con un importe más.
- Incapacidades. Cuando el IMSS cubre parte del periodo, esos días van en su propio bloque y no como sueldo.
- Jubilados y pensionados. Tienen su propio esquema, distinto del de un trabajador activo.
- Asimilados a salarios. No son empleados, y su recibo se arma diferente.
El consejo práctico: modela desde el principio el finiquito y la incapacidad, aunque no los necesites el primer mes. Siempre llegan, normalmente el día que menos te conviene reabrir la integración.
Timbrar en lote
La nómina es el caso de uso más claro para una API: 200 empleados son 200 comprobantes, el mismo día, con la misma estructura y datos distintos. Hacerlo a mano no escala y hacerlo con layouts es lento y frágil.
Dos recomendaciones de implementación que ahorran disgustos: guarda el
Id y el UUID de cada recibo junto al registro del empleado —los vas a
necesitar para reenvíos y cancelaciones— y maneja el error por empleado, no por
lote. Que un RFC mal capturado tumbe la corrida entera es una tarde perdida; que
falle solo ese recibo es un minuto.
Y prueba la corrida completa en sandbox antes del primer timbrado real. Cancelar 200 recibos mal emitidos es un trabajo que nadie quiere hacer dos veces.
Ciclo de vida y SDKs
Consulta por Id, descarga de XML y PDF, envío por correo al trabajador y
cancelación. El envío automático es especialmente útil aquí: en vez de montar tu propio
mailing de recibos, lo disparas desde la misma API tras timbrar.
Librerías oficiales en PHP, Python, JavaScript, Java, Ruby y .NET (4.5+).
¿Y si no quieres integrar?
Si tienes pocos empleados o tu nómina la lleva un despacho, el sistema de nómina en la plataforma web te resuelve el timbrado sin desarrollo.
La API tiene sentido cuando ya existe un sistema de RH que calcula la nómina y solo falta que el timbrado ocurra solo al cerrar el periodo.
Preguntas frecuentes
¿Dónde se declara el subsidio al empleo?
En el bloque de otros pagos, no en percepciones. Es el error más común al armar el complemento.
¿Puedo timbrar finiquitos con la API?
Sí. Usan claves de percepción específicas para indemnización y prima de antigüedad, con su propio tratamiento fiscal.
¿Qué pasa si un recibo sale mal?
Se cancela y se emite de nuevo. Por eso conviene guardar el Id de cada recibo y
controlar los errores empleado por empleado en las corridas en lote.
¿Se puede enviar el recibo al trabajador desde la API?
Sí, hay operación de envío por correo. Evita montar un sistema de distribución aparte.
Prueba una corrida completa
El sandbox no consume folios: puedes timbrar tu plantilla de prueba las veces que necesites.
Crear cuenta y probar Hablar con un ingeniero