Referencia de la API de la interfaz headless

PLUS La interfaz headless forma parte de la API REST de WordPress y responde bajo el espacio de nombres immomakler-headless/v1. Por tanto, la URL base es

https://su-direccion-wordpress.es/wp-json/immomakler-headless/v1/

Todos los endpoints solo responden cuando ha activado la interfaz en el back end de su sitio web (wp-admin) en WP-ImmoMakler → Integraciones → Headless; consulte Modo headless con un front end propio.

Autenticación

Los endpoints de lectura son públicos de forma predeterminada. Si ha activado la opción Exigir la clave de API también para las solicitudes de lectura, cada solicitud debe enviar la clave de API, ya sea en la cabecera propia o como token Bearer:

curl -H "X-ImmoMakler-Key: SU-CLAVE-API" https://su-direccion-wordpress.es/wp-json/immomakler-headless/v1/properties

curl -H "Authorization: Bearer SU-CLAVE-API" https://su-direccion-wordpress.es/wp-json/immomakler-headless/v1/properties

Si falta la clave o no coincide, la interfaz responde con 401 y el código de error headless_unauthorized.

Parámetros comunes

Parámetro	Significado
page, per_page	Página y tamaño de página de una lista. per_page está limitado a 100 y, en el resumen /properties/manifest, a 1000.
fields	summary devuelve la forma abreviada para listas (datos de la vista de lista, imagen destacada, estado, dirección, enlaces), full el inmueble completo para la vista de detalle. Las listas devuelven summary de forma predeterminada; la consulta individual, full.
status	open muestra los inmuebles del listado de inmuebles, reference solo los inmuebles de referencia, all ambos. Las listas devuelven open de forma predeterminada; la consulta individual, all.
modified_since	Solo los inmuebles modificados desde este momento (ISO 8601, por ejemplo 2026-10-11T08:00:00Z).
locale	Idioma de las denominaciones y de los nombres de categoría, por ejemplo de_DE o en. En sitios web multilingües con WPML o Polylang, el parámetro cambia también el idioma de los inmuebles.

Las listas responden con una envoltura:

{
  "items": [],
  "total": 42,
  "total_pages": 3,
  "page": 1,
  "per_page": 20,
  "generated_at": "2026-10-11T08:15:00+00:00"
}

Además, las listas incluyen las cabeceras X-WP-Total, X-WP-TotalPages y una cabecera Link con rel="next" y rel="prev".

Caché

Las respuestas de lectura incluyen Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600 y un ETag. Si envía el ETag en la cabecera If-None-Match en la siguiente consulta, la interfaz responde con 304 Not Modified mientras los datos no hayan cambiado. En el navegador, de esto se encarga por sí sola la caché HTTP del navegador; si un front end envía If-None-Match por su cuenta, su código recibe una respuesta vacía cuando los datos no han cambiado y debe usar entonces los datos cargados anteriormente. Tras cada transferencia de su software CRM y tras cada modificación de un inmueble, WP-ImmoMakler descarta su caché, de modo que la siguiente solicitud devuelve los datos actuales.

Endpoints

GET /site

Describe el sitio web una vez por compilación: la dirección de WordPress y del front end, los patrones de ruta, los idiomas disponibles (locales y, en languages, el código, el locale, el nombre, el idioma predeterminado y el directorio del front end prefix de cada uno), la moneda, las funciones disponibles (PDF, lista de favoritos, alertas de búsqueda, búsqueda por radio), todas las categorías con variable de consulta y ruta de URL, los campos de datos elegidos en su configuración (keys.archive, keys.single, keys.single_areas, keys.single_prices, keys.epass, keys.contact), los tamaños de imagen registrados y, en search, la estructura de su formulario de búsqueda: las categorías mostradas, los rangos con slug, unidad, tamaño de paso y valor máximo, las ordenaciones con su etiqueta, la ordenación predeterminada, la búsqueda por radio con sus radios y, en search.places, el autocompletado de direcciones de la búsqueda por radio, si ha configurado un proveedor para ello (véase más abajo).

GET /properties

La lista de inmuebles, con los modificados más recientemente primero. Admite page, per_page, fields, status, modified_since y locale.

GET /properties/manifest

El resumen compacto de todos los inmuebles visibles para la sincronización al compilar un front end estático. Cada entrada indica objektnr_extern, post_id, slug, language, modified_gmt, public_since, is_reference, is_project, is_project_unit y frontend_url. Admite page, per_page (hasta 1000), status y locale.

GET /properties/{objektnr_extern}

