SDK SIMI para PHP

Cliente PHP oficial mantenido por Homlity para consumir el API de SIMI (CRM inmobiliario) desde cualquier proyecto PHP, Laravel o WordPress.

🏠 homlity.com · 👩‍💻 Portal de desarrolladores · 📦 GitHub · 📝 Changelog

📘 ¿Prefieres leerlo como página web? El repositorio incluye una versión navegable con el mismo contenido en docs/index.html (autocontenida, lista para GitHub Pages). Los ejemplos ejecutables están en examples/.

Tabla de contenido

1. ¿Qué es este SDK y para qué sirve?
2. Requisitos
3. Instalación
4. El token de SIMI
5. Primeros pasos (Quickstart)
6. Arquitectura del SDK
7. Referencia del API (ApiFachada)
8. Filtros disponibles
9. Referencia de modelos
10. Servicios de aplicación
11. Paginación
12. Recetas y ejemplos completos
13. Integración con Laravel
14. Integración con WordPress
15. Rendimiento y caché
16. Manejo de errores
17. Advertencias y comportamientos a tener en cuenta
18. Pruebas
19. Versionado y contribución
20. Soporte
21. Licencia

1. ¿Qué es este SDK y para qué sirve?

SIMI es un CRM inmobiliario usado por inmobiliarias y constructoras (principalmente en Colombia) para administrar su inventario de inmuebles, sus asesores y sus sedes. SIMI expone ese inventario mediante un API HTTP público por inmobiliaria, autenticado con un token.

Ese API devuelve JSON "crudo", con nombres de campos inconsistentes entre endpoints (Codigo_Inmueble vs idInm, banios vs banos, Venta vs ValorVenta, precios con símbolos y puntos mezclados dentro de strings, etc.). Este SDK existe para que nunca tengas que tocar ese JSON.

Con el SDK obtienes:

Casos de uso típicos

• Portales inmobiliarios: listados con filtros, ficha de detalle, mapa, galería, video y fotos 360.
• Landing pages / home: carrusel de inmuebles destacados.
• Buscadores: selects encadenados departamento → ciudad → barrio, tipos de inmueble y gestiones.
• Página "Nuestro equipo": listado paginado de asesores con foto, celular y correo.
• Sincronizaciones / feeds: exportar inventario hacia portales externos u otros sistemas.
• Widgets y shortcodes de WordPress alimentados con inventario real.

2. Requisitos

3. Instalación

Vía Composer (recomendado)

El nombre del paquete en composer.json es homlity/sdk-simi y el repositorio es github.com/homlity/sdk-simi.

Migración desde codwelt/sdk-simi

El paquete se publicaba antes bajo el vendor codwelt. El vendor y el namespace ahora son homlity, y ese es un cambio incompatible hacia atrás: todo el código que use el SDK debe actualizar sus importaciones.

Un solo comando actualiza todas las referencias de tu proyecto:

Después ejecuta composer dump-autoload. Ninguna clase, método ni firma cambió: solo el namespace.

Nota sobre versiones. Cambiar el namespace rompe la compatibilidad, así que corresponde una versión mayor: v3.0.0. Publica ese tag antes de usar la restricción ^3.0; mientras no exista, apunta a dev-master.

Vía repositorio VCS

Si el paquete no está disponible en tu Packagist (por ejemplo, si trabajas contra un fork, una rama de desarrollo o un Packagist privado), agrégalo como repositorio VCS en el composer.json de tu proyecto:

Para fijar una versión exacta usa cualquiera de los tags publicados (v2.5.7, v2.5.6, …):

Autoload

El paquete usa PSR-4:

Basta con incluir el autoloader de Composer:

4. El token de SIMI

Todas las peticiones se autentican con un único token que entrega SIMI a cada inmobiliaria.

Formato

El SDK valida el token contra esta expresión regular antes de permitir cualquier llamada:

