Homlity SDK · Smart Inmobiliario

SDK oficial de PHP para integrar el inventario inmobiliario y el CRM de Homlity en cualquier sitio o aplicación.

Sitio principal · Portal de desarrolladores · Packagist · GitHub

Tabla de contenido

1. ¿Qué es este SDK?
2. ¿Para qué sirve?
3. Requisitos
4. Instalación
5. Credenciales
6. Inicio rápido
7. Referencia de la API del SDK
8. Modelos de datos
9. Catálogos y códigos
10. Ejemplos completos
11. Integración con frameworks
12. Buenas prácticas
13. Limitaciones y advertencias
14. Endpoints REST subyacentes
15. Solución de problemas
16. Pruebas
17. Versionado y changelog
18. Soporte

¿Qué es este SDK?

homlity/sdk-smarthome es una librería PHP sin frameworks que envuelve la API REST del integrador inmobiliario de Homlity (https://api.smart-home.com.co). En lugar de armar URLs, manejar cURL y navegar arrays asociativos en inglés, trabajas con objetos PHP con métodos en español:

El SDK resuelve tres cosas por ti:

¿Para qué sirve?

Casos de uso reales que este SDK habilita:

• Portal inmobiliario propio. Publicar en tu sitio web el inventario que la inmobiliaria administra en Homlity, siempre sincronizado, sin duplicar la carga de datos.
• Ficha de inmueble. Página de detalle con galería de fotos, video, tour virtual 360°, características, mapa (latitud/longitud) y datos del asesor.
• Buscador y filtros. Construir filtros por ciudad, localidad, barrio, tipo de inmueble, gestión (venta/arriendo), precio, alcobas o baños usando los catálogos que expone la API.
• Captación de leads hacia el CRM. Enviar los formularios de contacto de tu web directamente al CRM de Homlity, asociados al inmueble específico que generó el interés.
• Landing pages y micrositios de proyectos que consumen un subconjunto del inventario.
• Sindicación / feeds hacia portales de terceros o alimentación de un índice de búsqueda.

Requisitos

Instalación

⚠️ Nota de versión importante

La última etiqueta publicada en Packagist es v2.2.1, que expone una API distinta y anterior (SDKSmartInmoBuilder::build() + SmartHomeFacade). Toda esta documentación describe la API actual de la rama main (SDKSmartHomeBuilder), que aún no tiene etiqueta.

Mientras se publica la versión estable, instala la rama de desarrollo:

O fijando el commit para builds reproducibles:

Para el mantenedor: etiquetar v3.0.0 desde main publica esta API como versión estable y permite composer require homlity/sdk-smarthome:^3.0.

Instalación sin Composer

Necesitarás instalar también curl/curl manualmente.

Namespace

El paquete se llama homlity/sdk-smarthome, pero el namespace PHP sigue siendo Codwelt\SDK\SmartHome\ por compatibilidad hacia atrás. No lo confundas:

Credenciales

El SDK necesita hasta tres identificadores, que entrega el equipo de Homlity al habilitar la integración:

• Company Code identifica a la inmobiliaria dentro de la plataforma.
• Project Code identifica el proyecto o bolsa de inventario que quieres exponer.
• Project ID es el token largo del CRM al que se asocian los leads.

Solicítalos en el portal de desarrolladores de Homlity.

Seguridad: aunque el Company Code y el Project Code viajan en la URL y solo dan acceso de lectura al inventario que ya es público, nunca expongas el projectId en JavaScript del lado del cliente. Las llamadas del SDK deben ejecutarse siempre en el servidor.

Guárdalas fuera del código:

Inicio rápido

Referencia de la API del SDK

SDKSmartHomeBuilder

Clase de entrada. Codwelt\SDK\SmartHome\SDKSmartHomeBuilder.

__construct(string $endpoint = "https://api.smart-home.com.co")

Crea el cliente. Solo necesitas pasar $endpoint si Homlity te asignó un entorno alterno (staging, on-premise):

No incluyas la barra final: el SDK concatena las rutas directamente.

setCompanyCode(string $companyCode): void

Define el código de la inmobiliaria. Obligatorio para todas las consultas de inventario.

setProjectCode(string $projectCode): void

Define el código del proyecto. Obligatorio para todas las consultas de inventario.

setProjectId(string $projectId): void

Define el identificador del proyecto en el CRM. Solo se usa en agregarLead(); si no vas a enviar leads puedes omitirlo.

obtenerPropiedades(): InmueblePreview[]

Devuelve todos los inmuebles del proyecto como un array de InmueblePreview.

• Devuelve [] (array vacío) si la petición falla o no hay inventario. No lanza excepciones.
• La respuesta no está paginada desde el cliente: la API devuelve hasta 10.000 registros por llamada. Si tu inventario es grande, cachea el resultado.

obtenerPropiedad(string $unitCode): ?InmuebleDetail

Devuelve el detalle de un inmueble a partir de su código (getCodigo() del listado).

• El parámetro es el code del inmueble (ej. "20230022"), no el moduleId.
• Devuelve null solo si la petición HTTP falla (red caída, endpoint inalcanzable).
• 🔴 Un código inexistente NO devuelve null. La API responde 200 con units: null y el SDK entrega un InmuebleDetail vacío: el objeto existe, pero su array interno es null, así que cada getter emite el aviso Trying to access array offset on value of type null y devuelve null. Por eso comprobar === null no basta: valida además un campo obligatorio como getCodigo(), tal como en el ejemplo de arriba.
• El propio obtenerPropiedad() emite ese mismo aviso desde dentro del SDK antes de devolverte el objeto. Si quieres logs limpios, llámalo como @$sdk->obtenerPropiedad($codigo).

obtenerUbicaciones(): ?Ubicaciones

Devuelve el árbol geográfico del inventario (países, ciudades, localidades, barrios y zonas), con el conteo de inmuebles de cada nodo — ideal para construir filtros.

obtenerTipoPropiedades(): ?TipoPropiedad[]

Devuelve los tipos de inmueble presentes en el inventario, con su conteo.

⚠️ Este método devuelve null (no []) cuando el proyecto no tiene tipos, y en ese caso además emite el aviso foreach() argument must be of type array|object, null given desde dentro del propio SDK. Usa siempre ?? [] antes de iterar.

agregarLead(array $datos): ?string

Registra un contacto en el CRM de Homlity y lo asocia a un inmueble.

Claves del array $datos — todas son obligatorias:

🔴 Dos detalles que causan la mayoría de los errores:

1. La clave se escribe commentario (con doble m), tal como la espera el SDK. Si la omites, PHP emitirá un warning de clave indefinida y el comentario viajará vacío.
2. codigo debe ser el moduleId (un UUID como 35f98252-6db1-43d6-bd6b-18752b883c41), no el código visible del inmueble.

Además, setProjectId() debe haberse llamado antes; de lo contrario el lead llegará sin proyecto asociado.

Devuelve el cuerpo crudo de la respuesta del CRM (string) o null si la petición falló. Comprueba siempre !== null antes de mostrar un mensaje de éxito al usuario.

Modelos de datos

Todos los modelos viven en Codwelt\SDK\SmartHome\InfraStructure\ y son objetos de solo lectura construidos a partir de la respuesta JSON.

InmueblePreview / InmuebleDetail

InmuebleDetail extiende InmueblePreview sin añadir métodos: ambos exponen exactamente la misma interfaz. La diferencia está en el origen de los datos, no en la clase.

Identificación

Áreas

Precios

Gestión y tipo

Distribución

Ubicación

Multimedia y relaciones

⚠️ En inventarios reales, images y features llegan null con frecuencia (en el inventario de demostración: 3 de 15 y 4 de 15 respectivamente). Como los métodos hacen foreach directo sobre el campo, PHP 8 emite el aviso foreach() argument must be of type array|object, null given y el método devuelve [].

No es fatal por sí solo, pero sí es ruido en los logs — y en Laravel, Symfony o cualquier proyecto con un set_error_handler que convierte los avisos en excepciones, sí se convierte en una ErrorException. Usa accesores seguros que cubran ambos escenarios:

Fotos

Representa una pieza multimedia: foto, video o tour virtual.

Caracteristicas

Asesor

Datos de contacto del comercial responsable del inmueble.

Ubicaciones

Contenedor del árbol geográfico devuelto por obtenerUbicaciones().

⚠️ getZonas() envuelve las zonas en la clase Paises, por lo que getCodigo() leerá countryId y no zoneId. En los proyectos de prueba zones viene vacío, así que rara vez se nota; evita depender de este método hasta que se corrija.

Paises

Ciudades

Localidades

Barrios

TipoPropiedad

Catálogos y códigos

Gestión (unitCategory)

Usa siempre getGestion() para mostrar el texto: la API ya envía la descripción oficial.

Tipos de inmueble (unitType)

Los códigos son estables, pero el catálogo disponible varía por proyecto. Obtén siempre el listado real con obtenerTipoPropiedades(). Valores observados:

Tipo de multimedia (mediaType)

Ejemplos completos

En la carpeta examples/ encontrarás estos scripts listos para ejecutar.

1. Listado con tarjetas

2. Filtrar en memoria

La API devuelve el inventario completo, así que los filtros se aplican en PHP:

3. Ficha de inmueble con galería

4. Construir filtros desde los catálogos

El atributo data-ciudad de cada barrio permite encadenar los selects en JavaScript sin volver a llamar a la API.

5. Formulario de contacto que envía al CRM

6. Sitemap y feed JSON

Integración con frameworks

Laravel

Registra el SDK como singleton en un ServiceProvider:

Cache::remember serializa los objetos del SDK sin problema: solo contienen arrays.

WordPress

PHP plano con caché en archivo

Buenas prácticas

1. Cachea siempre. obtenerPropiedades() trae el inventario completo en cada llamada. Un TTL de 10–30 minutos reduce drásticamente la latencia y la carga sobre la API.
2. Nunca llames al SDK desde el navegador. Las credenciales, y sobre todo el projectId, deben quedarse en el servidor.
3. Sirve caché rancia ante fallos. Como el SDK devuelve [] en vez de lanzar una excepción, una caída de la API vaciaría tu portal. Conserva la última respuesta buena.
4. Escapa toda salida. Las descripciones y títulos vienen tal como los cargó la inmobiliaria: usa htmlspecialchars() / esc_html().
5. Valida antes de renderizar. null, [] y campos ausentes son escenarios normales, no excepcionales.
6. Registra los fallos. Un agregarLead() que devuelve null es un lead perdido: déjalo en el log y, si es crítico, guarda el formulario en tu base de datos para reintentarlo.
7. Precarga las imágenes con loading="lazy". Las galerías suelen traer más de 20 fotos en alta resolución.
8. Usa getModuleId() para leads y getCodigo() para URLs. Confundirlos es el error más frecuente.

Limitaciones y advertencias (importante)

Estas son características actuales del SDK que conviene conocer antes de llevarlo a producción:

Envoltorio recomendado

Endpoints REST subyacentes

Si trabajas en otro lenguaje (Node, Python, Go…), estos son los endpoints que el SDK consume. Base: https://api.smart-home.com.co

Todas las peticiones envían Accept: application/json y aceptan Content-Encoding: gzip.

Respuesta de getUnits

Los campos agent, listingSites, featuredProperty, status e index existen en la respuesta pero el SDK aún no los expone mediante getters.

Respuesta de getUnitLocation

Respuesta de getUnitType

Cuerpo de POST /api/SmartInmobiliario

Se envía como application/x-www-form-urlencoded.

Solución de problemas

Pruebas

La suite actual (tests/IndexTestCase.php) es un esqueleto mínimo y no cubre la API vigente: construye SDKSmartHomeBuilder pasando el companyCode al constructor, cuando el constructor espera un endpoint. Trátala como código heredado, no como referencia de uso.

Para probar contra la API real sin tocar el CRM, usa únicamente los métodos de lectura y las credenciales de demostración incluidas en index.php.

Versionado y changelog

El proyecto sigue SemVer y Keep a Changelog. Consulta CHANGELOG.md.

Soporte

Otros SDK de Homlity

_{Hecho por Homlity · homlity.com}