Un inmueble, direccionado mediante su número de objeto. El número de objeto se pasa codificado como URL (A%2F1 para A/1); las mayúsculas y minúsculas no importan. Un inmueble que el listado de inmuebles no muestra responde con 404 y el código de error headless_not_found. Admite fields, status y locale.

GET /search

La búsqueda de inmuebles con los filtros de su sitio web. Los parámetros se llaman igual que en la búsqueda de su sitio WordPress, de modo que una dirección filtrada del listado de inmuebles y una solicitud de búsqueda significan lo mismo:

• Categorías mediante su variable de consulta (typ, vermarktungsart, nutzungsart, ort, land, ausstattung) con slugs de términos; la categoría de estado se llama aquí objektstatus, porque status elige, como en /properties, entre inmuebles abiertos, referencias y todos. Separe varios términos con una coma si basta con que coincida uno (typ=wohnung,haus), o con un signo más si deben coincidir todos (ausstattung=balkon+garten). En el equipamiento, también una lista (ausstattung[]=balkon&ausstattung[]=garten) significa “todos”.
• Rangos mediante von-{slug} y bis-{slug}, por ejemplo von-kaufpreis=200000&bis-kaufpreis=500000 o von-zimmer=3. Qué rangos existen y hasta dónde llegan lo indica site.search.ranges. Los rangos se aplican igual que en la búsqueda de su sitio web; un precio de compra de 0 (a consultar) no queda excluido, igual que allí.
• objekt-id: número de objeto o su comienzo.
• center y radius (km) para la búsqueda por radio (a partir de PLUS, con la búsqueda por radio activada); radius es opcional. Un filtro ort se ignora entonces, como en el sitio web. En radius, la respuesta indica la dirección encontrada o el error si no se pudo determinar el lugar.
• bounds=sur,oeste,norte,este para el área visible del mapa en grados decimales.
• order con una clave de site.search.orders; sin indicarlo se aplica la ordenación predeterminada de su sitio web.
• facets=1 añade en facets, por categoría, los términos del resultado con su número, los más frecuentes primero, para contadores junto a los filtros.
• Además page, per_page, fields, status y locale como en /properties.

Además de los inmuebles, la respuesta contiene en applied los filtros tal como la interfaz los ha entendido, de modo que un front end pueda restablecer a partir de ellos el estado de su formulario. Se aplican las mismas reglas de visibilidad que para el listado de inmuebles.

Sugerencias de direcciones para la búsqueda por radio

Si en WP-ImmoMakler → Integraciones → Servicios de geolocalización hay configurado un proveedor para el autocompletado de direcciones, site.search.places describe cómo un front end obtiene sugerencias mientras un visitante escribe en el campo de la búsqueda por radio; sin proveedor, places es null. El proceso es el mismo que en el formulario de búsqueda de su sitio web, y la clave del proveedor permanece en su servidor:

1. GET a places.token_url devuelve un token válido durante 15 minutos y, en proxy_url, la dirección del proxy Fast-API, que responde sin WordPress; proxy_url está vacío si el proxy está desactivado o el proveedor no es Google.
2. Cada entrada se envía como POST con el cuerpo JSON { "q": "Hambu", "session": "…", "languageCode": "de" } y la cabecera X-ImmoMakler-Sign: <token> a proxy_url o, como alternativa, a places.suggest_url. La respuesta es { "suggestions": [ { "label": "Hamburgo, Alemania", "placeId": "…" } ] }.
3. El front end pasa el label elegido a /search como center.

Ambos endpoints figuran también en el documento OpenAPI y en llms.txt, con su propio espacio de nombres immomakler/v1 como servidor. sessions indica si el proveedor factura por secuencia de escritura; en ese caso, un front end utiliza el mismo valor aleatorio de session para una secuencia de entradas y empieza una nueva tras una selección o una pausa de tres minutos. min_length, max_results y debounce_ms son los valores de su sitio web. Llame a los endpoints desde el navegador, no desde un servidor: los límites (90 solicitudes por minuto y visitante en el proxy, 600 por hora que no se respondan desde la caché) se aplican por visitante. El proxy acepta solicitudes desde la dirección de su front end y los orígenes permitidos; adopta un cambio en estos ajustes con el siguiente guardado.

GET /properties/{objektnr_extern}/similar

Inmuebles similares, tal como su sitio web los muestra debajo de un inmueble: mismo tipo de inmueble y de comercialización en las proximidades, ampliando el criterio paso a paso hasta que algo coincide, en orden aleatorio. count limita el número (predeterminado: su ajuste, como máximo 12). Las unidades del mismo proyecto de obra nueva quedan fuera si su sitio web las muestra en su propia tabla.

