Para un sitio inmobiliario que ya carga todo en Tokko, el widget alcanza si alcanza con mostrar propiedades. Cuando la inmobiliaria necesita filtros propios, un mapa y un diseño alineado a su marca, conviene un buscador propio que consuma la API de Tokko desde el servidor. Así lo resolvimos en DURBANO: PHP, caché de respuestas por 15 minutos y un mapa con Leaflet.js.

El punto de partida: el inventario ya vivía en Tokko

DURBANO es una inmobiliaria con sede en Buenos Aires que opera en venta y en alquiler. Su CRM es Tokko: listings, imágenes, precios y coordenadas geográficas viven ahí. El desafío no era cargar datos en el sitio, sino traerlos en tiempo real sin duplicar la carga operativa. Si el equipo tiene que cargar cada propiedad dos veces, el sitio queda desactualizado más temprano que tarde.

Tokko ofrece un widget embebible para mostrar propiedades en sitios externos. Es la opción rápida, pero tiene límites concretos: diseño fijo sin personalización, filtros limitados, sin mapa propio y un rendimiento que queda fuera del control de quien desarrolla el sitio. DURBANO pedía otra cosa: filtros avanzados, mapa con pins y una interfaz de su identidad visual. Podés ver el resultado en el caso de estudio de DURBANO.

Widget o buscador propio: cuándo conviene cada uno

No siempre hace falta construir. La decisión depende de qué tan importante es la búsqueda para el negocio de la inmobiliaria.

Criterio Widget de Tokko Buscador propio con la API
Puesta en marcha Se embebe un fragmento de código Hay que diseñar, desarrollar y probar
Diseño Fijo, sin personalización Alineado a la identidad de la marca
Filtros Los que trae el widget Los que el negocio necesita
Mapa Sin mapa propio Mapa propio con pins y popups
Rendimiento Fuera de tu control Lo definís vos: caché, imágenes, carga de scripts
Mantenimiento Lo resuelve Tokko Lo asume quien desarrolla el sitio

Nuestro criterio: si el sitio es una vidriera con pocas propiedades, el widget es razonable. Si la búsqueda es el centro de la experiencia, o si la marca no admite una pieza ajena en medio del sitio, un buscador propio se justifica. En ese caso el costo extra es el mantenimiento, y conviene decidirlo con los ojos abiertos.

Arquitectura de la integración

La integración se organiza en capas. Cada una tiene una sola responsabilidad, y por eso el día que cambia algo (un campo de la API, un filtro nuevo, otra librería de mapa) se toca un solo lugar. 

Navegador
  └─ Formulario de filtros + listado + mapa (HTML, CSS, JS vanilla, Leaflet)
        │  query string con el estado de la búsqueda
        ▼
Servidor PHP
  ├─ 1. Validación de los parámetros recibidos
  ├─ 2. Caché de respuestas (15 minutos)
  │      ├─ hit  → devuelve lo guardado
  │      └─ miss → llama a la API de Tokko
  ├─ 3. Cliente de la API (API key en el header, paginación LimitOffset)
  ├─ 4. Normalización (tipología, operación, ubicación, precio, imágenes)
  └─ 5. Vistas (listado, detalle, datos para los pins)
        ▼
API de Tokko  →  CRM donde el equipo carga las propiedades

Autenticación y configuración

La API de Tokko se consume con una API key enviada en el header de cada request. Esa clave vive en la configuración del servidor (variables de entorno), nunca en el código fuente ni en el JavaScript que llega al navegador. Todas las llamadas salen del servidor: el visitante nunca ve la clave.

Normalización de datos

Los datos del CRM no están pensados para mostrarse tal cual. En DURBANO normalizamos tipología, operación, ubicación, precios e imágenes a un formato consistente para el frontend. La ventaja es que las vistas trabajan con una estructura estable: si mañana Tokko cambia cómo entrega un campo, se corrige la normalización y las páginas no se enteran.

Filtros y paginación

