Formularios a través de la interfaz headless

PLUS

Un front end propio muestra sus formularios por sí mismo. Lo que un visitante introduce en ellos lo recibe WP-ImmoMakler a través de la interfaz headless y lo trata exactamente igual que una entrada en el formulario de contacto de su sitio WordPress: los mismos campos obligatorios, la misma protección antispam, el mismo camino hacia la persona de contacto, hacia su software CRM y hacia la lista de solicitudes en el back end.

Qué establece el sitio web

GET /site describe en forms cómo están construidos sus formularios, para que un front end los reproduzca en lugar de inventarlos:

forms.enquiry.fields: todos los campos del formulario de contacto con su etiqueta y las indicaciones de si el campo se muestra (enabled) y si debe rellenarse (mandatory), tal como lo ha definido en el back end de su sitio web (wp-admin) en WP-ImmoMakler → Ajustes → Formulario de contacto.
forms.enquiry.texts: los textos de los consentimientos (condiciones generales, privacidad, información sobre el desistimiento, aviso de comisión, casilla personalizada) y de los campos de selección “Se desea visita” y “Ya soy propietario de un inmueble” como HTML.
forms.enquiry.withdrawal_always: si la información sobre el desistimiento debe confirmarse en cada inmueble o solo en los inmuebles con comisión.
forms.withdrawal: los campos y consentimientos del formulario de desistimiento, los textos de introducción y de confirmación y la dirección de la política de privacidad.
forms.spam: cómo se maneja la protección antispam, véase más abajo.

Protección antispam

Cada formulario de su sitio web lleva un token firmado, un campo invisible y, si ha configurado uno, un captcha. Un front end obtiene estos datos cuando muestra un formulario:

GET /wp-json/immomakler-headless/v1/spam/token

La respuesta indica en token el token, en honeypot_field el nombre del campo invisible, en min_fill_seconds cuántos segundos deben transcurrir como mínimo entre la visualización y el envío, y en captcha el proveedor, el nombre del campo y la key pública del captcha (en ALTCHA, en challenge_url la dirección de la que el widget obtiene su tarea, en algorithm el algoritmo de la tarea y, si es ARGON2ID, en worker_url el worker de Argon2id; en Friendly Captcha en la región de la UE, en endpoint el valor para data-api-endpoint o data-puzzle-endpoint del widget). Al enviar, el token se devuelve en spam.token, el campo invisible vacío en spam.honeypot y la solución del captcha en spam.captcha.

Si su sitio web usa ALTCHA, WP-ImmoMakler emite en cada servidor con la extensión PHP Sodium tareas con el algoritmo Argon2id. El paquete ALTCHA por sí solo resuelve únicamente PBKDF2 y SHA; su front end debe registrar el worker de Argon2id en el widget antes de resolver una tarea; de lo contrario, cada tarea falla con “Unsupported algorithm”. Con el paquete npm altcha y un bundler como Vite:

import 'altcha';
import Argon2idWorker from 'altcha/workers/argon2id?worker';

globalThis.$altcha.algorithms.set('ARGON2ID', () => new Argon2idWorker());

Sin bundler, registre el worker desde worker_url. Un worker debe proceder de la misma dirección que la página, por lo que se carga mediante un blob que descarga el script: new Worker(URL.createObjectURL(new Blob(['importScripts(' + JSON.stringify(workerUrl) + ')']))). El widget recibe challenge_url en su atributo challenge; la ruta responde a solicitudes desde cualquier dirección.

Si un remitente sospechoso se rechaza o la solicitud solo se entrega marcada lo determina, igual que en el sitio web, el ajuste en WP-ImmoMakler → Ajustes → Protección antispam. También se aplica el límite de solicitudes por hora y visitante.

Si no es el navegador del visitante, sino el servidor de su front end, quien envía los formularios a la interfaz, todos los visitantes parecen uno solo para WP-ImmoMakler. En ese caso, introduzca las direcciones IP de esos servidores como direcciones de proxy de confianza en el back end de su sitio web (wp-admin) en WP-ImmoMakler → Integraciones → Headless; WP-ImmoMakler lee entonces la dirección del visitante del encabezado X-Forwarded-For que su servidor envía.

Si su front end se ejecuta en un proveedor como Cloudflare, Vercel o Netlify, los servidores de este no tienen una dirección fija. En ese caso, introduzca los rangos de direcciones que publica el proveedor, en notación CIDR, uno por línea, por ejemplo 173.245.48.0/20 o 2400:cb00::/32; los de Cloudflare se encuentran en cloudflare.com/ips. Un visitante no puede falsificar el encabezado en su favor: WP-ImmoMakler toma la última dirección del encabezado que no pertenece a un rango de confianza, que es la que registró el propio proveedor.

Quién puede enviar

Las rutas de formularios solo aceptan solicitudes de los orígenes permitidos, es decir, desde un navegador en la dirección de su front end o en una de las direcciones introducidas en Orígenes permitidos (Origins), o con la API key en el encabezado X-ImmoMakler-Key cuando envía el servidor de su front end. Todo lo demás se responde con 403 y el código de error headless_forbidden.

Enviar una solicitud de contacto