GET /properties/{objektnr_extern}/units

Las unidades de un proyecto de obra nueva, tal como las muestra la tabla “Otras unidades en este proyecto”: todas las unidades por número de objeto, también las vendidas y alquiladas que el listado de inmuebles ya no incluye. Para un inmueble que no es un proyecto de obra nueva, la interfaz responde con 404.

GET /taxonomies

Todas las categorías (tipo de inmueble, tipo de comercialización, tipo de uso, localidad, país, equipamiento, estado) con sus términos: term_id, slug, name, parent, count, description y source_slug, el slug del término independiente del idioma. Con hide_empty=false aparecen también los términos sin inmuebles. El recuento incluye todos los inmuebles de un término, también los que el listado de inmuebles oculta.

GET /contacts y GET /contacts/{post_id}

Las personas de contacto publicadas con nombre, descripción, retrato, los campos de contacto de su configuración y el número de sus inmuebles.

GET /content/pages y GET /content/pages/{ruta}

Las páginas publicadas de su sitio web, sin las páginas de plantilla de WP-ImmoMakler. El listado indica de cada página la ruta jerárquica (sobre-nosotros/equipo), la página superior, el orden, la plantilla de página, si es la página de inicio y su dirección en el front end. La consulta individual por ruta entrega la página como estructura de bloques: cada bloque lleva su nombre (core/paragraph, immomakler/single-data, …), sus atributos, su HTML interno, sus bloques secundarios y, en rendered, el HTML que WordPress emitiría para él. Los bloques de WP-ImmoMakler no tienen rendered; un front end los representa a partir de los datos del inmueble. Además se incluyen content_html, todo el contenido como un único fragmento HTML, y seo con el título y la descripción de Yoast SEO o Rank Math, siempre que estén rellenados allí. Los enlaces a su sitio web WordPress apuntan en ambas versiones ya al front end; las imágenes y los documentos permanecen en WordPress.

GET /content/posts y GET /content/posts/{slug}

Las entradas publicadas, las más recientes primero, con categorías, etiquetas, extracto e imagen destacada; admite modified_since. La consulta individual entrega la misma estructura de bloques que en las páginas.

GET /spam/token, POST /enquiries y POST /widerruf

Las rutas de formularios: el token para la protección antispam, las solicitudes de contacto y los desistimientos desde un front end propio. Solo aceptan solicitudes de los orígenes permitidos o con la API key, y nunca se almacenan en caché. La página Formularios a través de la interfaz headless describe la estructura de los documentos, los códigos de error y la interacción con la protección antispam; site.forms indica los campos, los campos obligatorios y los textos de consentimiento de sus formularios.

Webhook

La interfaz notifica por sí misma a su front end los cambios en sus inmuebles; la página Webhook, enlaces y redirección describe la estructura, la firma y el reintento del mensaje.

Menús y branding en /site

site.menus contiene las tres ubicaciones de menú que WP-ImmoMakler registra para su front end y que usted asigna en el backend de su sitio web (wp-admin) en Apariencia → Menús: primary (navegación principal), footer y legal (aviso legal, política de privacidad). Cada entrada lleva el título, la dirección guardada en WordPress, en frontend_url la dirección en el front end, el destino, las clases CSS, el tipo de destino y sus subentradas.

site.branding entrega las directrices de diseño de las secciones Branding y Starter de Astro de los ajustes headless: la plantilla de diseño (preset), el nombre y el eslogan del sitio web, el logotipo y la miniatura predeterminada con todos los tamaños de imagen, el color primario y el de acento como valores hexadecimales, la combinación tipográfica (sans, serif-headlines, humanist, system) y el redondeo de las esquinas (none, small, medium, large). Un front end escribe estos valores en sus design tokens, de modo que usted cambia el aspecto en WordPress sin tocar el front end.

Estructura de un inmueble

La forma completa (fields=full) de un inmueble, abreviada:

