DiseñosEnglish

Escribir propiedades

Una clave con properties:write crea, edita y archiva tus propiedades, y les agrega fotos. También las lee, como properties:read. Dásela al sistema donde viven tus propiedades —un CRM inmobiliario, un back office, un feed— para que letsrealty lo siga sin que nadie las vuelva a escribir.

Las escrituras siguen las mismas reglas que la consola: mientras tu suscripción esté en solo lectura responden 402, y una cuenta suspendida responde 503.

Crear, editar y archivar

  • POST /v1/properties — crea una propiedad. Solo title es obligatorio; la respuesta es 201 con la propiedad.
  • PATCH /v1/properties/{property_id} — cambia una propiedad. Solo cambian los campos que envías; la respuesta es 200 con la propiedad.
  • DELETE /v1/properties/{property_id} — archiva una propiedad: sale de tu sitio web y de las listas predeterminadas, conserva su slug y su historial de precios, y responde 204. Nunca se borra nada definitivamente.
curl https://api.letsrealty.io/v1/properties \
  -H "Authorization: Bearer $LETSREALTY_API_KEY" \
  -H "Idempotency-Key: crm-listing-4412" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Casa Tamarindo",
    "description": "Tres habitaciones, piscina y vista a la bahía.",
    "internal_ref": "CASA-TAM-07",
    "listing_type": "sale",
    "price": "385000",
    "currency": "USD",
    "property_type": "house",
    "bedrooms": 3,
    "bathrooms": 2,
    "place_code": "CR-50309",
    "agent_email": "maria@agency.example"
  }'

El cuerpo acepta los campos de la propiedad tal como los describe Propiedades —title, description, listing_type, price, currency, rent_price, property_type, bedrooms, bathrooms, area, lot_area, parking_spaces, year_built, floor, hoa_fee, amenities, address, latitude, longitude, location_precision, is_featured, video_url, tour_url e internal_ref— más place_code, agent_id o agent_email, highlights y ai_enrichment, que se explican más abajo. Envía los precios como texto, por ejemplo "385000".

Un internal_ref que ya tiene otra propiedad es un 409. Todas las escrituras aceptan un Idempotency-Key, así que un reintento después de un timeout nunca crea una propiedad dos veces; consulta Límites de uso e idempotencia.

Sincronizar por tu propia referencia

PUT /v1/properties/by-ref/{internal_ref} es la única llamada que necesita un proceso de sincronización. Encuentra la propiedad por tu referencia:

  • Ninguna la tiene todavía: se crea la propiedad con ese internal_ref y la respuesta es 201.
  • Una la tiene: esa propiedad se actualiza con los campos que envía el cuerpo, con las reglas de PATCH, y la respuesta es 200.

El cuerpo acepta los mismos campos que una creación, así que title siempre es obligatorio. Un internal_ref en el cuerpo distinto del de la ruta es un 422.

Una sincronización nocturna envía cada propiedad de tu sistema, una línea por propiedad con su referencia y su JSON:

while read -r ref body; do
  curl -X PUT "https://api.letsrealty.io/v1/properties/by-ref/$ref" \
    -H "Authorization: Bearer $LETSREALTY_API_KEY" \
    -H "Idempotency-Key: nightly-2026-10-04-$ref" \
    -H "Content-Type: application/json" \
    -d "$body"
done < listings.tsv

Guarda el id que devuelve cada respuesta. Para retirar una propiedad que ya no vendes, archívala por ese id con DELETE /v1/properties/{property_id}. Poner la fecha en el Idempotency-Key hace que repetir la misma noche reproduzca sus respuestas, mientras que la noche siguiente vuelve a escribir.

Una propiedad que creó tu clave tiene origin: "api", y toda propiedad que escribe una clave muestra el nombre de la clave en la consola. La edición de una clave sobre una propiedad importada cuenta como una edición manual, así que una importación posterior la respeta.

Lugar y Agente

  • place_code — el Lugar de la propiedad, uno de los códigos que lista GET /v1/places. Una propiedad con Lugar aparece en tu sitio web; una sin Lugar queda fuera, con needs_location: true.
  • agent_id o agent_email — el Agente al que se atribuye la propiedad. Envía uno o ninguno: los dos, o un Agente que no tienes, es un 422.

Fotos desde una URL

POST /v1/properties/{property_id}/images:import agrega una foto que tu sistema ya aloja:

curl https://api.letsrealty.io/v1/properties/6f1c…/images:import \
  -H "Authorization: Bearer $LETSREALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://media.example.com/casa-tamarindo/pool.jpg", "is_primary": true }'

La respuesta es 202 con una importación cuyo status es pending. letsrealty descarga la foto en segundo plano, y la importación pasa a ready, con la image de la galería, o a failed, con un failure_reason. Consúltala con GET /v1/properties/{property_id}/images:import/{import_id}, o espera el evento property.updated de la propiedad.

  • La URL debe ser https en un servidor público. Se siguen hasta tres redirecciones, cada una a un servidor público.
  • El archivo debe ser una imagen JPEG, PNG, WebP, AVIF o GIF de 20 MB como máximo.
  • La misma URL en la misma propiedad devuelve la importación existente con 200, así que reenviar toda tu galería no agrega nada dos veces. Una importación fallida se vuelve a intentar.
  • is_primary la convierte en la portada; sort_order la ubica en la galería.

Para subir archivos, pide una subida con POST /v1/properties/{property_id}/images/uploads (el content_type y el size_bytes), haz PUT del archivo a la url devuelta con los headers devueltos y confírmala con POST /v1/properties/{property_id}/images y el object_key. PATCH /v1/properties/{property_id}/images/{image_id} cambia el sort_order o el is_primary de una foto, y DELETE /v1/properties/{property_id}/images/{image_id} la elimina.

La IA y tus textos

Una propiedad en tu sitio web recibe el Enriquecimiento con IA —traducciones, puntos destacados y una descripción SEO— igual que una creada en la consola. Una creación, o una edición que pone la propiedad en tu sitio web o cambia allí su título o descripción, la pone en cola, dentro de tu cupo de IA. Envía "ai_enrichment": false para omitirlo.

  • Sin ?lang=, title y description son el texto propio de la propiedad, y highlights (hasta 6) son sus puntos destacados en ese idioma.
  • Con ?lang= y un Idioma del Sitio activado, title, description y highlights son el texto de ese idioma.
  • El texto que envías es tuyo: las ejecuciones de IA no lo tocan, como pasa con la edición de un Agente en la consola.

La respuesta vuelve en el idioma en que escribiste.

Eventos

Los endpoints de webhook y GET /v1/events avisan a tus otros sistemas de cada cambio en una propiedad, venga de la consola, de una importación o de una clave, así que la sincronización puede ir en los dos sentidos:

  • property.created y property.updated (con changed_fields; images cuando cambia la galería).
  • property.went_live — la propiedad apareció en tu sitio web.
  • property.price_changed — con previous_price y previous_currency.
  • property.archived.

Requieren properties:read. Consulta Webhooks.