README

SDK PHP de FincaRaíz

Publica, actualiza y sincroniza inmuebles en FincaRaíz desde PHP.
Un cliente tipado, validado y probado para la API de Integradores de FincaRaíz.

Homlity · GitHub · Packagist · Documentación

Qué es este paquete

homlity/sdk-fincaraiz es un SDK en PHP puro (sin dependencias de runtime, solo ext-curl y ext-json) que envuelve la API de Integradores de FincaRaíz — el canal oficial por el que una inmobiliaria, un portal o un CRM publica su inventario en fincaraiz.com.co.

Lo mantiene Homlity, la plataforma colombiana que conecta, automatiza y optimiza la operación inmobiliaria. Este SDK es la misma pieza que usamos internamente para sincronizar inventarios hacia FincaRaíz, publicada como open source para que cualquier equipo la reutilice.

Para qué sirve

Necesito…	El SDK lo resuelve con
Publicar inmuebles de mi CRM en FincaRaíz	`listings()->create()`
Actualizar precio, fotos o descripción	`listings()->update()`
Activar o eliminar una publicación	`listings()->updateStatus()`
Saber si la publicación quedó activa	`listings()->getSnapshot()` + `ListingStatus`
Seguir el resultado de una operación asíncrona	`tasks()->waitUntilSettled()`
Recibir avisos en tiempo real sin hacer polling	`webhooks()` + `WebhookNotification`
Buscar el `location_main_id` de un barrio	`locations()->search()`
Traer el catálogo de características	`categories()->list()`
Consultar el cupo (quota) de un cliente	`clients()->all()`

Qué te ahorra

Autenticación resuelta. El OpenAPI de FincaRaíz mezcla apikey y X-API-KEY; el SDK envía ambos headers con el mismo token para máxima compatibilidad.
Validación antes de la red. Los payloads de creación/actualización/estado se validan contra el snapshot OpenAPI versionado en el repo antes de gastar una llamada HTTP.
Errores tipados. 401 → AuthException, 404 → NotFoundException, 409 → ConflictException, 422 → ValidationException, 429 → RateLimitException, con acceso a statusCode(), trackingId() y firstErrorMessage().
Estados como enums, no como enteros mágicos. ListingStatus::ACTIVE, TaskStatus::FORWARDED, con helpers (isPublished(), isSettled(), isTerminalFailure()).
Webhooks seguros. Verificación HUB.ID / VERIFY-TOKEN con hash_equals() y normalización del payload de tareas (LISTING_CORE y LISTING_STATUS) en una sola forma consumible.
Cero dependencias de composer en producción. Instalable en cualquier proyecto PHP 8.1+.

Instalación

composer require homlity/sdk-fincaraiz

Importante — hoy solo hay rama de desarrollo publicada. El paquete aún no tiene tags de versión, así que Composer solo puede resolver dev-main. Instala de forma explícita:
composer require homlity/sdk-fincaraiz:dev-main
…o baja la estabilidad mínima en tu composer.json:
{
  "minimum-stability": "dev",
  "prefer-stable": true
}
Ver docs/instalacion.md para el detalle y para fijar un commit concreto.

Requisitos: PHP ^8.1, extensiones curl y json.

Uso en 30 segundos

<?php

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

use Fincaraiz\Sdk\Config;
use Fincaraiz\Sdk\FincaRaizClient;

$sdk = new FincaRaizClient(new Config(
    apiKey: getenv('FINCARAIZ_API_KEY'),
    baseUrl: Config::BASE_URL_PRODUCTION,
    timeoutSeconds: 30,
));

// ¿Qué clientes (inmobiliarias) tengo asociados y cuánto cupo les queda?
foreach ($sdk->clients()->all() as $client) {
    printf(
        "%s — %s de %s inmuebles usados (%s%%)\n",
        $client['name'],
        $client['used_quota'],
        $client['initial_quota'],
        $client['percentage_used_quota'],
    );
}

El namespace PHP sigue siendo Fincaraiz\Sdk\ (describe la API que se integra); el paquete Composer es homlity/sdk-fincaraiz (describe quién lo publica y mantiene).

Publicar un inmueble

<?php

use Fincaraiz\Sdk\Exception\ApiException;

$listing = [
    'external_code'  => 'CRM-1001',                                // tu ID interno
    'client_id'      => 'df03d199-be5c-4c5c-98f6-849361cb7fae',    // UUID del cliente en FincaRaíz
    'offer'          => 'sell',                                    // sell | rent | lease
    'property_type'  => 'house',                                   // house | apartment | office | ...
    'description'    => 'Casa amplia, iluminada y bien ubicada.',
    'price'          => 450000000,
    'area'           => 120,
    'rooms'          => 3,
    'baths'          => 2,
    'garages'        => 1,
    'stratum'        => 4,
    'address' => [
        'address' => 'Calle 12 # 34-56',
    ],
    'locations' => [
        'location_point'   => ['latitude' => 4.729795079, 'longitude' => -74.044724493],
        'location_main_id' => '1895e0a3-60b8-4a9d-858d-f2c7297b48b2', // barrio, vía locations()->search()
        'view_map'         => 2,                                      // 0 punto | 1 oculto | 2 solo zona
    ],
    'listing_contact' => [
        'emails' => [
            ['email' => 'ventas@midominio.com', 'is_main' => true, 'sort_order' => 0],
        ],
        'phones' => [
            [
                'phone'              => '+573001112233',
                'is_whatsapp_number' => true,
                'is_click_to_call'   => true,
                'sort_order'         => 0,
            ],
        ],
    ],
    'photos' => [
        ['sort_order' => 1, 'is_main' => true,  'image' => 'https://cdn.midominio.com/1.jpg'],
        ['sort_order' => 2, 'is_main' => false, 'image' => 'https://cdn.midominio.com/2.jpg'],
    ],
];