El formulario tiene cinco filtros: operación, tipo de propiedad, barrio, rango de precios y cantidad de dormitorios. Los parámetros se traducen directamente a la query string de la API, así que la lógica de filtrado queda en el servidor y la interfaz queda liviana. La paginación usa el esquema LimitOffset de la API. Todo parámetro que llega del visitante se valida antes de reenviarlo: la búsqueda es una entrada de usuario como cualquier otra.

Estrategia de caché de la API

Las respuestas de la API de Tokko se cachean en el servidor por 15 minutos. Esa decisión resuelve dos problemas a la vez: baja la latencia que percibe el visitante y evita superar los límites de rate de la API cuando hay mucho tráfico.

El plazo es un acuerdo entre frescura y carga. Para una inmobiliaria, un cambio en una ficha (precio, estado, fotos) puede tardar hasta un ciclo de caché en verse en el sitio. Es una demora que el equipo comercial entiende y acepta; a cambio, el sitio no depende de que la API responda rápido en cada visita. Y se mantiene el resultado buscado: cuando el equipo carga o modifica una propiedad en el CRM, el cambio aparece solo en el próximo ciclo, sin intervención técnica.

Este es un esquema mínimo de la idea, ilustrativo y simplificado. La clave de caché depende de los parámetros ya validados de la búsqueda: 

<?php
// Esquema ilustrativo, no es el código de producción.
const CACHE_TTL = 900; // 15 minutos

function buscar_propiedades_cacheado(array $filtros): array
{
    ksort($filtros); // mismos filtros, misma clave
    $clave = 'propiedades_' . hash('sha256', http_build_query($filtros));
    $archivo = sys_get_temp_dir() . '/' . $clave . '.json';

    if (is_file($archivo) && (time() - filemtime($archivo)) < CACHE_TTL) {
        $guardado = json_decode((string) file_get_contents($archivo), true);
        if (is_array($guardado)) {
            return $guardado;
        }
    }

    $propiedades = tokko_buscar($filtros); // llamada real + normalización
    file_put_contents($archivo, json_encode($propiedades), LOCK_EX);

    return $propiedades;
}

Dos detalles que importan en cualquier implementación: la clave tiene que salir de parámetros ya validados (si no, cualquiera puede llenar el caché de combinaciones absurdas) y la escritura tiene que ser segura ante pedidos simultáneos. Si la API falla, lo mejor es registrar el error y mostrar un mensaje claro, no una pantalla rota.

Decisiones de rendimiento del mapa

Elegimos Leaflet.js por dos motivos: es open source, sin costo de licencia, y es una librería más liviana que las alternativas comerciales. Cada propiedad expone coordenadas lat/lng desde Tokko, y con ellas se dibuja un pin por cada propiedad de la búsqueda activa. Al tocar un pin aparece un popup con precio, tipo de propiedad y un enlace al detalle.

  • Los pins salen de la búsqueda activa. El mapa muestra lo que el visitante filtró, no todo el inventario. Los datos de los pins son los mismos que ya están normalizados y cacheados para el listado.
  • Mapa colapsable en mobile. En pantallas chicas el mapa ocupa todo el ancho y se puede ocultar. Un mapa fijo ocupa la pantalla y bloquea el scroll, así que el visitante alterna entre mapa y lista.
  • Imágenes con carga diferida. Las fotos usan loading="lazy" nativo, de modo que el navegador no descarga lo que todavía no está en pantalla. Es un atributo estándar, documentado en MDN.
  • Una sola librería externa. El resto es PHP, HTML, CSS y JavaScript sin dependencias adicionales. Cada librería que se suma es peso para el visitante y trabajo de mantenimiento para vos.

Una advertencia sobre las coordenadas: el mapa depende de que las propiedades las tengan cargadas en Tokko. Si una ficha no tiene lat/lng, no hay pin. Conviene avisarle al equipo de la inmobiliaria que completar la ubicación es parte de cargar bien una propiedad.

