HoruxDespachosNuevo/docs/sessions/2026-05-17-facturapi-csf-sync-notifications.md

Sesión de cambios: 2026-05-17

Resumen

Correcciones y mejoras en onboarding de Facturapi, extracción de CSF, sincronización SAT inicial y notificaciones por email.

---

1. Facturapi onboarding — Datos fiscales + Carta Manifiesto

Problema

Las organizaciones Facturapi creadas por API quedaban sin datos fiscales (legal) y sin flujo para firmar la Carta Manifiesto (requerimiento SAT/RMF).

Cambios

Backend: apps/api/src/services/contribuyente-facturapi.service.ts

• Extraídos helpers reutilizables:
  • fetchContribuyenteFiscalData() — consulta RFC, razón social, régimen, CP, domicilio
  • buildLegalPayload() — construye body para PUT /legal
  • putOrgLegal() — ejecuta el PUT
• Nuevo updateOrgLegalOnCreate() — actualiza automáticamente los datos fiscales tras crear/recuperar una org
• createOrgContribuyente() ahora llama updateOrgLegalOnCreate() en los 3 casos (reused, recreated, fresh create)
• Refactorizado ensureOrgLegalForEmit() para usar los mismos helpers (DRY)

Backend: apps/api/src/services/sat/sat-csf-login.ts

• loginSatCsf() ahora acepta knownRfc opcional
• Timeout de espera del RFC auto-populado aumentado de 30s a 60s
• Fallback manual: si el SAT no auto-popula el RFC, se llena manualmente con knownRfc

Backend: apps/api/src/services/constancia.service.ts

• Ambas llamadas a loginSatCsf ahora pasan fiel.rfc

Frontend: apps/web/app/(dashboard)/configuracion/csd/page.tsx

• Nueva sección "Carta Manifiesto" con iframe embebido de Facturapi
• Aparece cuando la org está configurada (orgStatus?.configured)
• URL: https://www.facturapi.io/embedded/manifiesto?organization={orgId}

Frontend: apps/web/lib/api/constancias.ts

• consultarConstancia() ahora acepta contribuyenteId opcional

Frontend: apps/web/lib/hooks/use-constancias.ts

• useConsultarConstancia ahora pasa selectedContribuyenteId a la API

---

2. CSF de Carlos Husberto Torres Romero

Problema

La FIEL de Carlos Husberto se subió el 16/05 pero la CSF nunca se extrajo. El scraper falló con page.waitForFunction: Timeout 30000ms exceeded.

Acciones

• Actualizados datos fiscales de la org 6a08b242ec01fdfa232ed5cc en Facturapi:
  • tax_system: 601 → 612
  • Dirección completa sincronizada desde la CSF
• Extraída CSF manualmente desde el servidor (113 CFDIs insertados)
• Disparado sync inicial SAT para Carlos Husberto (job en progreso)

---

3. Sync inicial SAT por contribuyente

Problema

needsInitialSync() solo verificaba a nivel tenant. Si un tenant ya había tenido un sync inicial (legacy), los nuevos contribuyentes nunca recibían su extracción histórica.

Cambios

apps/api/src/jobs/sat-sync.job.ts

• needsInitialSync() ahora acepta contribuyenteId opcional
  • Si se pasa: busca jobs initial completados para ese contribuyente
  • Si no: mantiene comportamiento legacy a nivel tenant
• syncTenant() determina initial vs daily por cada contribuyente dentro del loop
• incrementalSyncTenant() verifica que cada contribuyente tenga su initial antes de hacer incremental

---

4. Notificaciones de documentos para admins

Problema

Cuando un global_admin subía una declaración/documento para otro tenant, la notificación buscaba los owners del tenant del admin en lugar del tenant destino.

Cambios

apps/api/src/controllers/documentos.controller.ts

• notifyDocumentoSubido ahora usa req.viewingTenantId ?? req.user!.tenantId
• Corregido en ambos endpoints: crear declaración y crear documento extra

---

Archivos modificados

• apps/api/src/controllers/documentos.controller.ts
• apps/api/src/jobs/sat-sync.job.ts
• apps/api/src/services/constancia.service.ts
• apps/api/src/services/contribuyente-facturapi.service.ts
• apps/api/src/services/sat/sat-csf-login.ts
• apps/web/app/(dashboard)/configuracion/csd/page.tsx
• apps/web/lib/api/constancias.ts
• apps/web/lib/hooks/use-constancias.ts