README

SDK PHP para integración con la API de Metrocuadrado.

⚠️ Estado: núcleo listo, módulos de dominio bloqueados

Metrocuadrado no publica documentación abierta de su API de integradores. Siguiendo la regla de no inventar contratos, este repositorio contiene toda la infraestructura que no depende de la especificación —y que no cambiará cuando ésta llegue— pero ningún path, campo, enum ni header de dominio.

Lo que falta y cómo obtenerlo: docs/api-reference.md.

Requisitos

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

Instalación

composer require metrocuadrado/sdk-php

Qué está implementado

Componente	Estado
`Config`	✅ credenciales, URL base, timeout
`MetrocuadradoClient`	✅ fachada con inyección de dependencias
`Http/HttpClientInterface` · `ApiResponse` · `CurlHttpClient`	✅
`Api/BaseApi`	✅ `send()`, `encodePath()`, `normalizeBatchPayload()`
`Exception/*`	✅ jerarquía completa y mapeo por status
`Schema/SchemaCatalog`	✅ lectura del OpenAPI versionado
`Schema/PayloadValidator`	✅ validación básica y estricta
`Api/<Recurso>Api`	⛔ falta spec
`Data/<Recurso>Snapshot` · `<Recurso>Status`	⛔ falta spec
Polling asíncrono	⛔ falta spec
`Webhook/*`	⛔ falta spec

Uso

use Metrocuadrado\Sdk\Config;
use Metrocuadrado\Sdk\MetrocuadradoClient;

$config = new Config(
    apiKey: getenv('METROCUADRADO_API_KEY'),
    baseUrl: getenv('METROCUADRADO_BASE_URL'),
    authHeaderName: getenv('METROCUADRADO_AUTH_HEADER'),
    timeoutSeconds: 30,
);

$client = new MetrocuadradoClient($config);

Nota sobre el esquema de autenticación

El SDK no adivina el nombre del header de autenticación ni la URL base: los recibe por constructor. CurlHttpClient inyecta en cada request Accept: application/json más el header devuelto por Config::authHeaders(), y añade Content-Type: application/json sólo cuando hay cuerpo JSON.

Cuando llegue la especificación oficial se añadirán a Config las constantes BASE_URL_PRODUCTION / BASE_URL_QA / BASE_URL_MOCK y los valores por defecto correspondientes, sin romper compatibilidad: los parámetros $baseUrl y $authHeaderName conservan su posición y sólo ganan un default.

Validación local antes de enviar

PayloadValidator corta los payloads malformados antes de gastar un request. Es genérico y dirigido por el OpenAPI: nada está hardcodeado.

use Metrocuadrado\Sdk\Schema\PayloadValidator;

$validator = new PayloadValidator($client->schemaCatalog());

// Básico: presencia de requeridos de primer nivel.
$validator->validate($items, 'NombreDelSchema');

// Estricto: además tipos, enums y requeridos de objetos anidados.
$validator->validate($items, 'NombreDelSchema', strict: true);

Todo fallo local lanza InvalidArgumentException citando el campo y el índice del item.

Testeabilidad

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

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

Manejo de errores

Ver docs/error-handling.md.

Tests

composer install
composer test

La suite no realiza ninguna llamada de red.

Documentación

docs/api-reference.md — estado del descubrimiento y datos faltantes
docs/error-handling.md — jerarquía de excepciones y diagnóstico
docs/listing-parameters.md — pendiente
docs/task-polling.md — pendiente
docs/webhooks.md — pendiente
docs/solicitud-acceso.md — borrador para pedir acceso a Metrocuadrado

Licencia

MIT. Ver LICENSE.

metrocuadrado / sdk-php

Maintainers

Package info

Statistics

Security