Entregable técnico — Integra Bienes y Raíces

Sitio público: integrabienesyraices.com Portal interno: integrabienesyraices.com/portal Versión del documento: 1.0 · Junio 2026 Plataforma: SocialSphereMX (Next.js 16 · App Router · SQLite + Prisma · Turbopack)

Este documento describe qué se construyó, cómo está estructurado y cómo se opera el portal inmobiliario de Integra Bienes y Raíces. Está pensado como guía de referencia rápida para el equipo interno y como entregable formal hacia el cliente. No incluye componentes del modelo SaaS genérico de SocialSphereMX, ni datos de otros clientes, ni precios de plataforma.

Tabla de contenido

1. Resumen ejecutivo
2. Accesos y credenciales
3. Páginas públicas (cara al cliente final)
4. Páginas internas (portal del equipo)
5. Inventario de APIs
6. Soporte para Google Ads y marketing digital
7. Captura de Prospectos: chatbot y modal reutilizable
8. SEO, analítica y rendimiento
9. Seguridad operacional
10. Mantenimiento y operación diaria
11. Roadmap recomendado (no incluido en este alcance)
12. Firma y contacto del responsable técnico

1. Resumen ejecutivo

Integra Bienes y Raíces cuenta con un portal inmobiliario de marca blanca desplegado bajo el dominio propio integrabienesyraices.com. La plataforma entrega, en un mismo producto:

• Frente público orientado a la conversión: catálogo de propiedades, página de detalle, página de "administramos tu propiedad", testimonios, blog, contacto.
• Portal interno multi-rol para el equipo de Integra con catálogo editable, CRM, calendario, configuración de campos y amenidades, gestión de comisiones.
• Captura de Prospectos vía modal reutilizable (4 flujos: publicar, administrar, agendar, contactar) y chatbot público (árbol de decisión bayesiano, sin IA).
• RBAC con tres roles: superadmin (Aurelio y Angelica — padre e hija), admin (David Aurelio — accesos a la cuenta publicitaria de Facebook), agent (Uriel, Braulio, Adriana).

El sistema NO depende de servicios externos pagos para operar el flujo principal de captura. Todo corre en una sola instancia Node con SQLite.

Alcance entregado

2. Accesos y credenciales

2.1 Equipo de Integra (ClientUser del portal)

Todos los usuarios del portal interno se autentican en /portal/login con correo + contraseña. Las contraseñas son placeholder inicial: cada usuario debe cambiarla en su primer ingreso, o bien el superadmin puede resetearla desde /portal/bienes-raices/agents.

Importante sobre jerarquía: Aurelio Montante es el padre. Sus dos hijos son David Aurelio (rol admin — quien tiene los accesos a la cuenta publicitaria de Facebook del equipo y por eso es quien carga el Pixel ID y los tokens de CAPI desde la pestaña Meta config) y Angelica (rol superadmin — quien opera el portal día a día: atender clientes, cargar propiedades, enviar propuestas). Cualquier decisión crítica del portal (precios, comisiones, eliminar propiedad, invitar nuevo agente) puede ser ejecutada por cualquiera de los tres, en coordinación con la agencia.

2.2 Acceso al panel de plataforma SocialSphereMX

El panel interno de la plataforma (donde se configura el tenant, integraciones y branding) es independiente del portal del cliente. Las credenciales de ese panel las conserva David Aurelio Montante y se comparten únicamente bajo solicitud expresa.

2.3 DNS y dominio

3. Páginas públicas (cara al cliente final)

Las páginas públicas son las que cualquier visitante ve sin autenticarse. Están construidas con componentes server-rendered (RSC) para SEO óptimo y un primer paint muy rápido.

3.1 Inventario de rutas públicas

3.2 Componentes clave del frente público