Es decir: entre 40 y 50 caracteres alfanuméricos, un guion, y un número (el identificador de la inmobiliaria/sede). Ejemplo con forma válida:

Si el token no cumple el formato, setTokenProvider() lanza:

Cómo se envía

Nunca lo publiques

El token da acceso completo al inventario de la inmobiliaria. No lo escribas en el código fuente ni lo subas al repositorio. Cárgalo desde variables de entorno; para eso existe la interfaz TokenServiceProviderRespository (ver §5).

5. Primeros pasos (Quickstart)

Paso 1 — Implementa tu proveedor de token

El SDK nunca recibe el token "a mano": recibe un objeto que sabe de dónde sacarlo. Así puedes leerlo de .env, de la base de datos, de un secreto de tu infraestructura o de la configuración multi-sitio.

Paso 2 — Construye el API

Atajo: si no necesitas el proveedor puedes instanciar la fachada directamente. Ojo: esta vía no valida el formato del token.

Paso 3 — Consulta inmuebles

Paso 4 — Ficha de detalle

6. Arquitectura del SDK

El paquete sigue una separación por capas al estilo de arquitectura hexagonal:

Flujo de una llamada

Por qué te importa esta separación

• Puedes tipar contra ApiFachadaRepository (la abstracción) y no contra la implementación concreta. Eso te permite inyectar un doble de prueba, un decorador con caché o un mock en tus tests sin tocar red.
• Los servicios de aplicación (Application/) reciben ApiFachadaRepository por constructor, así que funcionan igual con la fachada real o con la que tú decores.

7. Referencia del API (ApiFachada)

Todos los métodos pueden lanzar \Exception (URL inválida, filtro no permitido, parámetro requerido faltante).

getInmuebles(array $filtros = [])

Listado paginado con filtros. Es el método central del SDK.

• Los filtros con valor "vacío" ("", null, 0, []) se descartan antes de armar la URL.
• Si isSuccess() falla, devuelve ['inmuebles' => [], 'paginador' => null] — sin excepción.
• Valores por defecto: total = 30, limite = 1.

getDetalleInmueble($codigo)

Recibe el código público del inmueble (formato sede-consecutivo, p. ej. "503-4848"). Devuelve InmuebleDetail o null si el API respondió sin cuerpo útil.

Lanza excepción si $codigo está vacío: El codigo del inmueble es requerido para obtener el detalle del inmueble.

getInmueblesDestacados(array $filtros = [])

Solo acepta limite y total. Ideal para el home.

getDepartamentos() / getCiudades($id) / getBarrios($id)

Catálogo geográfico de la inmobiliaria (solo devuelve zonas donde hay inventario). Los tres modelos implementan JsonSerializable, así que puedes devolverlos directamente desde un endpoint JSON propio:

getTiposInmueble()

Tipos con conteo de inventario, útil para menús tipo "Apartamentos (124)".

getGestionesInmueble()

Las gestiones/operaciones configuradas (Venta, Arriendo, Arriendo/Venta…). El id() es el valor que se pasa en el filtro tipOper.

getAsesores(array $filtros = [])

Filtros permitidos: limite (página), cantidad (por página, por defecto 30) y asesor (id puntual).

getEstadoInmueble(int $idEstado, $idGestion)