POST /wp-json/immomakler-headless/v1/enquiries
Content-Type: application/json

{
  "properties": ["WP1235"],
  "fields": {
    "salutation": "Frau",
    "first_name": "Erika",
    "last_name": "Muster",
    "email": "erika@example.com",
    "phone": "+49 40 123456",
    "message": "Ich interessiere mich für die Wohnung.",
    "appointment_requested": true
  },
  "consents": { "privacy": true, "withdrawal": true },
  "spam": { "token": "…", "honeypot": "" },
  "origin": "https://www.ihre-domain.de/immobilien/wohnung-in-hamburg/"
}

properties indica los números de objeto de los inmuebles consultados; sin properties se trata de un contacto general a la dirección configurada en los ajustes. fields contiene las entradas con los nombres de campo en inglés de forms.enquiry.fields (key; source_key indica el nombre del campo en los ajustes de WordPress), consents los consentimientos (terms, privacy, withdrawal, commission, custom) y origin la página desde la que llegó la solicitud; se menciona en el correo.

Si todo va bien, la interfaz responde con 201 e indica el número de la entrada guardada en WP-ImmoMakler → Solicitudes de contacto (enquiry_id), así como si la solicitud se entregó marcada como sospechosa (spam_suspected). Los enlaces a los inmuebles en el correo apuntan a su front end.

Si faltan campos obligatorios o una dirección de correo no es válida, responde con 422 y el código de error headless_validation_failed; data.errors enumera los campos afectados (email, privacy, …). Un número de objeto desconocido se notifica como headless_unknown_property, una solicitud rechazada como spam como headless_spam_rejected y demasiadas solicitudes en una hora como 429 con headless_rate_limited. Si no se pudo entregar un correo, responde con 502 y headless_delivery_failed; la solicitud queda entonces igualmente guardada en WP-ImmoMakler → Solicitudes de contacto.

Enviar un desistimiento

POST /wp-json/immomakler-headless/v1/withdrawal
Content-Type: application/json

{
  "fields": {
    "first_name": "Erika",
    "last_name": "Muster",
    "email": "erika@example.com",
    "contract_identification": "Maklervertrag vom 1. Oktober 2026"
  },
  "consents": { "withdrawal": true, "privacy": true },
  "property": "WP1235",
  "source_url": "https://www.ihre-domain.de/widerruf/",
  "spam": { "token": "…", "honeypot": "" }
}

Todos los campos y ambos consentimientos son obligatorios. WP-ImmoMakler envía el desistimiento a la dirección configurada, lo guarda en el archivo y envía al visitante un acuse de recibo, siempre que el envío no resulte sospechoso de spam. La respuesta 201 indica en submitted_at el momento de la recepción. Los datos que faltan se notifican como 422 con headless_validation_failed, y data.errors indica los campos (contract_identification, withdrawal, privacy, …).

Crear una alerta de búsqueda

Una alerta de búsqueda guarda una búsqueda para una dirección de correo; WP-ImmoMakler envía después al suscriptor por correo los nuevos resultados, una vez que ha activado la alerta mediante el enlace del correo de confirmación (Double Opt-In). Si su sitio web ofrece alertas de búsqueda lo indica /site en forms.search_agent.active; allí figuran también los textos de los dos consentimientos (texts.contact, texts.privacy), el texto de teaser y del formulario, si se ofrece la opción de correos de solo texto (plaintext_option) y, en page_url, la página de su front end a la que apuntan los enlaces de los correos.

POST /wp-json/immomakler-headless/v1/search-agents
Content-Type: application/json

{
  "email": "erika@example.com",
  "criteria": { "marketing": "kauf", "type": "wohnung", "location": "hamburg", "price_max": 500000, "rooms_min": 3 },
  "consents": { "contact": true, "privacy": true },
  "notification": { "plaintext": false },
  "spam": { "token": "…", "honeypot": "" }
}

criteria acepta los mismos parámetros que /search (los nombres del formulario de búsqueda de su sitio web valen como alias); un objeto vacío guarda “todos los inmuebles”. Ambos consentimientos son obligatorios. La respuesta (201) indica en status el valor pending y en message el aviso que muestra al visitante; 422 señala consentimientos que faltan, una dirección no válida o criterios poco plausibles, y 429 demasiadas alertas de búsqueda en una hora.

El correo de confirmación lleva a page_url con ?callback=confirm_searchagent&confirm=<hash>, y el enlace de baja de cada notificación a page_url con ?callback=delete_searchagent&delete=<hash>. La página de su front end lee la alerta de búsqueda con GET /search-agents/<hash> (estado, dirección, criterios como pares etiqueta/valor, enlace a la lista de resultados) y actúa solo cuando el visitante hace clic: POST /search-agents/<hash>/confirm activa la alerta, DELETE /search-agents/<hash> la elimina. No actúe nunca ya al abrir el enlace: las comprobaciones de seguridad de los servicios de correo abren cada enlace de un correo. La ruta de la página la define en el back end de su sitio web (wp-admin) en WP-ImmoMakler → Integraciones → Headless como Ruta de la página de la alerta de búsqueda; sin un front end configurado, los enlaces llevan como hasta ahora a la lista de inmuebles de WordPress.