Anuncios y sincronización

Sincroniza anuncios y edita sus campos de contenido compatibles.

Operaciones REST y permisos de las claves

Inicia la sincronización y reproduce los cambios de anuncios

Para una sincronización completa de anuncios, conserva sin cambios el syncCursor de la primera página de sincronización inicial hasta aplicar todas sus páginas a un conjunto de datos temporal. Sigue el nextCursor inicial por todas las páginas; solo entonces inicia /api/v1/landlord/listings/changes desde ese primer cursor conservado. Aplica cada página de cambios de forma atómica con su nextCursor; continúa mientras hasMore=true. Sustituye la caché anterior solo cuando terminen correctamente la sincronización inicial completa y la primera reproducción de cambios. Los webhooks activan ese lector de cambios; las consultas periódicas recuperan las notificaciones perdidas.

Edita el nombre o el texto de una unidad en un anuncio existente

Usa un ID de unidad devuelto por el feed de anuncios de la empresa. Con write:properties, envía PATCH /api/v1/landlord/listings/{unitId}/content con un Idempotency-Key y este cuerpo JSON:

{"name":"Bright two-room apartment","otherFacts":"Two rooms and a kitchen with a balcony."}

La respuesta es la misma proyección {"listing": ...} que la consulta del detalle del anuncio. name y otherFacts son los únicos campos aceptados; ambos son cadenas opcionales que se recortan, y debe proporcionarse al menos uno. Sus límites respectivos son 200 y 10000 caracteres, con un máximo de 64 KiB para el cuerpo de la solicitud. Los campos omitidos no cambian. Un name vacío elimina el nombre opcional de la unidad. Un otherFacts vacío borra el texto de la unidad, de modo que la description pública recurre al campo heredado facts de la unidad y después a la descripción del inmueble. No borra esas fuentes alternativas. Se rechazan null y los campos desconocidos.

Consulta el resultado y aplica los eventos de cambios de anuncios del modo habitual. Las repeticiones siguen requiriendo el permiso y la titularidad actuales de la clave; una denegación posterior no revierte una operación correcta anterior. Si claves de operación distintas modifican el mismo campo, prevalece la última escritura; listingVersion no es aquí una condición previa de escritura.

Esta operación de contenido no permite acceder a medios, publicación, disponibilidad ni campos privados de inquilinos. Siguen aplicándose sus límites de administración independientes. La escritura de contenido, la auditoría semántica obligatoria y el resultado de repetición se confirman atómicamente. La auditoría registra los ID de clave y operación y los nombres de los campos modificados, sin guardar tu credencial ni el texto del anuncio en ese registro.

Sube imágenes y publica anuncios mediante la API

Activa una delegación explícita para la clave exacta de integración en Configuración → API y agentes. El administrador vuelve a iniciar sesión con contraseña, passkey o un método de eID habilitado en Homito y concede media y/o publication con vencimiento. La activación usa la pertenencia real a la empresa y los requisitos actuales de publicación de esa misma persona. createdBy, un permiso comodín, una clave de reemplazo o un ID de persona enviado por el cliente no sustituyen la delegación. Se consulta o revoca mediante el control de sesión de la aplicación web /api/v1/settings/api-keys/{keyId}/listing-grant, no mediante el origen externo de la API.

Cada operación requiere write:properties, la capacidad delegada correspondiente y un Idempotency-Key distinto. Tras perder una respuesta, conserva el cuerpo y la clave idénticos; la repetición comprueba la autorización actual antes de devolver el recibo.