try {
    $response = $sdk->listings()->create($listing);   // POST /listing → { "task": { "id": ..., "status": ... } }
    $taskId   = $response['task']['id'];

    // La publicación es asíncrona: espera a que la tarea llegue a un estado terminal.
    $task = $sdk->tasks()->waitUntilSettled($taskId, [
        'maxAttempts'     => 20,
        'intervalSeconds' => 3,
    ]);

    if ($task->isFailed()) {
        throw new RuntimeException('FincaRaíz rechazó el inmueble: ' . $task->firstErrorMessage());
    }

    foreach ($task->listingUpdates() as $update) {
        printf(
            "%s → listing_id=%s fr_property_id=%s (%s)\n",
            $update['external_code'],
            $update['listing_id'],
            $update['fr_property_id'],
            $update['processing_status'],
        );
    }
} catch (ApiException $e) {
    // Errores HTTP de la API, ya tipados y con diagnóstico listo.
    error_log(sprintf(
        '[FincaRaíz %s] %s (tracking: %s)',
        $e->statusCode(),
        $e->firstErrorMessage() ?? $e->getMessage(),
        $e->trackingId() ?? 'n/a',
    ));
    throw $e;
}

Guarda el listing_id. Es el identificador que necesitarás para actualizar o eliminar el inmueble más adelante. El fr_property_id es el código público que ven los usuarios en el portal.

Recursos disponibles

$sdk->listings();    // POST/PATCH/GET /listing, PATCH /listing/status, POST /validate-listing
$sdk->clients();     // GET /client/, /client/{id}, /client/{id}/agent
$sdk->categories();  // GET /category
$sdk->locations();   // GET /location/{name}
$sdk->tasks();       // GET /task/{id} + polling
$sdk->webhooks();    // POST /webhook/{id}/subscribe | /unsubscribe

La tabla completa endpoint ↔ método está en docs/api-reference.md.

Ciclo de vida de una publicación

  Tu CRM                    SDK                       FincaRaíz
    │                        │                            │
    │  create($listing) ─────►  valida payload            │
    │                        │  POST /listing ───────────►│  crea tarea
    │                        │◄────── { task: { id } } ───│
    │                        │                            │  procesa (asíncrono)
    │                        │                            │
    ├── Opción A: polling ───►  GET /task/{id} ──────────►│
    │                        │◄── COMPLETED / ERROR ──────│
    │                        │                            │
    └── Opción B: webhook  ◄─────────── POST tu endpoint ─┤  (HUB.ID + VERIFY-TOKEN)
                             │
                             ▼
                 listing_id + fr_property_id → guárdalos en tu base de datos

Polling (docs/tareas.md) — simple, bueno para procesos batch o scripts CLI.
Webhooks (docs/webhooks.md) — recomendado en producción: sin espera activa y sin consumir rate limit.

Documentación completa

Documento	Contenido
docs/README.md	Índice y mapa de la documentación
docs/instalacion.md	Instalación, requisitos, versionado, integración con Laravel/Symfony
docs/configuracion.md	`Config`, entornos, timeouts, HTTP client propio, logging
docs/api-reference.md	Todos los endpoints, firmas, parámetros y formas de respuesta
docs/listing-parameters.md	Cada campo de un inmueble: tipo, obligatoriedad y notas
docs/enums.md	Enums y códigos: oferta, tipo de inmueble, estrato, estados…
docs/categorias.md	Las 234 características (`categories`) con su ID
docs/tareas.md	Tareas asíncronas, polling y estados terminales
docs/webhooks.md	Suscripción, verificación de firma y procesamiento
docs/errores.md	Jerarquía de excepciones, diagnóstico y reintentos
docs/flujos.md	Recetas: sincronización completa, Laravel, idempotencia, lotes
docs/testing.md	Cómo testear tu integración sin llamar a FincaRaíz
docs/faq.md	Preguntas frecuentes y errores comunes

Ejemplos ejecutables: carpeta examples/.

Soporte

Issues y bugs del SDK → github.com/homlity/sdk-fincaraiz/issues
Credenciales, cupos y permisos de la API → tu contacto comercial en FincaRaíz
Homlity → homlity.com

Licencia

MIT. Ver LICENSE.

_{Hecho por Homlity — conecta, automatiza y optimiza tu operación inmobiliaria.}

homlity / sdk-fincaraiz

Maintainers

Package info

Statistics

Security