• <Header /> — Logo, navegación, botón "Contactar" que abre el modal reutilizable en estado menú. En móvil colapsa a UserBadge + Contactar compacto.
• <Hero /> — Headline, subheadline, CTA primario "Iniciar Proyecto" que abre el modal reutilizable (estado menú). 100% responsive; el botón WhatsApp se quitó en favor del modal para centralizar la captura.
• <PropertyCard /> — Card del catálogo. Muestra foto, precio, amenidades destacadas, icono de no-disponible cuando el status lo amerita. 3 campos personalizados destacados (recámaras, baños, m²).
• <PropertyDetail /> — Galería, mapa (Google Maps embed), amenidades, características específicas, formulario de contacto atado a la propiedad, CTA único "Administramos tu propiedad" (sin duplicados).
• <FloatingActions /> — Esquina inferior derecha. Contiene solo QR + Chatbot (el botón WhatsApp flotante se eliminó porque duplicaba el flujo del chatbot).
• <ReusableContactModal /> — Modal único de captura con 4 estados: menu, publish, adminProperty, schedule, contact, success. Un solo componente, una sola API, accesible desde header, hero, chatbot, detail, landing de administración.
• <PropertyChatbot /> — Chatbot bayesiano de 7 nodos. NO usa IA; es un árbol de decisión hardcoded en PropertyChatbot.tsx. Cada intent (publicar, administrar, agendar, contactar) abre el modal reutilizable en su estado correspondiente.

3.3 Página de detalle de propiedad — qué incluye

1. Hero con foto principal + precio + tipo + operación.
2. Galería con lightbox (móvil-friendly, swipe gestures).
3. Características específicas (sub-items configurables: recámaras, niveles, m² construcción, m² fondo, lote, etc.).
4. Amenidades organizadas por categoría (seguridad, recreación, accesibilidad, servicios, ambiente, educación).
5. Mapa embebido (Google Maps iframe, sin API key requerida para uso básico).
6. Formulario de contacto atado a la propiedad (nombre, email, teléfono, mensaje). Al enviar crea un Contact con source=modal.contact y notifica a los superadmins.
7. CTA único "Administra tu propiedad con nosotros" → /administramos.
8. Propiedades relacionadas (mismo tipo, misma zona, ±20% precio).

4. Páginas internas (portal del equipo)

