Lo que nadie te dice de conectar tu FIEL al SAT

Publicado en vinc.mx · Notas de operar la descarga masiva del SAT en producción

El servicio de Descarga Masiva del SAT existe desde hace años y hay librerías de código abierto que lo implementan bien (nosotros mismos nos apoyamos en el protocolo que documentan). El problema no es el protocolo. Es que "conectar tu FIEL y descargar tus CFDIs automáticamente" suena a un botón que se aprieta una vez, y en la práctica es un proceso que hay que vigilar de forma continua.

Tres formas concretas en que falla en silencio

1. El SAT confirma que el paquete está listo, pero la descarga se cae. El flujo tiene tres pasos — solicitar, verificar, descargar — y cada uno puede fallar por separado. Si el paso de descarga falla después de que el SAT ya dijo "tu paquete está listo", esa solicitud se queda huérfana: nadie la vuelve a intentar a menos que el sistema esté diseñado explícitamente para reintentar descargas atoradas, no solo solicitudes nuevas.

2. La cuota del SAT se agota sin avisar con claridad. El SAT limita cuántas solicitudes puedes hacer en una ventana de tiempo. Cuando se agota, el error no dice "espera fue una hora" — dice un código genérico, y el reintento ciego puede tardar más de lo necesario o, peor, nunca reintentarse si el proceso que lo maneja vive solo en el navegador de alguien.

3. Si el proceso vive en una pestaña del navegador, se muere cuando la pestaña se va a segundo plano. Es tentador construir esto como "el usuario aprieta sincronizar y espera". Pero los navegadores limitan agresivamente los temporizadores de pestañas en segundo plano — si alguien cambia de pestaña a medio proceso, la sincronización se cuelga sin que nadie se entere hasta que revisa y ve que "no ha cargado" desde hace horas.

Ninguno de estos tres es un bug exótico. Son el comportamiento por default si construyes la integración una sola vez y confías en que el camino feliz es el único camino.

Qué tuvimos que construir para que de verdad fuera automático

• Un proceso del lado del servidor que revisa el estado de cada solicitud cada pocos minutos — no depende de que alguien tenga una pestaña abierta.
• Reintentos específicos para paquetes que quedaron "listos" pero sin descargar, no solo para solicitudes nuevas.
• Un límite de reintentos por periodo, para no quedarnos atorados reintentando algo que de verdad falló, ni marcarlo como error cuando en realidad seguía procesándose.

Nada de esto es sofisticado. Es simplemente el trabajo de operar la integración todos los días durante meses, con cientos de miles de CFDIs reales, y corregir cada forma en la que silenciosamente dejaba de sincronizar.