Timbrado del CFDI de Nómina 1.2

Una vez calculado el periodo, los recibos deben timbrarse para convertirse en Comprobantes Fiscales Digitales por Internet (CFDI) válidos ante el SAT. ALTUM ERP integra Finkok como único PAC autorizado para el timbrado de nómina.

Requisitos previos

Antes de timbrar, verifique en /nomina/configuracion que estén configurados:

• RFC del emisor (tenant) — válido según la regex SAT (12 chars moral / 13 chars física).
• Certificados CSD — archivo .cer (certificado público) y archivo .key (llave privada) cargados en la configuración del tenant.
• Contraseña del SAT — clave de la llave privada.
• Régimen fiscal y código postal del tenant (necesarios para el nodo cfdi:Emisor y LugarExpedicion).

Si alguno falta, el timbrado falla con un error de configuración antes de contactar a Finkok.

Permiso requerido

El timbrado requiere el permiso nomina.timbrar. Solo el personal autorizado puede ejecutar esta acción.

Ejecutar el timbrado

Desde /nomina/periodos/:id, con el periodo en estado CALCULADO, haga clic en el botón “Timbrar”.

El sistema procesa los recibos en lotes de 10 en paralelo:

1. Valida que el periodo esté en CALCULADO.
2. Carga los certificados CSD del tenant y descifra la llave privada.
3. Determina el código postal de expedición (LugarExpedicion): primero busca tenant.lugarExpedicion; si no existe, usa el CP de la primera sucursal activa; si tampoco hay sucursal, usa 06600 (CDMX) como fallback.
4. Para cada recibo en estado PENDIENTE_TIMBRADO o TIMBRADO_FALLIDO: a. Construye el XML del CFDI Nómina 1.2. b. Firma el XML con el CSD del tenant. c. Envía el XML firmado a Finkok. d. Persiste el UUID, sellos y rutas de los archivos (XML y PDF).
5. Al terminar el lote, actualiza el estado del periodo a TIMBRADO si no quedan recibos pendientes ni fallidos.
6. Emite el evento nomina.periodo.timbrado para la generación automática de la póliza contable (si está habilitada).

Estructura del CFDI de Nómina

El XML que se genera y firma tiene la siguiente estructura general (CFDI 4.0 + complemento Nómina 1.2):

Elemento / Atributo	Valor
Version	4.0
TipoDeComprobante	N (Nómina)
Moneda	MXN
SubTotal	Total de percepciones del recibo
Descuento	Total de deducciones (cuando > $0.00)
Total	percepciones − deducciones + otrosPagos
MetodoPago	PUE
Exportacion	01
Serie	NOM
Folio	Número secuencial de 6 dígitos dentro del periodo
LugarExpedicion	Código postal del tenant (ver arriba)
cfdi:Concepto ClaveProdServ	84111505
cfdi:Concepto ClaveUnidad	ACT
cfdi:Concepto Descripcion	Pago de nómina
cfdi:Receptor RegimenFiscalReceptor	605 (fijo para asalariados)
cfdi:Receptor UsoCFDI	CN01 (Nómina)

MetodoPago y FormaPago en tipo N

El CFDI de nómina (tipo N) incluye MetodoPago="PUE" en el nodo cfdi:Comprobante, conforme a la especificación SAT CFDI 4.0 para nómina. No se incluye el atributo FormaPago.

Complemento Nómina 1.2

El complemento contiene, entre otros datos:

Dato	Origen
TipoNomina	O (Ordinaria) — fijo en la implementación actual
FechaPago	periodo.fechaPago
FechaInicialPago	periodo.fechaInicio
FechaFinalPago	periodo.fechaFin
NumDiasPagados	recibo.diasTrabajados (3 decimales)
CURP	empleado.curp
NumSeguridadSocial	empleado.nss
FechaInicioRelLaboral	empleado.fechaInicio
Antiguedad	Semanas completas en formato ISO PnW (calculado a partir de empleado.fechaInicio)
TipoContrato	empleado.tipoContrato (catálogo SAT)
TipoJornada	empleado.tipoJornada (catálogo SAT)
TipoRegimen	empleado.tipoRegimen (catálogo SAT)
SalarioBaseCotApor	empleado.sbc
SalarioDiarioIntegrado	empleado.sbc
PeriodicidadPago	Mapeado de TipoPeriodoNomina a clave SAT: SEMANAL=01, CATORCENAL=02, QUINCENAL=04, MENSUAL=05
RegistroPatronal	tenant.nominaConfig.registroPatronal (cuando existe)

