# FD-SYNC-001 — Sincronización Automática de CFDIs desde el SAT --- # 1. INTRODUCCIÓN Este documento describe en detalle la arquitectura, lógica, procesos y operación del sistema FD-SYNC-001, encargado de sincronizar CFDIs desde el SAT hacia FactuDesk. El objetivo principal es garantizar: - Integridad de la información fiscal - Automatización total del proceso - Escalabilidad para miles de contribuyentes - Tolerancia a fallos del SAT --- # 2. PROBLEMA A RESOLVER El SAT: - No entrega datos en tiempo real - Usa un proceso asíncrono - Tiene límites operativos (CFDIs, descargas, duplicados) Esto implica: - Necesidad de polling (esto lo realiza una herramienta 6 veces en al día empezando de las 3 am) - Manejo de estados intermedios - Reintentos controlados - Prevención de duplicados --- ### 2.2 Desfase de registro en el SAT Por ley los CFDIs pueden tardar hasta 72 horas en registrarse en el SAT tras el timbrado; en la práctica este tiempo puede excederse. Esto significa que una solicitud de descarga para "hoy" puede devolver menos CFDIs que los realmente emitidos/recibidos ese día. El sistema resuelve esto con una **zona volátil** de 10 días (`hoy - 10`) que el proceso diario cubre repetidamente, garantizando que ningún CFDI se pierda por desfase. ### 2.3 Diferencia entre persona física y moral El RFC identifica el tipo de contribuyente por su longitud: - **12 caracteres** → Persona moral - **13 caracteres** → Persona física Esto determina qué tipos de documentos se sincronizan: | Tipo | Descripción | Persona física | Persona moral | |------|-------------|:--------------:|:-------------:| | `R` | CFDIs recibidos | ✅ | ✅ | | `E` | CFDIs emitidos | ✅ | ✅ | | `CR` | Constancias de retención recibidas | ✅ | ❌ | | `CE` | Constancias de retención emitidas | ❌ | ✅ | La razón fiscal es que las personas morales son retenedoras (emiten constancias) y las físicas son retenidas (las reciben). --- # 3. ARQUITECTURA DEL SISTEMA ## 3.1 Componentes - BD central: epifania - BD individual del cliente - Workers de sincronización - API REST - UI de monitoreo ## 3.2 Decisión clave Cada RFC tiene su propia base de datos de sincronización: - Evita locks - Evita colisiones - Permite paralelismo total --- # 4. MODELO DE DATOS ## Tablas Las tablas se crean en la base de datos del contribuyente z_{rfc} por el proceso de backfill al momento de subir la fiel - rfc_fiel -> se crea la base de datos principal. - sat_sync_main_log - sat_sync_daily - sat_sync_ondemand ## 4.1 sat_sync_main_log Campos clave: - tipo - fecha_ini / fecha_fin - estado - estado_sat - id_solicitud_sat - intentos - xmls_descargados - cfdi_nuevos Estados: pendiente → solicitado → verificando → descargando → completado / error - por verificar (estado por si ocurre un error en el estado `verificando`) - por descargar (estado por si ocurre un error e el estado `descargando`) - en proceso (estado cuando ocurre un error al hacer la solicitud al SAT y no devuelva un id de solicitud) --- ## 4.2 sat_sync_daily - Registro diario - Sin reintentos - Solo control operativo --- ## 4.3 sat_sync_ondemand - Solicitudes manuales - Control de usuario - Estados independientes --- # 5. PROCESOS DEL SISTEMA ## 5.1 Backfill Se ejecuta cada vez que un contribuyente carga su certificado de eFirma en el sistema (sat_sync_backfill.dkl). - Genera histórico de 1 año - Segmentación quincenal - Inserta múltiples registros - Lanza worker quincenal ## 5.2 Proceso quincenal Se ejecuta cada dia 10 y 26 a la 1 am (sat_sync_quincenal.dkl) - Corre días 10 y 26 - Convierte datos en históricos - Maneja reintentos ## 5.3 Proceso diario Se ejecuta todos los días a las 1 de la mañana (sat_sync_daily.dkl) - Corre todos los días - Ventana: hoy-10 → hoy - No reintenta ## 5.4 Proceso de verificación de estado El proceso `sat_sync_check.dkl` se ejecuta **seis veces al día**, a intervalos de **tres horas**, iniciando a las **03:00 a.m.** Su objetivo es dar seguimiento a las solicitudes activas y completar su ciclo de descarga y procesamiento. ### Flujo de ejecución 1. **Obtención de solicitudes activas** Consulta todas las solicitudes cuyo estado se encuentre en proceso (por ejemplo: `solicitado`,`verificando`,`en_proceso`,`descargando_xml`,`aceptada`,`descargando_meta`,`aceptada`). 2. **Verificación con el SAT** Por cada solicitud, se invoca el servicio `VerificaSolicitudDescarga` del SAT para conocer su estado actual. 3. **Procesamiento de resultados** En función de la respuesta del SAT: - Si la solicitud está **terminada**, se procede a la descarga de paquetes (XML o metadatos según corresponda). - Si continúa en proceso, se programa la siguiente verificación según la estrategia de backoff. - Si ocurre un error, se registra el detalle para su seguimiento. 4. **Gestión de información** - Se insertan o actualizan los metadatos en la **base de datos central (`epifania`)**. - Se sincronizan los metadatos con la **base de datos individual del contribuyente**. - Se almacenan los archivos XML en la ruta configurada del sistema. 5. **Actualización de estado** Se actualiza el estado de la solicitud en la base de datos, de acuerdo con su progreso: ### Consideraciones - El proceso es **idempotente**, por lo que puede ejecutarse múltiples veces sin generar inconsistencias. - Permite continuar solicitudes previamente iniciadas sin necesidad de reiniciarlas. - Garantiza que las solicitudes no queden en estados intermedios sin seguimiento. --- # 6. LÓGICA DE DESCARGA ## 6.1 Recibidos - Descarga directa de XMLs ## 6.2 Emitidos - Primero metadatos - Luego XMLs si faltan --- # 7. CONSISTENCIA DE DATOS Se validan 3 capas: - XML físico - Metadatos central - Metadatos individual Acciones: - Insertar - Copiar - Descargar - Ignorar --- # 8. API REST Endpoints: | Método | Ruta | Descripción | |--------|------|-------------| | GET | `/sync/estado/{rfc}` | Resumen general: FIEL, backfill, último diario, errores, disponibilidad on-demand | | GET | `/sync/segmentos/{rfc}` | Backlog completo de `sat_sync_main_log` (todos los estados) | | GET | `/sync/estado/{rfc}/{id}/` | Estado de una solicitud - avanza el proceso si está activa | | GET | `/sync/diario/{rfc}` | Historial de `sat_sync_daily` — últimos 30 días | | GET | `/sync/ondemand/{rfc}` | Lista de solicitudes manuales | | GET | `/sync/ondemand/{rfc}/{id}/` | Estado de una solicitud — avanza el proceso si está activa | | POST | `/sync/ondemand/{rfc}` | Lanzar sincronización manual | Características: - Autenticación con token - Respuesta uniforme - Polling activo --- # 9. ON-DEMAND Flujo: 1. Validación 2. Solicitud SAT 3. Polling 4. Descarga 5. Resultado --- # 10. PARALELISMO - Lotes de 100 RFCs - async.runscript - async.wait Beneficios: - Alto rendimiento - Control de recursos --- # 11. MANEJO DE ERRORES Errores comunes: - 5005 → duplicado - 5003 → límite CFDIs - 5011 → límite descargas - Estado 6 → expiración Estrategia: - Reintentos - Backoff - Registro en logs --- # 12. CONFIGURACIÓN Parámetros: - lote - reintentos - timeout - margen - rutas XML/FIEL --- # 13. FLUJO COMPLETO 1. Se detecta RFC activo 2. Se generan segmentos 3. Worker procesa: - Solicita - Verifica - Descarga 4. Se validan datos 5. Se almacenan resultados --- # 14. ESCALABILIDAD El sistema soporta: - Miles de RFCs - Procesamiento paralelo - Aislamiento por BD --- # 15. BUENAS PRÁCTICAS - No duplicar solicitudes - Validar antes de descargar - Usar logs como fuente de verdad - Mantener idempotencia --- # 16. CONCLUSIÓN FD-SYNC-001 es un sistema robusto que: - Automatiza completamente la descarga de CFDIs - Se adapta a las limitaciones del SAT - Escala horizontalmente - Garantiza consistencia de datos