Lecciones aprendidas

  1. La fuente de verdad es una sola. Todo lo que se pueda tomar del CRM se toma del CRM. En cuanto el sitio tiene su propia copia editable de las propiedades, aparece la doble carga que se quería evitar.
  2. Normalizar antes de mostrar. Los datos del CRM reflejan cómo trabaja el equipo comercial. La capa de normalización es el amortiguador entre eso y la interfaz.
  3. El caché es una decisión de negocio. Elegir cuánto tarda un cambio en verse en el sitio tiene que hablarse con la inmobiliaria, no solo con el equipo técnico.
  4. La clave de la API se cuida como una contraseña. Servidor, variables de entorno, nada en el código ni en el navegador.
  5. La calidad del dato define la calidad del sitio. Fotos, ubicación y descripciones completas en el CRM se traducen directo en un mejor sitio. Ninguna interfaz arregla una ficha incompleta.

Qué mirar antes de decidir

Antes de elegir entre widget y buscador propio, repasá esta lista:

  • ¿La búsqueda de propiedades es el centro del sitio o un complemento?
  • ¿Necesitás filtros que el widget no ofrece, o un mapa propio?
  • ¿La identidad visual admite una pieza que no podés modificar?
  • ¿Alguien se va a ocupar del mantenimiento de la integración después del lanzamiento?
  • ¿El equipo carga completas las fichas (fotos, ubicación, descripción)?
  • ¿Podés aceptar que un cambio en el CRM tarde un ciclo de caché en verse?

Si muchas respuestas apuntan a la búsqueda propia, también conviene pensar el sitio como plataforma. Los criterios generales para elegir tecnología están en PHP o WordPress para empresas, y el servicio de sitios y plataformas web describe cómo trabajamos. Para que las páginas de propiedades se encuentren en buscadores, sumá el trabajo de SEO técnico y GEO. Más casos en proyectos.

En resumen

Usá el widget de Tokko si necesitás mostrar propiedades rápido y el diseño no es prioridad. Pasá a un buscador propio cuando los filtros, el mapa y la identidad visual hacen a la propuesta de la inmobiliaria. En DURBANO, la combinación de API de Tokko, normalización, caché de 15 minutos, Leaflet y carga diferida de imágenes dio un sitio en producción con listings actualizados desde el CRM, búsqueda con filtros y mapa interactivo. La integración se puede replicar si el criterio de decisión es claro.

Preguntas frecuentes

¿Conviene usar el widget de Tokko o un buscador propio?

Si el sitio es una vidriera con pocas propiedades, el widget alcanza. Si la búsqueda es el centro de la experiencia o necesitás filtros, mapa y diseño propios, conviene un buscador que consuma la API de Tokko desde el servidor. Tiene un costo: el mantenimiento lo asume quien desarrolla el sitio.

¿Cómo se conecta un sitio web con Tokko?

Con la API REST de Tokko, autenticada con una API key que se guarda en el servidor y no en el navegador. El sitio consulta propiedades con los filtros del visitante, normaliza la respuesta a un formato propio y la muestra en listado, detalle y mapa.

¿Cada cuánto se actualizan las propiedades en el sitio?

Depende del plazo de caché que se acuerde. En DURBANO las respuestas de la API se cachean 15 minutos: cuando el equipo carga o modifica una propiedad en Tokko, el cambio aparece en el próximo ciclo, sin intervención técnica ni doble carga.

¿Por qué cachear las respuestas de la API de Tokko?

Por dos motivos: el visitante recibe la página más rápido porque no espera una llamada externa en cada visita, y se evita superar los límites de uso de la API en momentos de mucho tráfico. El plazo es un acuerdo entre frescura del dato y carga.

¿Qué mapa se puede usar en un sitio inmobiliario?

Leaflet.js es una opción open source, sin costo de licencia y liviana. Con las coordenadas lat/lng que cada propiedad tiene en Tokko se dibuja un pin por propiedad, con un popup de precio, tipo y enlace al detalle. Las propiedades sin ubicación cargada no aparecen.