README

SDK Domus para PHP

Cliente PHP oficial de Homlity para consumir la API del CRM inmobiliario Domus.
Inmuebles, propietarios, ciudades, barrios, zonas, asesores y más — con objetos tipados en español.

homlity.com · Portal de desarrolladores · Packagist · Repositorio

Tabla de contenido

¿Qué es esto y para qué sirve?
Requisitos
Instalación
Inicio rápido
Autenticación: el proveedor de token
Qué puedes consultar
Ejemplo completo: listado con filtros y paginación
Documentación detallada
Versiones y compatibilidad
Desarrollo y pruebas
Soporte

¿Qué es esto y para qué sirve?

Domus es un CRM inmobiliario ampliamente usado en Colombia y LATAM. Las inmobiliarias cargan allí su inventario (inmuebles, fotos, precios, propietarios, asesores) y Domus expone esa información mediante una API REST protegida por token.

Consumir esa API "a mano" implica repetir siempre lo mismo: armar URLs con decenas de filtros, manejar cURL, interpretar respuestas que devuelven HTTP 200 incluso cuando fallan, y traducir claves en inglés (saleprice, neighborhood_id, area_cons) a algo legible en tu aplicación.

Este SDK resuelve exactamente eso:

Sin el SDK	Con el SDK
`curl` manual + headers + `json_decode`	`$api->getInmuebles([...])`
Interpretar si un 200 es realmente un éxito	`$response->isSuccess()` ya lo valida
Leer `$data['area_cons']` y adivinar	`$inmueble->getAreaConstruida()`
Paginación manual sobre el body crudo	`$resultado->getPaginador()->getUltimaPagina()`
Acoplarte a la forma del JSON de Domus	Programar contra interfaces (`InmueblePreviewAdapter`)

Casos de uso típicos

Portales inmobiliarios: renderizar el inventario de una inmobiliaria en un sitio web propio (WordPress, Laravel, Symfony, PHP plano).
Sindicación de inventario: exportar inmuebles hacia portales de terceros o feeds XML/JSON.
Buscadores y filtros: construir búsquedas por ciudad, barrio, tipo, precio, habitaciones, área, estrato, etc.
Fichas de inmueble: página de detalle con galería de imágenes, tour 3D, video, características y datos del asesor.
Back-office: consultar propietarios y su información de contacto.
Sincronización: procesos programados que replican el inventario de Domus a una base de datos local.

Arquitectura en 30 segundos

El SDK está organizado en capas (arquitectura hexagonal ligera):

Application/   ApiServiceProvider        → punto de entrada, arma el SDK
Domain/        *Adapter (interfaces)     → el contrato contra el que programas
InfraStructure/
  API/         ApiFachada                → fachada de alto nivel (lo que usarás el 95% del tiempo)
  Requests/    Request*  + HttpClient    → capa HTTP (cURL), endpoints y filtros
  Responses/   Response*                 → validación y extracción del body
  Modelos/V1/  InmueblePreview, ...      → objetos de dominio con getters en español

La regla práctica: usa ApiFachada. Baja a Requests/ solo cuando necesites algo que la fachada no expone todavía (ver métodos no implementados).

Requisitos

Requisito	Versión
PHP	>= 7.3 (probado en 7.3, 7.4, 8.0, 8.1)
Extensión `ext-curl`	requerida
Extensión `ext-json`	requerida
Extensión `ext-mbstring`	requerida
Token de API de Domus	proporcionado por la inmobiliaria / Domus

No requiere Guzzle ni ninguna dependencia de terceros en producción: el transporte es cURL nativo.

Instalación

composer require homlity/sdk-domus

Para fijar la línea de versión mayor (recomendado en producción):

composer require homlity/sdk-domus:^3.2

Nota: el paquete se distribuía antes como codwelt/sdk-domus. Ese nombre quedó obsoleto; usa siempre homlity/sdk-domus. El namespace PHP sigue siendo Codwelt\DOMUS\SDK\ por compatibilidad hacia atrás, así que no tienes que cambiar tus use al migrar.

Detalles completos (instalación sin Composer, Laravel, WordPress): docs/instalacion.md.

Inicio rápido

El SDK necesita saber de dónde sacar el token. Para eso implementas una interfaz de una sola función y se la entregas al proveedor:

<?php

require __DIR__ . '/vendor/autoload.php';

use Codwelt\DOMUS\SDK\Application\Providers\ApiServiceProvider;
use Codwelt\DOMUS\SDK\Domain\Providers\TokenServiceProviderAdapter;

// 1) Implementa el proveedor de token
class MiProveedorDeToken implements TokenServiceProviderAdapter
{
    public function getToken(): string
    {
        // De donde quieras: .env, base de datos, config, Vault...
        return getenv('DOMUS_TOKEN');
    }
}

// 2) Construye el service provider y entrégale el proveedor de token
$provider = ApiServiceProvider::build();
$provider->setTokenProvider(new MiProveedorDeToken());

