Cómo construir un plugin de WordPress para la API de Propstack

Un sitio web inmobiliario depende de sus anuncios. Si administra sus propiedades en Propstack pero su sitio público funciona con WordPress, se enfrenta a una elección tediosa: copiar cada anuncio a mano o construir un puente entre ambos.

En este artículo explico cómo construí ese puente: un plugin de WordPress que trae los anuncios directamente desde la API de Propstack y los muestra en su sitio, de forma automática y bajo demanda.

El objetivo

El plugin tiene que hacer bien cuatro cosas:

1. Autenticarse en la API de Propstack y obtener los datos de las propiedades.
2. Guardar esos datos en caché para que el sitio siga siendo rápido y la API no se sature.
3. Mostrar los anuncios con plantillas limpias que se puedan adaptar desde el tema.
4. Permitir que una persona sin perfil técnico lo configure y lo use sin tocar código.

Todo lo demás son detalles. Veamos cada pieza.

Cómo hablar con la API

Propstack ofrece una API REST (versión 2) en https://api.propstack.de/v2. Toda la integración gira en torno a una sola clase, PropstackAPI, que encapsula cada solicitud a ese endpoint. Al centralizar el acceso a la API en una clase, la autenticación, el manejo de errores y la caché quedan reunidos en un solo lugar del código.

Propstack v2 se autentica mediante un encabezado HTTP, X-Api-Key, de modo que la clave no viaja en la URL. Eso es más seguro (las claves no terminan en los logs del servidor ni en el historial del navegador) y más limpio:

PHP

$args = array(
    'timeout' => 30,
    'headers' => array(
        'X-Api-Key'  => $this->api_key,
        'Accept'     => 'application/json',
        'User-Agent' => $this->get_user_agent(),
    ),
    'sslverify' => true,
);

$response = wp_remote_get($final_url, $args);

Observe que el código usa la función propia de WordPress, wp_remote_get(), para HTTP. Es deliberado: a diferencia de una llamada directa a cURL, la API HTTP integrada hereda los filtros, la configuración de proxy y el manejo de errores de WordPress, y devuelve objetos WP_Error ordenados que usted puede comprobar con is_wp_error(). Así obtiene comunicaciones de red confiables sin esfuerzo adicional.

Caché: no sature la API

Llamar a una API externa en cada carga de página es lento para sus visitantes y un desperdicio para los servidores de Propstack. El plugin lo resuelve con los transients de WordPress, la caché clave-valor nativa.

Cada respuesta de la API se guarda bajo una clave de transient con un tiempo de expiración configurable. El valor predeterminado es de cinco minutos y está disponible como ajuste en el panel de administración, para que los responsables del sitio equilibren actualidad y velocidad. Un mínimo razonable de 60 segundos evita que alguien lo ponga en cero por accidente y le haga un DDoS a la API:

PHP

// Convierte el ajuste de minutos a segundos, nunca por debajo de 60.
$this->cache_duration = max(60, intval($cache_setting) * 60);

Los visitantes recurrentes reciben resultados instantáneos desde la caché; la API solo se consulta cuando la caché expira.

Mostrar anuncios con shortcodes

La forma más sencilla de que los usuarios de WordPress coloquen contenido dinámico en cualquier lugar es el shortcode. El plugin registra varios:

• [propstack_listings], una cuadrícula paginada de propiedades
• [propstack_property], la vista de detalle de una propiedad
• [propstack_search], un formulario de búsqueda con resultados en vivo vía AJAX

El responsable del sitio solo tiene que insertar un shortcode en cualquier página o entrada. La cuadrícula de anuncios acepta un conjunto amplio de atributos para filtros y diseño:

[propstack_listings limit="9" columns="3" city="Berlin" min_price="200000" max_price="800000"]

Internamente, cada atributo se sanea y se limita a rangos seguros antes de llegar a la API: columns se fuerza entre 1 y 4, limit entre 1 y 50, los precios se convierten a float, etcétera. Nunca confíe en la entrada de un shortcode.

Para una sola propiedad:

[propstack_property id="123" show_gallery="true" show_contact="true"]

Plantillas adaptables desde el tema

La salida se genera con archivos de plantilla PHP (una plantilla para la cuadrícula de propiedades, otra para la propiedad individual y un formulario de búsqueda), separados de la lógica que obtiene los datos. Esta separación importa: permite que el tema activo sobrescriba el marcado sin editar el plugin.

El plugin busca primero en el directorio del tema y, si no encuentra nada, recurre a sus propias plantillas incluidas:

1. your-theme/propstack/property-card.php
2. your-theme/propstack-property-card.php
3. plugin/templates/property-card.php

Los diseñadores pueden rediseñar por completo los anuncios desde el tema, y sus cambios se conservan al actualizar el plugin.

Un “cargar más” sin recargar la página

Paginar recargando la página completa se siente anticuado. El plugin registra un endpoint AJAX, habilitado tanto para usuarios con sesión iniciada como para visitantes anónimos, que obtiene la siguiente página de propiedades y la agrega a la cuadrícula:

PHP

add_action('wp_ajax_load_more_properties', array($this, 'load_more_properties'));
add_action('wp_ajax_nopriv_load_more_properties', array($this, 'load_more_properties'));

Cada solicitud AJAX está protegida con un nonce de WordPress contra la falsificación de solicitudes entre sitios.

Que lo pueda usar quien no programa

Una buena integración es invisible para quien administra el sitio. El área de administración incluye:

• Una página de configuración en Ajustes con el campo de la clave de API, la duración de la caché, el símbolo de moneda y los valores predeterminados de las imágenes.
• Un botón “Test Connection” que hace una llamada AJAX a Propstack, para que usted confirme al instante que su clave funciona, sin adivinar.
• Avisos en el panel de administración que le recuerdan agregar su clave de API si falta.
• Pestañas de ayuda contextual que explican la configuración y el uso de los shortcodes justo donde los necesita.

Ser un buen ciudadano de WordPress

Los detalles finales distinguen un plugin de aficionado de uno que se puede mantener:

• Verificación de requisitos al activarlo. El plugin comprueba PHP 7.4+ y WordPress 5.0+ y, si no se cumplen, se niega a activarse de forma controlada, sin lanzar errores fatales.
• Listo para traducción. Cada texto visible para el usuario pasa por las funciones de i18n de WordPress con un text domain, para que el plugin pueda localizarse.
• Desinstalación limpia. Un archivo uninstall.php dedicado elimina todas las opciones, los transients en caché y los metadatos de usuario cuando se borra el plugin, sin dejar restos huérfanos en su base de datos.

Conclusiones

Esta arquitectura se puede aplicar a casi cualquier integración de una API de terceros en WordPress:

1. Encapsule la API en una clase para que la autenticación y la caché vivan en un solo lugar.
2. Apóyese en las API nativas de WordPress: wp_remote_get() para HTTP, transients para la caché, shortcodes para la ubicación.
3. Separe los datos de la presentación con plantillas que se puedan sobrescribir.
4. Exponga la configuración en una página de ajustes y limpie todo al desinstalar.

Si hace bien esas cuatro cosas, el resto de verdad son solo plantillas. El resultado es un sitio inmobiliario alimentado por Propstack que se actualiza solo: sus anuncios viven en un solo lugar y su sitio web simplemente los refleja.