{
  "objektnr_extern": "A-1234",
  "openimmo_obid": "7f3c…",
  "post_id": 4711,
  "slug": "wohnung-kaufen-in-hamburg-a-1234",
  "language": "de",
  "published_gmt": "2026-09-01T10:00:00+00:00",
  "modified_gmt": "2026-10-10T08:15:00+00:00",
  "title": "3-Zimmer-Wohnung in Hamburg-Altona, 85 m²",
  "object_title": "Helle Stadtwohnung mit Blick aufs Wasser",
  "subtitle": "Hamburg-Altona · Wohnung · Kauf",
  "excerpt": "…",
  "status": {
    "terms": [ { "slug": "offen", "name": "offen" } ],
    "is_open": true,
    "is_reserved": false,
    "is_reference": false,
    "archived": false,
    "is_project": false,
    "is_project_unit": false,
    "is_hidden_project": false,
    "project_id": null,
    "public_since": "2026-09-01T10:00:00+00:00"
  },
  "marketing": { "vermarktungsart": "kauf", "nutzungsart": "wohnen", "objektart": [ "wohnung" ] },
  "taxonomies": { "immomakler_object_type": [ { "term_id": 12, "slug": "wohnung", "name": "Wohnung", "parent": 0, "source_slug": "wohnung" } ] },
  "address": { "street": "Elbchaussee", "house_number": "1", "zip": "22763", "city": "Hamburg", "district": "Altona", "state": "Hamburg", "country": "DEU", "country_name": "Deutschland" },
  "geo": { "lat": 53.55, "lng": 9.93, "exact": true, "radius_m": null },
  "fields": {
    "property": [ { "key": "rooms", "source_key": "anzahl_zimmer", "label": "Zimmer", "value": "3", "text": "3 Zimmer", "raw": 3 } ],
    "areas": [ { "key": "living_area", "source_key": "wohnflaeche", "label": "Wohnfläche ca.", "value": "85 m²", "text": "Wohnfläche ca. 85 m²", "raw": 85 } ],
    "prices": [ { "key": "purchase_price", "source_key": "kaufpreis", "label": "Kaufpreis", "value": "350.000 €", "text": "Kaufpreis 350.000 €", "raw": 350000 } ],
    "epass": []
  },
  "descriptions": {
    "objektbeschreibung": { "label": "Beschreibung", "html": "<p>…</p>", "text": "…" }
  },
  "media": {
    "featured": { "id": 99, "alt": "", "title": "Wohnzimmer", "mime": "image/jpeg", "sizes": { "immomakler-archive-thumb": { "url": "…", "width": 400, "height": 267 }, "full": { "url": "…", "width": 2000, "height": 1333 } } },
    "images_count": 12,
    "floorplans_count": 1,
    "images": [],
    "floorplans": [],
    "downloads": [ { "id": 101, "title": "Exposé", "url": "…", "filename": "expose.pdf", "is_pdf": true, "is_floorplan": false } ],
    "links": [],
    "videos": [ { "type": "embed", "url": "https://www.youtube.com/watch?v=…", "embeddable": true } ],
    "virtual_tours": []
  },
  "contact": { "post_id": 7, "name": "Erika Mustermann", "slug": "erika-mustermann", "wp_url": "…", "photo": { "…": "…" }, "fields": [ { "key": "kontaktperson_fullname", "label": "Ansprechpartner", "value": "Erika Mustermann" } ] },
  "seo": { "title": "…", "description": "…", "canonical": "https://ihr-frontend.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/", "og_image_url": "…" },
  "json_ld": [ { "@context": "https://schema.org", "@type": [ "Product" ] } ],
  "links": {
    "frontend_url": "https://ihr-frontend.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/",
    "wp_url": "https://ihre-wordpress-adresse.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/",
    "archive_frontend_url": "https://ihr-frontend.de/immobilien/",
    "og_image_url": "…/og-image/1/",
    "pdf_url": "…?pdf",
    "qr_url": "…?qrcode"
  }
}

seo contiene el título SEO y la descripción del inmueble, tal como WP-ImmoMakler los generó durante la importación o como los redactaron los textos de IA; si ha introducido para el inmueble un título o una descripción propios en Yoast SEO o Rank Math, estos tienen prioridad. Las plantillas con marcadores de posición como %%title%% quedan en manos del plugin SEO y aquí no se tienen en cuenta.

Cada campo de datos lleva un key en inglés, igual en todos los sitios web, y en source_key el nombre que usan WordPress y OpenImmo. Además incluye la denominación (label) y el texto de visualización (value) en el idioma del sitio web, ambos reunidos en una expresión (text) como en la forma de texto de las etiquetas de Elementor, por ejemplo “3,5 habitaciones” o “2 plazas de aparcamiento”, así como el valor sin formato (raw) como número o cadena de texto. Si un texto de visualización contiene HTML, por ejemplo un enlace, html entrega además la versión sin modificar. La forma abreviada (fields=summary) sustituye los grupos property, areas, prices y epass por archive y archive_prices, es decir, los campos de la vista de lista, y omite descriptions, json_ld y las listas de imágenes, documentos y vídeos.