Usa un API distinto (https://api.simicrm.app/crm/, cabecera token, versión v3). Devuelve un array plano de InmueblePreview filtrando por estado y gestión. El SDK acepta las tres formas de respuesta que usa ese endpoint (data, Inmuebles o array plano).

Si tu token no está habilitado para el API v3 del CRM, este método devolverá un array vacío aunque los demás métodos funcionen correctamente.

8. Filtros disponibles

getInmuebles()

Cualquier clave fuera de esta lista lanza Exception: Filtro (x) no esta permitido en APISIMI.

getInmueblesDestacados()

limite, total.

getAsesores()

limite, cantidad, asesor.

9. Referencia de modelos

InmueblePreview

Objeto liviano que devuelve getInmuebles(), getInmueblesDestacados() y getEstadoInmueble().

InmuebleDetail extends InmueblePreview

Devuelto por getDetalleInmueble(). Sobrescribe los getters porque el endpoint de detalle usa otros nombres de campo, y agrega:

Características

CaracteristicaInterna, CaracteristicaExterna y CaracteristicaAlrededores comparten la misma forma:

Asesores

AsesorUsuario (listado) y AsesorDetalleInmueble (ficha) extienden AsesorRepository:

Catálogos

Departamento, Ciudad, Barrio, GestionInmueble y TipoInmueble exponen id() y nombre() (TipoInmueble además totalInmuebles()). Todos implementan JsonSerializable.

10. Servicios de aplicación

ObtenedorInmueblesSimilaresService

Devuelve inmuebles parecidos a uno dado (misma zona, mismo tipo, misma gestión), excluyendo el original. Perfecto para el bloque "También te puede interesar" de la ficha.

obtener($detalle, $cantidad) pide $cantidad inmuebles al API y devuelve $cantidad - 1, porque reserva un espacio para descartar el inmueble original. Pide uno más de los que quieras mostrar.

ObtenedorUrlFichaInmuebleService

Construye la URL de la ficha técnica en SIMI para un inmueble.

PaginatorHTML

Paginador de propósito general que genera el HTML de la paginación (compatible con las clases de Bootstrap).

11. Paginación

getInmuebles() y getInmueblesDestacados() devuelven un PaginadorInmueblePreview:

getAsesores() devuelve un PaginadorAsesores con paginaActual(), total(), totalPorPagina(), numeroPaginaInicio() y numeroPaginaFin().

Recuerda: el paginador es null cuando la petición no fue exitosa. Verifica siempre antes de usarlo.

12. Recetas y ejemplos completos

En la carpeta examples/ encontrarás estos ejemplos como archivos PHP ejecutables.

Buscador con selects encadenados (JSON para tu frontend)

Listado con filtros desde $_GET (saneado)

Filtrar contra la lista blanca antes de llamar al SDK evita que un parámetro inventado en la URL provoque la excepción Filtro (x) no esta permitido en APISIMI.

Ficha completa con galería, mapa y similares

Precios: formateado vs. numérico

Útil para datos estructurados de SEO:

Exportar todo el inventario (paginando)

13. Integración con Laravel

1. Configuración

config/simi.php:

.env:

2. Proveedor de token

app/Services/Simi/TokenSimiProvider.php:

3. Service provider

app/Providers/SimiServiceProvider.php:

Se instancia ApiFachada directamente en lugar de usar ApiServiceProvider::build() para evitar el singleton estático del SDK (ver §17). Si quieres conservar la validación del formato del token, replícala o llama a setTokenProvider() una sola vez en el register().

4. Uso en un controlador

Ojo con el caché: los objetos del SDK son serializables porque solo guardan arrays, pero si prefieres cachear los datos crudos usa Request*/Response* directamente y guarda getBody().

14. Integración con WordPress

Un shortcode [simi_destacados total="6"] para mostrar inventario en cualquier página:

Guarda el token en wp-config.php, nunca en la base de datos ni en el tema:

15. Rendimiento y caché

El API de SIMI es la parte lenta de cualquier página que lo consuma. Cachea siempre.

Como los servicios del SDK dependen de la abstracción ApiFachadaRepository, puedes escribir un decorador con caché y seguir usando todo el resto del SDK sin cambios:

TTL sugeridos:

16. Manejo de errores

El SDK usa dos mecanismos distintos, y conviene tener claro cuál aplica:

Excepciones (\Exception)

Se lanzan antes de hacer la petición, por errores del programador o de configuración:

Respuestas vacías (sin excepción)

Si el API responde con error, no responde, o devuelve un cuerpo inesperado, no hay excepción: recibes listas vacías o null.

Patrón recomendado

17. Advertencias y comportamientos a tener en cuenta

Estas son particularidades reales del código. Conocerlas ahorra horas de depuración.

1. build() es un singleton compartido entre proveedores. ApiServiceProviderRepository::build() guarda la instancia en una propiedad estática de la clase padre. Si en el mismo proceso llamas primero a ApiServiceProvider::build() y luego a ApiModelRepositoryServiceProvider::build(), la segunda llamada devuelve la primera instancia. → Si necesitas ambas variantes, instancia las fachadas directamente:

2. Filtros con valor 0 se descartan. getInmuebles() filtra con !empty($value), así que ['garajes' => 0] nunca llega al API. Para "sin garaje" tendrás que filtrar del lado de tu aplicación.

3. idTipoInmueble() es protected en InmueblePreview. Solo es público en InmuebleDetail. Llamarlo sobre un preview desde fuera de la clase produce un Error de PHP.

4. fotoPortada() en InmuebleDetail asume que hay fotos. Accede a fotos()[0]["foto"] sin validar; si el inmueble no tiene fotos, genera un aviso. Valida antes:

5. Domain\ModelRepository\Inmueble::valorArriendo() devuelve el valor de venta. Es un defecto conocido de esa clase auxiliar. Usa InmueblePreview::valorArriendo() / InmuebleDetail::valorArriendo().

6. caracterisitcasInternas() está escrito con errata (caracterisitcas, no caracteristicas). Se mantiene así por compatibilidad hacia atrás.

7. La URL base por defecto es HTTP, no HTTPS (http://simi-api.com/ApiSimiweb/response/). Solo getEstadoInmueble() usa https://api.simicrm.app/crm/.

8. cURL no define timeouts. Una caída del API puede colgar tu petición. Si es crítico para ti, envuelve las llamadas en tu propia capa con timeout y caché (§15), o considera un job en segundo plano.

9. getEstadoInmueble() habla con otro API y otra versión (v3 del CRM, autenticación por cabecera). Que funcionen los demás métodos no garantiza que este también.

10. Los métodos de catálogo no verifican isSuccess() antes de iterar. getDepartamentos() itera directamente sobre la respuesta; si el API falla, puede propagarse un aviso de PHP. Envuélvelos en try/catch en producción.

18. Pruebas

Las pruebas del repositorio golpean el API real, así que necesitan un token válido.

Edita tests/testing.env.php:

Ejecuta:

tests/testing.env.php está en .gitignore: no subas tu token.

Probar tu propio código sin red

Extiende la abstracción y devuelve datos fijos:

19. Versionado y contribución

• El proyecto sigue Semantic Versioning.
• Los cambios se registran en CHANGELOG.md siguiendo Keep a Changelog.
• Fija la versión en tu composer.json ("homlity/sdk-simi": "^3.0") y revisa el changelog antes de subir de versión menor.

Para contribuir

1. Haz un fork de homlity/sdk-simi.
2. Crea una rama desde master: git checkout -b fix/mi-arreglo.
3. Si agregas un endpoint, sigue el patrón existente: una clase en Requests/, una en Responses/, su modelo en Modelos/, y expón el método en ApiFachada y en ApiFachadaRepository.
4. Agrega la entrada correspondiente en CHANGELOG.md.
5. Abre el Pull Request describiendo el cambio y su impacto en las versiones.

20. Soporte

21. Licencia

Este SDK se distribuye bajo la licencia MIT. Puedes usarlo, modificarlo, integrarlo en proyectos comerciales y redistribuirlo, siempre que conserves el aviso de copyright. El texto completo está en LICENSE.

La licencia cubre el SDK, no el acceso al API de SIMI: para consumir datos necesitas un token válido entregado por SIMI o por la inmobiliaria propietaria del inventario.

_{Hecho con ☕ por el equipo de Homlity.}