Un sitio inmobiliario completo y abierto que corre sobre la Express API: miralo andando, desplegalo en minutos y modificalo como quieras.
La wiki documenta las 21 acciones una por una. Esta página contesta la otra pregunta, la que aparece primero: ¿cómo armo un sitio con esto?
1. Miralo andando
express.mapaprop.com es el sitio corriendo sobre una cuenta de Mapaprop real, con la Express API de producción. Lo que ves ahí es lo que se despliega: no es una maqueta.
El código está en github.com/Mapaprop/mapaprop-express-starter, con licencia MIT.
2. Qué es
Un sitio web completo —inicio, destacadas, buscador, ficha de propiedad, emprendimientos, blog, contacto y captación de propietarios— escrito en HTML y JavaScript, sin framework y sin paso de compilación. Lo abrís, lo editás y ves el cambio.
No es un ejemplo de código suelto: es la implementación que mantenemos con cada cambio de la Express API, y la misma que usamos para mostrar la API funcionando.
| Lo que trae del lado del cliente | HTML, CSS y JavaScript sin dependencias: nada que instalar, nada que compilar |
| Lo que trae del lado del servidor | una función que guarda tu token y le habla a la API por vos |
| Los idiomas | español, inglés y portugués, con selector |
| Los tests | 131, sin dependencias externas |
| La licencia | MIT: usalo, cambialo y publicalo como quieras |
El diseño —colores, tipografía, logo, portada, llamados a la acción, redes y pie— sale de tu cuenta si activás el sitio web de Mapaprop y lo atás a tu token. Sin eso, el sitio usa los valores de respaldo de public/js/config.js.
3. De cero a desplegado
- Tené tu plan. La Express API viene incluida desde Mapaprop Pro+.
- Activá tu token en Configuración > Token de API. Guía paso a paso: Express API Token.
- Desplegá el sitio. El repositorio tiene un botón de Vercel que clona el proyecto y te pide el token durante el proceso; queda guardado como variable de entorno
MAPAPROP_API_TOKEN. - Editá
public/js/config.jscon tus datos de respaldo y publicá de nuevo.
No necesitás activar el scope CORS: el sitio le habla a la API desde el servidor, no desde el navegador. El scope CORS hace falta cuando el JavaScript del navegador llama a la API directamente, que es justo lo que este sitio evita.
También funciona en tu propio servidor: es un servidor Node sin dependencias, se levanta detrás de nginx o Apache como cualquier otra aplicación. Lo que no alcanza es un hosting de archivos estáticos sueltos, porque hace falta ejecutar la función que guarda el token.
4. Probarlo sin cuenta y sin token
git clone https://github.com/Mapaprop/mapaprop-express-starter
cd mapaprop-express-starter
npm run dev:mock # http://localhost:3000
Eso arranca el sitio contra las fixtures del repositorio, que son respuestas reales de la API anonimizadas. Es la forma de mirarlo, de trabajar el diseño y de mandar un cambio sin ser cliente de Mapaprop. En modo mock los formularios no envían nada a ningún lado.
Con tu token, el modo real:
cp .env.example .env.local # y pegá tu token adentro
npm run dev # http://localhost:3000
npm test # la suite completa
5. El mapa del código
Para el desarrollador que va a modificarlo, lo que toca cada cosa:
| Archivo | Qué resuelve |
|---|---|
api/mp/[...path].js | la función de servidor: agrega el token y deja pasar sólo las acciones que el sitio usa |
dev-local.mjs | el servidor Node que despacha a esa misma función, para tu máquina o tu hosting |
public/js/config.js | tus datos de respaldo. Es lo primero que vas a editar |
public/js/api.js | el cliente que le habla a la función de servidor |
public/js/brand.js | aplica el diseño de tu cuenta: colores, tipografía, logo y favicon |
public/js/i18n.js | los textos en los tres idiomas y el selector |
public/js/ui.js | el render compartido: precios, fotos, características y paginado |
public/css/style.css | todo el estilo, en un archivo |
public/<sección>/index.html | una carpeta por sección, servida en /<sección> |
fixtures/ | las respuestas anonimizadas y el servidor del modo mock |
tests/ | la suite, que corre sin instalar nada |
6. Por qué el token va del lado del servidor
Es la decisión de arquitectura más importante del proyecto, y la que conviene entender antes de cambiarla.
Tu cuenta tiene un solo API Token, ese token lleva todos los permisos que te da tu plan y no vence. Si tenés contratado el adicional de Property API, el mismo token también puede crear propiedades y publicarlas en los portales. Puesto en el JavaScript del sitio, cualquier visitante lo leería desde las herramientas de desarrollo del navegador y se quedaría con una credencial permanente de tu cuenta.
Por eso vive en una variable de entorno del servidor, y el navegador le habla a una función que es la única que lo conoce. Esa función además:
- deja pasar sólo las acciones que el sitio usa, por una lista explícita. Sin esa lista, una ruta armada a mano podría llegar con tu token a otra parte de la API.
- filtra el cuerpo de los dos formularios contra los campos que cada acción documenta.
- recorta
settings-v2a lo que el sitio usa. Esa acción devuelve, además de tu nombre y tus datos de contacto, tus datos fiscales y las claves de Mapbox y reCAPTCHA de tu cuenta. Todo lo que la función devuelve queda público, así que lo que el sitio no necesita no sale. - completa la IP, el navegador y el referer de cada consulta: son datos que la acción de consultas necesita y que el navegador no puede declarar de sí mismo.
- cachea los catálogos para no gastar llamadas de más.
Si sumás una acción nueva, agregala a esa lista. Y si necesitás un campo de settings-v2 que hoy no sale, agregalo a propósito y preguntate si ese campo puede quedar publicado, porque es exactamente lo que va a pasar.
El sitio también declara una Content-Security-Policy y tres cabeceras más, y el servidor Node las lee del mismo archivo que Vercel: así la defensa no depende de dónde lo desplegaste.
7. Las consultas vuelven a tu CRM
El formulario de cada ficha postea a messages, así que la consulta entra a tu Inbox de Mapaprop como un lead: la asignás a un asesor, le hacés seguimiento, queda en tus reportes y dispara tus automatizaciones.
Si lo cambiás por un formulario que te manda un email y nada más, el círculo se corta: seguís cargando las propiedades en Mapaprop y atendés a los clientes afuera, donde la consulta no existe para tu CRM.
El formulario de captación de propietarios usa seller-submissions: crea el contacto en tu CRM y te manda un email con los adjuntos. Esa acción sí necesita un sitio atado a tu token.
8. Qué no cubre
| La consulta genérica | messages exige una propiedad publicada, así que una consulta que no es sobre ninguna propiedad no entra al CRM por la API. La página de contacto del sitio muestra tus sucursales con teléfono, email y WhatsApp, y su formulario abre el programa de correo del visitante |
| El hosting y el mantenimiento | corren por tu cuenta. Es la contracara de tener el código: nadie te lo actualiza en tu servidor |
| 20 propiedades por pedido | es el tope de la API. El listado pagina solo |
| Los borradores | la API devuelve sólo propiedades publicadas |
| Los adjuntos de captación | 2 MB por archivo, y el techo real lo pone el total del envío: viajan codificados y eso infla el cuerpo cerca de un tercio |
Si regenerás tu token, el anterior deja de funcionar al instante: actualizá la variable de entorno y volvé a desplegar. Si das de baja el plan, el token se desactiva y el sitio deja de traer propiedades.
9. Cómo colaborar
El repositorio es público y recibe pull requests.
- Si te falta algo —un filtro, un bloque, un idioma—, abrí un issue en github.com/Mapaprop/mapaprop-express-starter/issues y lo vemos.
- Si ya lo resolviste, mandá tu PR. El modo mock existe justamente para que puedas trabajar y probar sin una cuenta.
- Si encontrás un problema de seguridad, está escrito cómo reportarlo en el
SECURITY.mddel repositorio.