DiseñosEnglish

Claves publicables

Una clave publicable permite que una página web lea tus propiedades publicadas, Agentes, Ubicaciones y amenidades directamente desde el navegador, y envíe una Consulta, sin un servidor propio. Los widgets para sitios web usan una. A diferencia de una API Key, no es un secreto: cualquiera puede verla en el código de tu página, así que solo abre lo que tu sitio web ya muestra, y solo a los sitios que indiques.

Crear una

Un Tenant Admin la crea en el Admin Console en Integraciones → API keys → Claves publicables, e indica los orígenes permitidos: los sitios web que pueden usarla, como https://www.tuagencia.com.

  • Un origen es https:// más el host, sin ruta: https://www.tuagencia.com, no https://www.tuagencia.com/propiedades.
  • https://*.tuagencia.com permite cualquier subdominio de tuagencia.com. Agrega https://tuagencia.com por separado si también usas el dominio sin subdominio.
  • También se permite http://localhost (en cualquier puerto), para probarla en tu propia computadora.

La clave empieza con lr_pk_… y la consola la muestra siempre que la necesites. Puedes editar sus orígenes cuando quieras; revócala para desactivarla para siempre.

Llamar a la API

Envía la clave como ?key= en lugar de un encabezado Authorization, y el origen de tu página como &origin=, desde una página en un origen permitido:

const url = new URL("https://api.letsrealty.io/v1/site/properties");
url.searchParams.set("key", "lr_pk_1a2b3c4d_xxxx");
url.searchParams.set("origin", window.location.origin);
url.searchParams.set("listing", "sale");
url.searchParams.set("limit", "12");
url.searchParams.set("locale", "es");
const res = await fetch(url);
const { items, total } = await res.json();
  • Desde un navegador, cada lectura necesita origin, con exactamente el origen de la página (window.location.origin, que el navegador también envía como su encabezado Origin). Omitirlo, o enviar el de otro sitio, es un 403. Los widgets lo hacen por ti.
  • Una solicitud desde un navegador en un origen que la clave no incluye es un 403 y no recibe encabezados CORS, así que el navegador no la lee.
  • Un origen permitido recibe Access-Control-Allow-Origin con su propio valor.
  • Una solicitud sin encabezado Origin, desde un script o curl, también se atiende y puede omitir origin: la clave solo abre lo que tu sitio web ya muestra. Si envía origin, debe ser uno permitido.
  • Una clave desconocida o revocada es un 404, y una cuenta suspendida un 503.

Nunca pongas una API Key secreta (lr_live_…) en una URL. Una enviada como ?key= se rechaza con un 400 y queda marcada en la consola como expuesta; rótala de inmediato.

Qué puedes leer

  • GET /v1/site/properties — una página de propiedades publicadas, con los filtros listing, location, type, min_price, max_price, beds, amenities, q, featured y sort, y limit y offset.
  • GET /v1/site/properties/by-slug/{slug} — una propiedad por su slug. Un slug retirado la sigue encontrando, con is_canonical: false.
  • GET /v1/site/properties/by-id/{property_id} — una propiedad por id: available con su detalle, o unavailable cuando ya no está en el mercado.
  • GET /v1/site/properties/by-slug/{slug}/similar y GET /v1/site/properties/{property_id}/similar — hasta 3 o 6 propiedades parecidas.
  • GET /v1/site/locations — las Áreas, Lugares y tipos de propiedad con propiedades publicadas, con su conteo, y GET /v1/site/locations/{slug} para uno de ellos.
  • GET /v1/site/agents y GET /v1/site/agents/by-slug/{slug} — los perfiles públicos de tus Agentes activos.
  • GET /v1/site/amenities — el vocabulario de amenidades, con etiquetas en locale.
  • GET /v1/theme — con lo que se estilizan los widgets: los colores, las fuentes, el estilo de esquinas y el logo de tu marca, tus Idiomas del Sitio, la dirección de tu sitio web y si se muestra "Con la tecnología de letsrealty".

Responden exactamente lo que muestra tu sitio web: solo propiedades publicadas, las coordenadas de una ubicación aproximada redondeadas para que un mapa muestre una zona y no un punto, y nunca tu referencia interna. Pasa locale para recibir el texto de una propiedad en uno de tus Idiomas del Sitio. Las estructuras completas están en la referencia.

Actualidad y caché

Cada GET exitoso con una clave publicable se envía con Cache-Control: public, s-maxage=60, stale-while-revalidate=300 y se guarda en caché en nuestro borde, según la URL completa. Un cambio que hagas en una propiedad se ve en alrededor de un minuto; no hace falta purgar nada. Dos visitantes que piden la misma URL comparten una respuesta en caché, así que mantén estables tus parámetros. Como origin forma parte de la URL, cada uno de tus sitios web tiene su propia respuesta en caché, con CORS solo para ese sitio: una página de otro sitio que copie tu URL recibe una respuesta que su navegador se niega a leer.

Enviar una Consulta

POST /v1/site/leads?key=…&origin=… envía una Consulta, que llega a tu CRM como una de tu sitio web: el mismo emparejamiento de Leads, Responsable del Lead, Calificación de Leads y notificación por correo. Debe llevar un token de Turnstile del widget Turnstile de Cloudflare en tu página, en turnstile; sin uno válido es un 403.

const leads = new URL("https://api.letsrealty.io/v1/site/leads");
leads.searchParams.set("key", "lr_pk_1a2b3c4d_xxxx");
leads.searchParams.set("origin", window.location.origin);
await fetch(leads, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Lucía Vargas",
    email: "lucia@example.com",
    message: "¿Sigue disponible?",
    property_id: "2f0c9d4e-7a51-4c3b-9b1e-0d6a8f3e5c21",
    turnstile: turnstileToken,
  }),
});

Indica una propiedad con property_id o un Agente con agent_id (como mucho uno), o ninguno para una consulta general. El origen del Lead es Widget, con la página desde la que se envió según el Referer del navegador (entre sitios, los navegadores solo envían el origen de tu sitio salvo que la solicitud use referrerPolicy: "no-referrer-when-downgrade"), y la Consulta dice "vía widget" en la consola. POST /v1/site/properties/{slug}/view cuenta una vista del detalle de una propiedad. En estos POST, origin es opcional, pero si lo envías también debe ser el origen de tu página.

Límites

Los mismos en todos los planes:

  • 120 solicitudes por minuto desde la dirección IP de cada visitante, y 5 Consultas por minuto;
  • 3.000 solicitudes por minuto para todas tus claves publicables juntas.

Las respuestas servidas desde la caché del borde no cuentan. Un presupuesto agotado es un 429 con Retry-After, y los encabezados RateLimit funcionan como con las API Keys (ver Límites de uso).