El portal autenticado vive bajo /portal/* y requiere sesión activa (cookie client_token firmada con JWT HS256). Toda la operación del equipo ocurre aquí.

4.1 Inventario de rutas internas

4.2 Permisos por rol

5. Inventario de APIs

El sistema expone ~80 endpoints HTTP distribuidos entre público, portal autenticado y panel de plataforma. Todos devuelven JSON.

5.1 APIs públicas (sin autenticación)

5.2 APIs del portal autenticado (/api/portal/*)

Requieren cookie client_token válida. Los endpoints sensibles además validan RBAC.

5.3 APIs de admin de plataforma (/api/admin/*)

Reservadas al equipo de SocialSphereMX. NO son accesibles desde el portal de Integra.

Total estimado: ~80 endpoints entre los tres grupos (público + portal + admin de plataforma).

6. Soporte para Google Ads y marketing digital

El sistema está listo para correr campañas de Google Ads, Meta Ads y cualquier canal que requiera tracking de conversión. El setup es agnóstico al proveedor; se implementó siguiendo las recomendaciones oficiales de gtag.js.

6.1 Google Tag (gtag.js)

• Medición: GA4 cargado vía <Script strategy="afterInteractive"> en el layout raíz, usando NEXT_PUBLIC_GA_MEASUREMENT_ID.
• Eventos automáticos: page_view, scroll, click, file_download, video_start.
• Eventos personalizados (a través del modal reutilizable):
  • generate_lead (intent: contact, schedule)
  • sign_up (intent: publish o adminProperty)
  • schedule_visit (intent: schedule)

6.2 Conversiones de Google Ads

Para activar la medición de conversiones de Google Ads:

1. Crear acción de conversión en Google Ads (tipo Lead o Contact según la campaña).
2. Obtener el Conversion ID y Conversion Label.
3. Solicitar al equipo técnico agregar NEXT_PUBLIC_GADS_CONVERSION_ID + NEXT_PUBLIC_GADS_CONVERSION_LABEL al .env del deploy.
4. Cada generate_lead desde el modal envía el evento ads_conversion con el label correspondiente.

6.3 UTM tracking

Todas las URLs de campañas externas deben usar los parámetros UTM estándar:

[https://integrabienesyraices.com/propiedades?utm_source=google&utm_medium=cpc&utm_campaign=venta-casa-slp&utm_content=ad-variant-a](https://integrabienesyraices.com/propiedades?utm_source=google&utm_medium=cpc&utm_campaign=venta-casa-slp&utm_content=ad-variant-a)

Los UTMs no se persisten en DB (no agregan valor analítico a largo plazo), pero sí disparan eventos a GA4 con sus valores originales, lo que permite atribución correcta en el panel de Google Ads.

6.4 Landing pages dedicadas para Ads

Recomendable crear rutas dedicadas para campañas de alto presupuesto:

• /ads/venta-casa-slp → filtro pre-aplicado a venta + casa + SLP
• /ads/renta-departamento → filtro pre-aplicado a renta + departamento

Estas rutas son estáticas y no requieren lógica nueva: solo pasan query params al catálogo. Pídale al equipo técnico que las configure.

6.5 Pixel de Meta (Facebook / Instagram)

Si se requiere tracking de Meta, el pixel se instala igual que gtag: con un <Script> adicional en el layout. No requiere cambios en el modal ni en el chatbot; los eventos personalizados ya disparan a GA4 vía window.dataLayer.

7. Captura de Prospectos: chatbot y modal reutilizable

7.1 Modal reutilizable (<ReusableContactModal />)

Un solo componente, montado en el layout raíz de la app. Cualquier botón de la UI puede abrirlo via:

import { openContactModal } from "@/app/components/reusableContactModal";

openContactModal({
  initialState: "menu" | "publish" | "adminProperty" | "schedule" | "contact",
  brandName: "Integra Bienes y Raíces",
  accentColor: "#B45309",
  propertyId, propertyName, clientId,
});

Estados del modal

Lugares donde se abre

• Header (botón Contactar en PC y móvil).
• Hero de la home (botón Iniciar Proyecto).
• Property detail (formulario de contacto lateral).
• Chatbot (cada nodo terminal: "agendar", "publicar", "administrar", "contactar").
• Floating Actions (próximamente — el botón WhatsApp se eliminó para consolidar).

Resultado de un submit

Cada submit crea una fila en Contact con:

{
  "clientId": "cmqn8p8iy0000ez1wss4u5a9l",
  "name": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "phone": "4441234567",
  "message": "Dirección: ... · Tipo: casa · Operación: venta",
  "services": "["publish"]",
  "source": "modal",
  "status": "new",
  "metadata": {
    "source": "modal.publish",
    "intent": "publish",
    "propertyId": null,
    "propertyName": null,
    "preferredDate": null,
    "propertyAddress": "...",
    "propertyType": "casa",
    "operationType": "venta",
    "ip": "189.xxx.xxx.xxx"
  }
}

Y crea una notificación para cada superadmin activo del cliente (Aurelio y Angelica) con tipo lead.new, título "Publicar propiedad · Juan Pérez" y cuerpo con el teléfono y la dirección.

7.2 Chatbot público (<PropertyChatbot />)

No es IA. Es un árbol de decisión determinístico, escrito a mano en src/app/components/PropertyChatbot.tsx. La decisión de NO usar IA se tomó por:

1. Costo predecible: cero tokens consumidos por consulta.
2. Tiempo de respuesta: instantáneo (no hay round-trip a OpenAI).
3. Privacidad: ningún dato del visitante sale del servidor de Integra.
4. Control de marca: las respuestas son las que el equipo redactó, no alucinaciones.

Árbol del chatbot

root (4 opciones si NO estás en detalle de propiedad, 3 si sí)
├── Me interesa esta propiedad (solo si estás en /propiedades/[slug])
│   └── Captura: nombre → email → teléfono → mensaje → guarda
├── Que administren mi propiedad
│   └── Abre modal (initialState=adminProperty)
├── Agendar una visita
│   └── Abre modal (initialState=schedule)
├── Publicar mi propiedad
│   └── Abre modal (initialState=publish)
├── ¿Cómo funciona?
│   └── Explica proceso 1-2-3-4 → ofrece modal
├── Conocer al equipo
│   └── Lista equipo → ofrece modal
└── Quiero que me contacten
    └── Abre modal (initialState=contact)

Footer del chatbot

El footer del chat muestra un solo botón: "✉️ Escríbenos" (estilo del modal, color del tenant). Al hacer click, cierra el chat y abre el modal en estado contact. Esto reemplaza el antiguo botón WhatsApp directo, evitando que el visitante salga de la web y entre a una conversación que no queda registrada.

Métricas del chatbot

Todas las conversaciones quedan registradas en ChatbotConversation + ChatbotMessage para análisis posterior:

• Tasa de conversión por nodo (qué % llega a "Publicar").
• Nodos con más abandono (dónde se cierra el chat sin acción).
• Tiempo medio de conversación.

Estas métricas se exponen en /portal/reportes cuando se quieran consultar.

8. SEO, analítica y rendimiento

8.1 SEO técnico

8.2 Rendimiento

• First Contentful Paint (medido en home): <1.5s en 4G.
• Largest Contentful Paint: <2.5s.
• Cumulative Layout Shift: <0.05 (gracias a aspect-ratio reservado en cada foto).
• Bundle inicial: ~85KB gzipped (home pública).
• Server-rendered: la primera vista llega con HTML completo, sin necesidad de JS para leer el contenido (SEO-safe).

8.3 Hosting

• Single instance Node.js (PM2) detrás de Nginx.
• SQLite como base de datos (archivo único, fácil de respaldar).
• SSL vía Let's Encrypt.
• Backups: el archivo dev.db se respalda cada 6 horas a un bucket privado. Retención 30 días.

9. Seguridad operacional

9.1 Autenticación

• Portal interno: cookie client_token (JWT HS256, algoritmo pinned, secret ≥32 chars).
• Admin de plataforma: NextAuth con bcrypt + verificación de email.
• Contraseñas: bcrypt con 10 rounds; nunca se devuelven en respuestas JSON.

9.2 Validación

• Whitelist de campos en cada POST (no se persiste nada fuera del shape esperado).
• Rate limit por IP en endpoints públicos (/api/public/contact: 5 req/min).
• RBAC inline por rol en cada endpoint sensible (no se asume autenticación = autorización).
• CSRF: doble submit cookie en formularios del portal.

9.3 Datos sensibles

• No se almacenan números de tarjeta, claves interbancarias, ni datos fiscales en este portal.
• No se exponen hashes de contraseña ni tokens internos en respuestas JSON.
• Las conversaciones del chatbot persisten en DB pero NO se comparten con terceros.

9.4 Auditoría

• Cada acción crítica (login, cambio de rol, hard-delete, edición de comisiones) genera un log con timestamp + userId + IP.
• Logs disponibles en /portal/admin/audit (solo superadmin).

10. Mantenimiento y operación diaria

10.1 Tareas del equipo de Integra

10.2 Tareas del equipo técnico (SocialSphereMX)

10.3 Procedimiento ante un lead nuevo

1. Llega notificación lead.new a Aurelio y Angelica.
2. Superadmin revisa el lead en /portal/clientes → cambia status a contacted.
3. Si el lead tiene intención clara (publish, adminProperty, schedule), se asigna al agente de la zona.
4. El agente contacta al Prospecto, agenda cita, sube fotos si aplica, asigna la propiedad al agente correcto en el catálogo.
5. Cuando se cierra (vendido / rentado / dado de baja), el superadmin marca status=converted o status=lost.

11. Roadmap recomendado (no incluido en este alcance)

Estas funcionalidades no están incluidas en el alcance actual pero son las siguientes evoluciones naturales según el roadmap de producto:

1. Notificaciones push al agente cuando se asigna una propiedad con override (mejora de comisiones).
2. Reportes avanzados de comisiones generadas vs. pagadas con exportable a Excel.
3. Multi-idioma (EN/ES) con switcher en header.
4. Auto-sugerir amenidades según tipo de propiedad (basado en catálogo, no ML).
5. Mobile bottom nav con badges de notificación (mejora UX).
6. Integración con WhatsApp Business API (Meta Cloud API) para enviar mensajes automáticos desde el portal.
7. Historial de cambios en comisiones (audit log específico).

12. Firma y contacto del responsable técnico

David Alejandro Mireles Llamas Director de Producto · SocialSphereMX

• 🌐 LinkedIn: linkedin.com/in/davidmirelesll
• 💬 WhatsApp: wa.me/4446581994
• 📧 Correo: david@loust.pro

Para soporte técnico, preguntas sobre este entregable o solicitudes de evolución del portal, contactar por WhatsApp (canal preferido) o LinkedIn.

Documento generado el 26 de junio de 2026. Versión 1.0. Plataforma: SocialSphereMX · Cliente: Integra Bienes y Raíces · San Luis Potosí, México.