1. Envía POST /api/v1/landlord/listings/{unitId}/media/uploads con {"images":[{"bytes":12345,"sha256":"<64 lowercase hexadecimal characters>","mimeType":"image/png"}]}. Calcula tamaño y SHA-256 a partir de los bytes originales reales. Límite: diez imágenes por reserva y cinco MiB por imagen. La reserva vence a los quince minutos; la URL PUT dura como máximo cinco minutos.
2. Envía esos bytes exactos mediante PUT a upload.url, con todos los valores devueltos en upload.headers y sin la cabecera Authorization de Homito. Usa carga HTTP binaria, rechaza redirecciones y comprueba el resultado HTTP antes de completar. El objeto privado temporal todavía no es una imagen del anuncio. Repetir la reserva no prolonga sus URL; después del vencimiento crea otra reserva con una clave de operación nueva.
3. Envía POST /api/v1/landlord/listings/{unitId}/media/uploads/{uploadId}/complete con {} o {"setAsFront":true}. El servidor comprueba longitud, SHA-256, MIME, descodificación y límites de píxeles; escribe otra imagen pública inmutable y confirma atómicamente galería, auditoría, diario, intención duradera de webhook y recibo. Consulta el anuncio resultante. GIF y WebP animado pueden conservar metadatos incrustados; no se promete eliminarlos todos.
4. Envía PATCH /api/v1/landlord/listings/{unitId}/publication con {"isPublic":true,"allocationMethod":"individual_assessment","creditCheckMode":"without_credit_check"} para publicar, o {"isPublic":false} para retirar. El método también puede ser first_come. Se mantienen mantenimiento, bloqueo de empresa, reglas de convocatoria y requisitos actuales de publicación de la persona delegante. Retirar conserva su exención existente de confianza de publicación, pero exige clave, delegación, persona, pertenencia y titularidad vigentes. No se aceptan slugs arbitrarios, consultas de crédito ni campos privados de inquilinos.

Procesa listing.changed/listing.unpublished mediante el feed ordenado de cambios. Las cargas temporales abandonadas y los objetos derivados no adjuntos tienen limpieza programada duradera. Un recibo confirma la modificación y la intención de entrega; comprueba aparte la entrega real del webhook.

Cuando una distribución MCP exacta y aprobada los anuncie, homito.reserve_listing_media, homito.complete_listing_media y homito.set_listing_publication llaman a las mismas operaciones REST con reservation, completion y publication. También exigen unitId e idempotencyKey; completar exige uploadId. Activa el control local habitual de escritura; apruebas cada llamada en tu cliente MCP antes de que se envíe. El PUT binario sigue siendo una carga HTTP separada con las instrucciones devueltas.

Gestiona imágenes existentes con PATCH /api/v1/landlord/listings/{unitId}/media: {"removeUrls":["<exact URL from the current gallery>"],"frontImageUrl":"<exact retained gallery URL>"}. Puedes enviar cada campo por separado; frontImageUrl:null borra la selección explícita de portada. La operación solo elimina o selecciona imágenes existentes, nunca importa una URL nueva. Las imágenes gestionadas retiradas pueden pasar a limpieza física protegida por la base de datos. La herramienta MCP aprobada correspondiente es homito.update_listing_gallery, con un objeto gallery y los controles habituales de escritura.

Continúa las consultas de forma segura

Sigue nextCursor hasta que sea null, manteniendo la misma operación de listado y los mismos filtros. Utiliza los cursores solo con la misma empresa y operación de listado. Las previsualizaciones de importación, los trabajos y su historial pertenecen a la clave API que los creó, incluido el acceso mediante ID de trabajo. Una respuesta correcta del /health público, por sí sola, no verifica tu clave ni el acceso a la empresa.

Mantén los datos privados fuera de las cachés públicas

Mantén los datos personales, los recibos y las capacidades de carga fuera de las cachés públicas de anuncios. Las consultas de inquilinos y solicitudes devuelven deliberadamente proyecciones operativas mínimas; no deduzcas campos privados ausentes ni conclusiones de evaluación. Distingue los valores null o desconocidos de cero o de un resultado completado.

Usa la versión publicada del contrato

Usa la versión de API y el ciclo de vida indicados en la referencia, los esquemas de cada operación y cualquier versión de formulario o recurso requerida al actualizar una integración. Conserva las versiones opacas sin cambios y fija una versión MCP aprobada. Los nombres de evento proceden del mismo catálogo que la API; el orden de llegada y una versión de producto no sustituyen la consulta actual del recurso.