// 3) Obtén la fachada y consulta
$api = $provider->getAPi();

$resultado = $api->getInmuebles([
    'parametros' => [
        'city'     => 1,        // id de ciudad
        'biz'      => 2,        // id de gestión (venta / arriendo)
        'bedrooms' => 3,
        'page'     => 1,
    ],
]);

foreach ($resultado->getInmuebles() as $inmueble) {
    printf(
        "[%s] %s — %s, %s · %s m² · %s hab · %s%s",
        $inmueble->getIdentificacion(),
        $inmueble->getTipoInmuebleNombre(),
        $inmueble->getBarrioNombre(),
        $inmueble->getCiudadNombre(),
        $inmueble->getAreaConstruida(),
        $inmueble->getHabitacionesTotal(),
        $inmueble->getPrecioFormateado(),
        PHP_EOL
    );
}

$paginador = $resultado->getPaginador();
echo "Página {$paginador->getPaginaActual()} de {$paginador->getUltimaPagina()} "
   . "({$paginador->getTotal()} inmuebles)" . PHP_EOL;

Alternativa: sin service provider

Si no necesitas la inyección del proveedor de token, puedes instanciar la fachada directamente:

use Codwelt\DOMUS\SDK\InfraStructure\API\ApiFachada;

$api = new ApiFachada(getenv('DOMUS_TOKEN'));
$ciudades = $api->getCiudades();

⚠️ ApiServiceProvider::build() devuelve un singleton. La primera llamada crea la instancia y todas las siguientes devuelven la misma, incluso si le pasas otro proveedor de token. Si necesitas trabajar con varios tokens (multi-inmobiliaria) en el mismo proceso, instancia ApiFachada directamente como en el ejemplo de arriba. Ver docs/errores-y-depuracion.md.

Autenticación: el proveedor de token

TokenServiceProviderAdapter es intencionalmente mínimo:

namespace Codwelt\DOMUS\SDK\Domain\Providers;

interface TokenServiceProviderAdapter
{
    public function getToken(): string;
}

Esto te permite decidir dónde vive el token sin que el SDK lo imponga. Ejemplos reales:

// Desde variables de entorno
class TokenEnv implements TokenServiceProviderAdapter {
    public function getToken(): string { return getenv('DOMUS_TOKEN') ?: ''; }
}

// Desde la configuración de Laravel
class TokenConfig implements TokenServiceProviderAdapter {
    public function getToken(): string { return (string) config('domus.token'); }
}

// Multi-tenant: cada inmobiliaria con su propio token en base de datos
class TokenInmobiliaria implements TokenServiceProviderAdapter {
    public function __construct(private int $inmobiliariaId) {}
    public function getToken(): string {
        return Inmobiliaria::findOrFail($this->inmobiliariaId)->domus_token;
    }
}

El token se envía en cada petición como header Authorization.

Nunca publiques el token en el frontend ni lo subas al repositorio. Guárdalo en variables de entorno o en un gestor de secretos.

Qué puedes consultar

Métodos disponibles en ApiFachada:

Método	Devuelve	Descripción
`getInmuebles(array $filtros = [])`	`ResultadoResponse`	Búsqueda paginada de inmuebles con filtros y ordenamiento
`getDetalleInmueble($codigo, array $params = [])`	`InmuebleDetalleAdapter \| null`	Ficha completa de un inmueble (imágenes, características, asesores, tour 3D)
`getCiudades()`	`Ciudad[]`	Catálogo de ciudades
`getTiposInmueble()`	`TipoInmueble[]`	Catálogo de tipos (casa, apartamento, lote…)
`getBarrios()`	`Barrio[]`	Catálogo de barrios
`getGestiones()`	`Gestion[]`	Catálogo de gestiones (venta, arriendo, venta y arriendo…)
`getPropietarios()`	`ResponseConsultarPropietarios`	Listado de propietarios
`getDetallePropietario($cedula)`	`ResponseDetallePropietario`	Detalle de un propietario por documento

Además hay catálogos disponibles a nivel de Request (aún no expuestos en la fachada): zonas, características/amenidades, destinaciones, estados de inmueble y asesores. Se usan igual de fácil — ver docs/referencia-api.md.

Referencia completa de cada método, sus parámetros y sus modelos: docs/referencia-api.md

Ejemplo completo: listado con filtros y paginación

use Codwelt\DOMUS\SDK\InfraStructure\API\ApiFachada;

$api = new ApiFachada(getenv('DOMUS_TOKEN'));

$resultado = $api->getInmuebles([
    // Filtros de búsqueda (query string)
    'parametros' => [
        'city'      => 1,          // ciudad
        'type'      => 2,          // tipo de inmueble
        'biz'       => 1,          // gestión: venta / arriendo
        'minbed'    => 2,          // mínimo de habitaciones
        'maxbed'    => 4,
        'pvmin'     => 150000000,  // rango de precio de venta
        'pvmax'     => 400000000,
        'stratum'   => 4,
        'great'     => 'on',       // solo destacados
        'page'      => 1,
    ],
    // Ordenamiento (campos permitidos por Domus)
    'ordenamiento' => ['saleprice'],
    // Headers de control
    'headers' => [
        'perpage'      => 24,      // resultados por página
        'inmobiliaria' => 1,       // 1 = todas las sucursales
    ],
]);

