Introducción a la Express API

Construí tu propio sitio o app —que corre en tu propio servidor, con tu web y tu diseño— usando la Express API de Mapaprop para servir el inventario de tu cuenta (propiedades, desarrollos, sucursales, zonas). Es una API para desarrolladores: el sitio o sistema es tuyo y lo consumís desde afuera; Mapaprop no lo hospeda. Todos los métodos operan sobre la cuenta dueña del token —tu inventario y tu configuración—: el scope sale del access token, no se envía como parámetro. Las consultas que envíen tus visitantes ingresan a tu Inbox de Mapaprop.

1. Obtené tu access token

La Express API funciona con tu Token de API de Mapaprop (no con el registro de app OAuth2 de terceros). Si ya sos cliente Mapaprop Pro+ (o superior), activás tu token con un clic desde tu cuenta —Configuración > API Token— y lo usás como Authorization: Bearer {token}. El token no expira (salvo que lo regeneres o lo desactives). Guía paso a paso: Express API Token.

2. Cómo se resuelve tu sitio

Cuáles necesitan un sitio y cuáles no

Solo once servicios necesitan un sitio: los que devuelven contenido del sitio —settings, settings-v2, design, features, menus, pages, pages/{url}, pages/static/{pageId}, posts, posts/{url}, featureds—. Sirven para armar tu sitio con contenido que administrás desde Mapaprop.

Todos los servicios de inventario funcionan sin sitio: se resuelven únicamente con la cuenta dueña del token. Son properties, properties/{propertyHash}, developments, development/properties, branches, types, operations, zones, zones/suggestions y messages (el envío de consultas).

Cómo se elige el sitio

Para los once servicios de contenido no hace falta que envíes cuál: tu sitio queda atado a tu Token de API desde tu cuenta de Mapaprop, y todos lo usan automáticamente. Lo atás —o creás uno— desde Configuración > Token de API, en la tarjeta Función Sitio Web.

El sitio se resuelve así:

1. Tu token ya tiene un sitio atado → se usa ese. Es el caso normal y no tenés que hacer nada.
2. Tu token no tiene sitio atado y tenés un solo sitio activo → se usa ese.
3. Tu token no tiene sitio atado y tenés más de un sitio activo → tenés que indicar cuál con el parámetro websiteId. Ejemplo: GET /api/action/express-v1/settings-v2?websiteId=1234. Solo se acepta un websiteId que sea uno de tus propios sitios activos (se valida contra la cuenta de tu token); cualquier otro se rechaza.

Un sitio cuenta como activo desde que lo creás en tu cuenta. No hace falta que tenga un dominio apuntado ni contenido cargado.

Errores al resolver el sitio

Ante un error, la respuesta es un JSON con los campos error (un código estable, ideal para tu integración) y description (texto legible), con estado HTTP 400:

{
  "error": "AMBIGUOUS_WEBSITE",
  "description": "El cliente tiene mas de un sitio activo. Especifique el parametro websiteId."
}

3. Flujo básico

Lo que armás con esta API es tu sitio con tu inventario. Todo se resuelve con el token: no hay que mandar de qué cuenta se trata.

1 · Traé los catálogos, una vez

types y operations devuelven los tipos y operaciones que vos tenés en uso, no el catálogo entero del país. Con eso armás los filtros del buscador sin ofrecer opciones que no van a dar ningún resultado. zones hace lo mismo con las zonas donde tenés propiedades, y zones/suggestions resuelve el autocompletado cuando el visitante escribe.

Cambian poco: traelos al arrancar y cacheálos.

2 · Listá y buscá

properties es el listado, con from y size para paginar.

3 · Mostrá la ficha

properties/{propertyHash} trae la propiedad completa.

4 · Los desarrollos

developments lista tus emprendimientos. Cada uno trae en developmentProperties los ids de sus unidades, y con esos ids pedís las unidades a development/properties.

Sobre los campos del desarrollo —los 10 que declara la inmobiliaria y el bloque developmentStats con los números derivados de las unidades— mirá la página de developments.

5 · Recibí las consultas

messages envía la consulta de tu visitante, y entra a tu Inbox de Mapaprop como cualquier otra. Si tu sitio además recibe propiedades de potenciales vendedores, eso va por seller-submissions — y es el único servicio de inventario que sí necesita un sitio (ver arriba).

6 · El contenido del sitio, si lo administrás desde Mapaprop

Sólo si usás Mapaprop para el contenido además del inventario: settings-v2 (la configuración), design (colores y tipografía), features, menus, pages y posts.

Éstos son los que necesitan un sitio resuelto — es lo que explica la sección anterior. Si tu contenido vive en tu CMS, no los vas a usar nunca.

4. Explorar servicios

GET /api/action/express-v1/settings-v2

GET /api/action/express-v1/design

GET /api/action/express-v1/branches

GET /api/action/express-v1/menus

GET /api/action/express-v1/types

GET /api/action/express-v1/operations

GET /api/action/express-v1/pages

GET /api/action/express-v1/pages/{url}

GET /api/action/express-v1/pages/static/{pageId}

GET /api/action/express-v1/posts

GET /api/action/express-v1/posts/{url}

GET /api/action/express-v1/zones

GET /api/action/express-v1/zones/suggestions

GET /api/action/express-v1/properties

GET /api/action/express-v1/development/properties

GET /api/action/express-v1/developments

GET /api/action/express-v1/properties/{propertyHash}

POST /api/action/express-v1/messages

POST /api/action/express-v1/seller-submissions

GET /api/action/express-v1/features

GET /api/action/express-v1/settings deprecado