Saltar al contenido principal

Backend: integraciones y operacion

Integraciones externas​

IntegracionUso principal
Firebase AdminAuth, Firestore, FCM y operaciones de usuario
FirestorePersistencia principal
Google Cloud TasksAutomatizaciones diferidas
Infobip WhatsApp APIMensajeria al cliente
Firebase Cloud MessagingPush web al equipo
Firebase StorageArchivos e imagenes de negocios, sedes y usuarios

Firebase Admin​

Se usa para:

  • validar tokens
  • crear o eliminar usuarios de Auth
  • interactuar con Firestore
  • enviar push via FCM
  • borrar archivos de Storage en ciertos flujos de limpieza
  • apoyar ciertos flujos de limpieza

Dependencia critica:

  • FIREBASE_CREDENTIALS_PATH
  • FIREBASE_STORAGE_BUCKET

Firestore​

FirestoreService centraliza:

  • CRUD basico
  • consultas paginadas
  • subcolecciones
  • conversion de timestamps
  • logging de queries lentas

Google Cloud Tasks​

Cloud Tasks soporta automatizaciones alrededor de appointments.

Hoy se documentan dos tasks por cita:

  • appointment-status-in-progress
  • appointment-status-finished

El objetivo es mover automaticamente una cita cuando llega su hora.

Tambien se usa para disparar procesos diferidos del outbox, por ejemplo cascadas o limpieza de recursos que no deberian depender de que un request HTTP permanezca vivo.

Infobip WhatsApp​

Se usa para plantillas de mensajeria como:

  • confirmacion de cita
  • modificacion o cancelacion
  • cierre o finalizacion

Validaciones conocidas:

  • el telefono se normaliza a formato internacional
  • rechazos del proveedor se reportan como error controlado
  • las plantillas cambian por ambiente: en produccion usan sufijo _prd y en desarrollo conservan los nombres base

Outbox​

El backend tiene un outbox persistido en OutboxEvents para efectos diferidos o reintentables.

Estados conocidos:

  • PENDING
  • PROCESSING
  • DONE
  • ERROR
  • PAUSED

Tipos conocidos incluyen eventos de bookings, sincronizacion de metricas, WhatsApp, push, tasks de appointments, borrado en cascada de negocio, limpieza de Storage y sincronizacion/eliminacion de usuarios en Auth.

Endpoints internos:

  • GET /outbox
  • GET /outbox/:id
  • POST /outbox/process
  • POST /outbox/:id/requeue

Todos requieren x-internal-task-token, aunque esten exentos de Firebase Auth para que Cloud Tasks o Scheduler puedan llamarlos.

Push web​

El backend maneja suscripciones de dispositivos y puede enviar notificaciones al equipo.

Comportamientos documentados:

  • un deviceId no debe quedar asociado a multiples usuarios a la vez
  • tokens invalidos se limpian automaticamente
  • el link de destino se construye con FRONTEND_APP_BASE_URL

Variables de entorno​

Base​

  • PORT
  • FIREBASE_CREDENTIALS_PATH
  • FIREBASE_STORAGE_BUCKET
  • ENV

WhatsApp / Infobip​

  • INFOBIP_BASE_URL
  • INFOBIP_API_KEY
  • INFOBIP_WHATSAPP_SENDER
  • INFOBIP_TIMEOUT_MS

Cloud Tasks​

  • CLOUD_TASKS_PROJECT_ID
  • CLOUD_TASKS_LOCATION
  • CLOUD_TASKS_QUEUE
  • CLOUD_TASKS_MAX_ATTEMPTS
  • CLOUD_TASKS_TARGET_BASE_URL
  • CLOUD_TASKS_INTERNAL_TOKEN

Frontend y push​

  • FRONTEND_APP_BASE_URL
  • PUSH_NOTIFICATIONS_ENABLED

Flujos operativos importantes​

Alta de booking​

  1. validar negocio, cliente, sede, servicio y horario
  2. consumir cupo de booking
  3. crear booking y appointments
  4. recalcular metricas economicas
  5. programar tasks
  6. intentar WhatsApp y push

Finalizacion de cita​

  1. actualizar estado
  2. sincronizar booking si aplica
  3. actualizar metricas
  4. limpiar tasks pendientes
  5. si el booking termina, intentar WhatsApp de finalizacion

Reconciliacion de usage​

El endpoint interno POST /business/usage/reconcile-today sirve para:

  • activar o desactivar periodos de uso
  • corregir cupos restantes
  • recalcular subscriptionStatus

Comandos de operacion​

Segun package.json del backend:

npm run dev
npm run typecheck
npm run build
npm run start
npm run seed:prod:base:dry-run
npm run seed:prod:base
npm run deploy:prod:indexes
npm run deploy:dev
npm run deploy:prod

Los despliegues actuales separan ambiente de desarrollo y produccion. Produccion apunta a cutlyy-prd, cutlyy-api-prod, api.cutlyy.com y app.cutlyy.com; desarrollo conserva barber-app-dev-c7f59 y dominios *.dev.cutlyy.com.

Healthcheck​

GET /health responde un JSON liviano con:

  • status
  • service
  • timestamp

Sirve para ver que el proceso HTTP esta vivo. No reemplaza una prueba profunda de dependencias como Firestore, Infobip o Cloud Tasks.

Riesgos operativos actuales​

  • no hay suite automatizada de regresion
  • el healthcheck actual no valida dependencias externas
  • el rate limit no es distribuido
  • varias automatizaciones dependen de que el token interno y la base URL de Cloud Tasks esten correctos

Documentos relacionados​