SDK PHP para Portugal
corp-merch/sdk no Packagist — PHP 8.1+, PSR-7/PSR-18, bridges nativos Laravel e Symfony, DTOs readonly.
Instalação e init
composer require corp-merch/sdk. $cm = new CorpMerch\Client(apiKey: getenv('CM_KEY'), country: 'PT'). Usa PSR-18 HTTP client — passe qualquer (Guzzle, Symfony HttpClient, default sensato). Aplica IVA 23% e Portal das Finanças (AT) para Portugal; hub padrão Lisboa.
Quickstart — submeter encomenda
$order = $cm->orders->create(idempotencyKey: Uuid::v4(), buyer: ['vat_id' => 'PT…'], lines: [['sku' => 'TSH-001', 'qty' => 200]], promisedDate: '2026-07-01'); echo $order->id; echo $order->estimatedIvaAmountCents. Devolve DTO Order readonly. Erros lançados como CorpMerch\Exception\ValidationException etc.
Bridges Laravel e Symfony
Laravel: instale corp-merch/sdk-laravel — regista singleton ligado a config('corp-merch.country'). Symfony: corp-merch/sdk-symfony adiciona bundle com cliente autowired. Ambos os pacotes incluem middlewares webhook que validam assinatura e despacham eventos tipados no event bus do framework.
FAQ
Versão mínima de PHP?
PHP 8.1 (readonly properties, enums). PHP 8.2 e 8.3 testados. PHP 7.x não suportado.
Que HTTP client?
PSR-18 — bring your own. Descoberta padrão via http-interop/http-factory-discovery, apanha Guzzle ou Symfony HttpClient.
Como estão tipadas as responses?
DTOs readonly (Order, Invoice, CatalogItem). Enums para status (OrderStatus::ACCEPTED etc.). Strict types: declare(strict_types=1) em cada ficheiro.
Iteração de catálogo?
foreach ($cm->catalog->iterate(country: 'PT') as $item) { … } — baseado em generators, fetch lazy de páginas. Cancele com break sem desperdício.
Código fonte?
MIT no GitHub: github.com/corp-merch/sdk-php. Codestyle PSR-12; PHPStan level 9 em CI.