Coordenadas y dirección

Si el propietario no ha autorizado la dirección, street y house_number quedan vacíos y geo.exact es false. En ese caso, represente la posición como una zona, no como un punto; geo.radius_m indica el radio si su software CRM lo ha transmitido.

Descripción legible por máquina

La interfaz se describe a sí misma. Ambos endpoints son siempre públicos, incluso si exige la clave de API para las solicitudes de lectura, porque no emiten datos de inmuebles.

GET /openapi.json

Un documento OpenAPI 3.1 con todos los endpoints, parámetros, esquemas de respuesta y los dos métodos de autenticación. Herramientas de desarrollo como Postman, Insomnia o generadores de clientes tipados lo leen directamente; los parámetros proceden de las rutas registradas, de modo que el documento se mantiene al día con cada ampliación de la interfaz. En webhooks describe los mensajes que su sitio web envía al front-end, con cabeceras, firma y estructura; la introducción indica los códigos de error y la regla para los formularios que un servidor reenvía.

GET /llms.txt y GET /llms-full.txt

Una descripción breve en formato de texto según la convención llms.txt: finalidad de la interfaz, URL base, autenticación, la regla de identificar los inmuebles mediante el número de objeto, los códigos de error, el webhook y la lista de endpoints con enlaces. La variante llms-full.txt añade a cada endpoint los parámetros y los campos de la respuesta.

Para constructores de sitios web con IA

Las herramientas con IA que generan código a partir de una descripción se las arreglan con estos dos archivos sin más explicaciones:

• Lovable, Bolt, v0, Replit: indique en el prompt la dirección de llms.txt o openapi.json, por ejemplo “Crea un listado de inmuebles con la API en https://su-direccion-wordpress.es/wp-json/immomakler-headless/v1/llms.txt”. Las solicitudes de lectura funcionan directamente desde el navegador, ya que WordPress habilita la API REST para todos los orígenes.
• Base44: guarde la dirección de openapi.json como integración OpenAPI personalizada. Si exige la clave de API para las solicitudes de lectura, guárdela allí como secreto; Base44 llama entonces a la interfaz desde una función de backend.

El código generado debería identificar siempre los inmuebles mediante objektnr_extern y usar los enlaces de links.frontend_url; ambas cosas figuran así en llms.txt.

Códigos de error

Estado HTTP	Código	Significado
401	headless_unauthorized	Falta la clave de API o es incorrecta, aunque se exige para las solicitudes de lectura.
404	headless_not_found	El inmueble o la persona de contacto no existe o no se muestra públicamente.
404	rest_no_route	La interfaz no está activada.
400	headless_invalid_modified_since	El parámetro modified_since no es una fecha válida.
403	headless_forbidden	Se llamó a una ruta de formulario sin proceder de un origen permitido ni usar la API key.
422	headless_validation_failed	Faltan campos obligatorios o no son válidos; data.errors los indica.
422	headless_unknown_property	Un número de objeto de properties no corresponde a ningún inmueble publicado.
422	headless_spam_rejected	El envío fue rechazado como spam.
429	headless_rate_limited	Demasiadas solicitudes en esta hora.
502	headless_delivery_failed	La solicitud está guardada, pero no pudo entregarse a todos los destinatarios.

Filtros para desarrolladores

• immomakler_headless_frontend_url modifica una URL que la interfaz emite hacia el front end. Parámetros: la URL, el ID de WordPress del inmueble (0 para el listado de inmuebles) y el tipo (property o archive).
• immomakler_headless_property modifica el documento JSON de un inmueble antes de emitirlo y almacenarlo en caché. Parámetros: el documento, el ID de WordPress y la forma (summary o full).
• immomakler_headless_presets determina qué plantillas de diseño ofrece la sección Starter de Astro para su selección. Parámetro: un array con el slug y la denominación de la plantilla.
• immomakler_headless_webhook_payload modifica el mensaje del webhook antes de firmarlo y enviarlo. Parámetros: el mensaje como array y el nombre del evento (properties.changed o ping).
• immomakler_contact_property_url cambia la dirección de un inmueble en el correo de una solicitud de contacto. Con la interfaz activada y una dirección de front end configurada, apunta al front end. Parámetros: la URL y el ID de WordPress del inmueble.

También puede interesarle

• Modo headless con un front end propio
• Taxonomías y categorías
• Hooks de filtro y de acción
• Realizar ajustes de forma compatible con actualizaciones