if (count($resultado->getInmuebles()) === 0) {
    echo "Sin resultados o token inválido." . PHP_EOL;
    return;
}

foreach ($resultado->getInmuebles() as $inmueble) {
    echo $inmueble->getIdentificacion() . ' · ' . $inmueble->getDireccion() . PHP_EOL;
    echo '  ' . $inmueble->getUrlFoto() . PHP_EOL;
    echo '  Venta: ' . $inmueble->getValorVenta()
       . ' | Arriendo: ' . $inmueble->getValorArriendo()
       . ' | Admón: ' . $inmueble->getValorAdministracion() . PHP_EOL;
}

// Los modelos implementan JsonSerializable: útil para APIs propias
header('Content-Type: application/json');
echo json_encode([
    'data'       => $resultado->getInmuebles(),
    'paginacion' => $resultado->getPaginador(),
]);

Ficha de detalle

$inmueble = $api->getDetalleInmueble('1234001');

if ($inmueble === null) {
    http_response_code(404);
    exit('Inmueble no encontrado');
}

echo $inmueble->getDescripcion();
echo $inmueble->getEstrato();
echo $inmueble->getAreaPrivada();
echo $inmueble->getTour3d();
echo $inmueble->getVideo();

foreach ($inmueble->getImagenes() as $imagen) {
    echo '<img src="' . $imagen->getThumb() . '" data-full="' . $imagen->getFull() . '">';
}

foreach ($inmueble->caracteristicas() as $caracteristica) {
    echo '<li>' . $caracteristica->getNombre() . '</li>';
}

foreach ($inmueble->getAsesores() as $asesor) {
    echo $asesor->getNombre() . ' — ' . $asesor->getEmail() . ' — ' . $asesor->getTelefonoMovil();
}

Muchos más ejemplos (Laravel, WordPress, caché, sincronización, feed JSON, buscador completo): docs/ejemplos.md

Documentación detallada

Guía	Contenido
Instalación	Composer, autoload manual, integración con Laravel / WordPress / Symfony
Referencia de la API	Cada método de la fachada, sus parámetros, retornos y excepciones
Filtros de búsqueda	Catálogo completo de los ~40 filtros, ordenamiento y headers
Modelos y getters	Todos los objetos de dominio y qué getter devuelve qué campo de Domus
Ejemplos y recetas	Casos de uso reales, listos para copiar
Errores y depuración	Cómo detectar fallos, excepciones, trampas conocidas
Versiones y migración	Diferencias 2.x ↔ 3.x y cómo migrar

Versiones y compatibilidad

Línea del SDK	API de Domus	URL base	Estado
3.x	Domus 3.0	`https://api.domus.la/3.0/`	✅ Actual — usa esta
2.x	Domus 2.1	`http://api.domus.la/`	⚠️ Mantenimiento / heredada
1.x	Domus 2.1	`http://api.domus.la/`	❌ Sin soporte

Cambios clave de 2.x a 3.x:

URL base ahora es HTTPS y versionada (/3.0/).
Endpoints de inmuebles unificados: pro-grid y pro-detail → properties.
Header de autenticación authorization → Authorization.
Detección de errores: el body ahora usa errors y message (antes error y mensaje).
getDetalleInmueble() acepta un segundo parámetro $params para enviar headers propios.
Nuevo header de agrupación grupo en la búsqueda de inmuebles.
InmuebleDetalle::getAsesores() lee brokers (antes broker).

Guía de migración paso a paso: docs/versiones-y-migracion.md.

Desarrollo y pruebas

git clone https://github.com/homlity/sdk-domus.git
cd sdk-domus
composer install

# Las pruebas golpean la API real: necesitan credenciales
cp tests/testing.env.php.example tests/testing.env.php
# edita tests/testing.env.php con un token válido y un código de inmueble existente

./vendor/bin/phpunit

tests/testing.env.php está ignorado por git y sus valores se cargan como variables de entorno en TestCase::setUp(). La integración continua (GitHub Actions) ejecuta la suite contra PHP 7.3, 7.4, 8.0 y 8.1, inyectando las credenciales desde el secreto DOMUS_ENV_TESTING.

Soporte

🌐 Web: homlity.com
👩‍💻 Portal de desarrolladores: homlity.com/desarrolladores
🐛 Reportar un problema: GitHub Issues
📦 Paquete: packagist.org/packages/homlity/sdk-domus
📖 API de Domus: documentación oficial v2.1

Hecho con ❤️ por Homlity

homlity / sdk-domus

Package info

Security

Statistics