Percepciones, deducciones y otros pagos en el CFDI

Tipo	Clave SAT	Concepto	Notas
Percepción	001	Sueldos, Salarios Rayas y Jornales	Importe gravado = sueldo bruto del periodo
Deducción	001	ISR	Solo si isrNeto > $0.00
Deducción	002	Cuotas IMSS	Cuotas obrero: CESANTIA_VEJEZ + EYM_FIJA + IV
Deducción	006	Descuento Infonavit	Solo si el empleado tiene crédito activo
Otro pago	002	Subsidio para el empleo	Siempre presente; importe diferencial subsidioPeriodo − isrPeriodo (puede ser $0.00)

Distribución correcta de deducciones

Las cuotas IMSS obrero (clave 002) van en el nodo Deducciones con TotalOtrasDeducciones. El ISR (clave 001) es el único concepto que se suma en TotalImpuestosRetenidos. Si estas claves se invierten, el CFDI es inválido ante el PAC.

Estados del timbrado por recibo

Estado	Significado
PENDIENTE_TIMBRADO	Aún no enviado a Finkok
TIMBRADO	Timbrado exitosamente; UUID disponible
TIMBRADO_FALLIDO	Error en el intento; se puede reintentar
CANCELADO	CFDI cancelado ante el SAT

Reintento de timbrado

Si uno o más recibos quedan en TIMBRADO_FALLIDO, puede reintentarse hasta un máximo de 3 intentos. El campo intentosTimbrado del recibo registra cuántos se han realizado y ultimoError guarda el mensaje del último fallo. Al volver a ejecutar el timbrado del periodo, el sistema incluye automáticamente los recibos en TIMBRADO_FALLIDO junto con los PENDIENTE_TIMBRADO.

Diagnóstico de errores

Los motivos comunes de fallo son: certificado CSD vencido, RFC del empleado con formato incorrecto, RFC del emisor no registrado como emisor activo en el SAT, o datos del receptor (CURP, NSS) inconsistentes. Revise ultimoError en la tabla de recibos para obtener el mensaje de Finkok.

Cancelación de un recibo timbrado

Para cancelar un CFDI de nómina ya timbrado:

1. El recibo debe estar en estado TIMBRADO.
2. Se requiere el permiso nomina.timbrar.
3. Se selecciona el motivo de cancelación SAT:
   • 01 — Comprobante emitido con errores con relación (requiere indicar el UUID sustituto).
   • 02 — Comprobante emitido con errores sin relación.
   • 03 — No se llevó a cabo la operación.
   • 04 — Operación nominativa relacionada en la factura global.
4. El sistema envía la solicitud de cancelación a Finkok vía FinkokCancellationService.
5. El recibo pasa a estado CANCELADO con fecha y motivo registrados.
6. Si todos los recibos del periodo quedan en CANCELADO, el periodo también pasa a CANCELADO automáticamente.

Motivo 01 requiere UUID sustituto

Si selecciona motivo 01, debe proporcionar el UUID del CFDI que reemplaza al cancelado. Sin ese dato, la cancelación es rechazada.

Descarga de XML y PDF

Los paths de los archivos generados durante el timbrado se almacenan en xmlPath y pdfPath del recibo. El formato de ruta es:

{tenantId}/{año}/{periodoId}/{reciboId}.xml
{tenantId}/{año}/{periodoId}/{reciboId}.pdf

La descarga de archivos individuales no está expuesta directamente desde la tabla de recibos en la interfaz actual. La consulta se realiza a través de la API del recibo.

Casos frecuentes

El timbrado falla con “Configuracion fiscal incompleta”. Verifique en la configuración del tenant que estén capturados: RFC, Razón Social, Régimen Fiscal y los certificados CSD con su contraseña.

Un recibo queda en TIMBRADO_FALLIDO y ya se agotaron los 3 intentos. Se requiere intervención manual. Contacte al soporte para resetear el contador de intentos o para generar un reintento excepcional vía la API.

¿Puedo timbrar un recibo individual? No desde la interfaz. El timbrado se ejecuta siempre a nivel de periodo y procesa todos los recibos pendientes del mismo en lotes.

¿El PDF del recibo se genera automáticamente? El path del PDF se almacena al timbrar, pero la generación del PDF como representación impresa del CFDI depende del servicio de Finkok. Consulte la documentación de su cuenta PAC para confirmar si está habilitada.