Saltar al contenido principal

Backend: API y seguridad

Alcance​

Este documento describe el estado actual de la API. No necesariamente representa el estado ideal deseado.

Convenciones generales​

  • no existe prefijo global como /api o /v1
  • la paginacion tipica usa page y pageSize
  • el maximo usual de pageSize es 100

Headers importantes​

HeaderPara que sirve
AuthorizationLleva el Firebase ID token de la sesion
businessIdDefine el tenant activo en rutas privadas multiempresa
x-internal-task-tokenProtege endpoints internos de automatizacion

Autenticacion​

La API usa Firebase Admin para validar Authorization: Bearer <token>.

Cuando el token es valido:

  • se resuelve la identidad del usuario
  • se inyecta contexto de autenticacion en la request

Validacion de businessId​

En rutas privadas que no esten exentas, el backend exige businessId.

No se valida solo la presencia del header. Tambien se valida:

  • existencia del negocio
  • existencia del plan
  • suscripcion activa
  • plan activo

Rate limiting​

El sistema incluye un rate limit en memoria con estas caracteristicas documentadas:

  • ventana de 1 segundo
  • maximo de 10 requests por segundo
  • clave basada en origen, metodo y path

Modulos API expuestos​

Base pathOperaciones tipicas
/authlogin y registro
/businessCRUD de negocio y reconciliacion de usage
/branchesCRUD de sedes
/servicesCRUD de servicios
/modulescatalogo funcional
/permissionspermisos base
/rolesroles del sistema
/business-membershipsmembresias, rol y sede
/usersconsulta y actualizacion de usuarios
/appointmentsagenda operativa
/bookingsreserva comercial y pagos
/reviewsreseñas
/metricsmetricas agregadas
/plansplanes de la plataforma
/push-notificationsregistro y baja de dispositivos
/whatsappmensajeria interna automatizada

Estado actual de acceso​

Rutas publicas o publicadas por prefijo​

Segun la configuracion actual, existen prefijos o endpoints que hoy quedan publicos, por ejemplo:

  • /auth
  • /branches
  • /services
  • /appointments
  • /modules
  • /permissions
  • /roles
  • GET /bookings
  • POST /bookings
  • PUT /bookings*
  • GET /users
  • GET /reviews
  • POST /reviews

Esto es importante porque forma parte del comportamiento real del sistema y debe revisarse con criterio de seguridad.

Rutas privadas sin businessId​

Algunas mutaciones privadas quedan exentas del header businessId, por ejemplo:

  • mutaciones de negocios
  • mutaciones de planes
  • alta de ciertas memberships por documento
  • suscripciones push

Endpoints internos​

Dos flujos documentados dependen de x-internal-task-token:

  • POST /whatsapp/send-message/:type
  • POST /business/usage/reconcile-today

Aunque alguno de esos endpoints pueda aparecer dentro de rutas tratadas como publicas, su proteccion real depende de ese token interno.

Filtros importantes​

Appointments​

Admite filtros como:

  • businessId
  • id
  • employeeId
  • bookingId
  • startDate
  • endDate
  • sameDate
  • includeDeletes

Bookings​

Admite filtros como:

  • id
  • businessId
  • clientId
  • consecutive
  • status
  • includeDeletes

Metrics​

Admite filtros como:

  • metricTypes
  • entityType
  • businessId
  • branchId
  • employeeId
  • timeframe
  • startDate
  • endDate

Riesgos y observaciones​

  • hay superficie publica mayor a la que normalmente se esperaria en una API privada
  • no existe especificacion formal OpenAPI
  • el rate limit es en memoria y no se comparte entre replicas
  • seguridad de tareas internas depende de configurar bien el token interno

Lectura recomendada​