README

Homlity · para desarrolladores
homlity.com · Portal de desarrolladores

SDK PHP para Metrocuadrado

SDK PHP mantenido por Homlity para integrarse con la API de Metrocuadrado (PTEC Core), escrito sobre la documentación oficial.

Cubre los 19 endpoints publicados: autenticación, catálogos, agentes, sucursales, inmuebles y transacciones. Cero dependencias de runtime.

📚 Referencia completa de métodos, uno a uno, con para qué sirve cada uno y un ejemplo ejecutable: docs/referencia-metodos.md.

Requisitos

PHP ^8.1
ext-curl, ext-json
Cero dependencias de runtime

Instalación

composer require homlity/sdk-metrocuadrado

Uso

use Metrocuadrado\Sdk\Auth\Credentials;
use Metrocuadrado\Sdk\Config;
use Metrocuadrado\Sdk\MetrocuadradoClient;

$config = Config::production(
    apiKey: getenv('METROCUADRADO_API_KEY'),
    credentials: new Credentials(
        username: getenv('METROCUADRADO_USERNAME'),
        password: getenv('METROCUADRADO_PASSWORD'),
        identification: getenv('METROCUADRADO_IDENTIFICATION'),
    ),
);

$client = new MetrocuadradoClient($config);

// Catálogos (sólo API key)
$regions = $client->catalogue()->regions();
$cities  = $client->catalogue()->cities(regionId: 1);
$types   = $client->catalogue()->realEstateTypes();

// Inmuebles (API key + JWT, que el SDK obtiene y renueva solo)
$receipt = $client->realEstate()->publish($property);
$estado  = $client->transactions()->find($receipt->transactionId());

$client->realEstate()->published();
$client->realEstate()->unpublish('11222-M4137000', 'https://tu-dominio.com/callback');

// Agentes y sucursales
$client->agents()->create($agent);
$client->offices()->all();

Config::development(...) apunta al entorno de desarrollo de Metrocuadrado.

Qué hay implementado

Recurso	Métodos
`auth()` · `token()`	emisión, caché y renovación del JWT
`catalogue()`	`regions` · `cities` · `zones` · `sectors` · `neighborhoodsByCity` · `neighborhoodsBySector` · `neighborhood` · `searchNeighborhoods` · `businessTypes` · `realEstateTypes` · `amenities`
`agents()`	`all` · `create` · `update`
`offices()`	`all`
`realEstate()`	`published` · `unpublished` · `listByStatus` · `find` · `publish` · `update` · `unpublish`
`transactions()`	`find`

Cada método, con firma, parámetros, excepciones y ejemplo, en docs/referencia-metodos.md. La tabla endpoint ↔ método está en docs/api-reference.md.

Autenticación

La API vive en dos hosts —el emisor de tokens y el de recursos— y no usa Authorization: Bearer: la API key va en x-api-key y el JWT en el header token. El token dura una hora; el SDK lo cachea, lo renueva 60 s antes de caducar y, ante un 401, lo renueva y reintenta la petición una vez.

Detalle en docs/autenticacion.md; ejemplo ejecutable en examples/autenticacion.php.

Operaciones asíncronas

Publicar, actualizar y despublicar inmuebles, y crear y actualizar agentes, devuelven un TransactionReceipt con el transactionId; el resultado definitivo llega al responseUrl del payload. Ver docs/task-polling.md y docs/webhooks.md.

Validación local

Los campos obligatorios se comprueban antes de gastar un request y fallan con InvalidArgumentException citando lo que falta:

$client->realEstate()->publish(['price' => 1]);
// InvalidArgumentException: Real estate publication: missing required field(s):
// realEstateType, realEstateOffer, city, images, neighborhood, reference1,
// responseUrl, amenities.

PayloadValidator añade validación dirigida por OpenAPI (tipos, enums, requeridos anidados) en cuanto se disponga del snapshot oficial en resources/openapi/.

Testeabilidad

El cliente acepta un HttpClientInterface, un SchemaCatalog y un TokenProviderInterface inyectables, así que se instancia con dobles sin tocar nada privado ni la red:

$client = new MetrocuadradoClient($config, $fakeHttpClient, $schemaCatalog, $fakeTokenProvider);

Manejo de errores

Ver docs/error-handling.md.

Tests

composer install
composer test

La suite no realiza ninguna llamada de red.

Documentación

docs/referencia-metodos.md — referencia detallada de cada método, con ejemplos
docs/autenticacion.md — token, hosts, headers y renovación
docs/api-reference.md — endpoints ↔ métodos y discrepancias de la doc oficial
docs/listing-parameters.md — campos y amenities de publicación
docs/task-polling.md — transacciones asíncronas
docs/webhooks.md — el callback responseUrl
docs/error-handling.md — jerarquía de excepciones y diagnóstico
docs/solicitud-acceso.md — borrador para pedir credenciales
docs/publicacion-packagist.md — versionado y publicación del paquete

Soporte

Documentación y guías de integración: https://homlity.com/desarrolladores/
Homlity: https://homlity.com
Incidencias y propuestas: issues del repositorio

Homlity no es Metrocuadrado: este SDK es un cliente independiente de su API pública. Las credenciales de integrador las entrega Metrocuadrado (ver docs/solicitud-acceso.md).

Licencia

MIT. Ver LICENSE.

Hecho por Homlity · homlity.com/desarrolladores

homlity / sdk-metrocuadrado

Package info

Security

Statistics