SDK Corp-Merch per l'Italia
Librerie client ufficiali tipizzate per Node.js, Python e PHP. Retry automatici, idempotency, verifica webhook, sandbox integrato.
Cosa includono gli SDK
Ogni SDK include: client tipizzato (TypeScript .d.ts / Python type stubs / PHP 8 attributes), retry automatici con backoff esponenziale, generazione idempotency-key, helper di verifica firma webhook, toggle sandbox/produzione, classi errore strutturate da RFC 7807. Testati con il catalogo reale italiano prima di ogni release.
Comandi di installazione
Node.js: npm install @corp-merch/sdk. Python: pip install corp-merch (Python 3.10+). PHP: composer require corp-merch/sdk (PHP 8.1+). Tutti i pacchetti firmati; lockfile pubblicati. Minor weekly; semver-strict — nessun breaking change fuori dalle major.
Localizzazione paese
Gli SDK accettano country='Italy' all'init e automaticamente: applicano IVA 22%, instradano fatture via SdI, default hub Milano, format valuta per locale italiano. Override per-request via opts.country se necessario. Catalogo include name_i18n per inglese e italiano.
FAQ
Quale linguaggio scegliere?
Quello usato dal tuo team — parità di feature. Node.js più popolare (45%), Python secondo (30%), PHP terzo (25%).
Gli SDK funzionano serverless?
Sì — footprint piccolo (Node.js ~80 KB), no dipendenze native. Testati su Vercel, AWS Lambda, Cloudflare Workers (con subpackage @corp-merch/sdk-edge).
C'è una CLI?
npx @corp-merch/cli viene con l'SDK Node.js — utile per dump catalogo, creazione ordini sandbox, ispezione payload webhook.
Come sono strutturati gli errori SDK?
Tutti gli errori estendono CorpMerchError con code, message, httpStatus, detailUrl. Sottoclassi: ValidationError, AuthError, RateLimitError, ServerError, IdempotencyConflictError.
Policy di versioning?
SemVer-strict. Major ~annuali con 12 mesi di sovrapposizione supporto. Minor mensili. Patch sicurezza backportate agli ultimi due major.