SDK Python per l'Italia
corp-merch (PyPI) — client sync e async, Python 3.10+, type hints completi, modelli Pydantic v2, FastAPI-friendly.
Install e init
pip install corp-merch. Sync: from corp_merch import CorpMerch; cm = CorpMerch(api_key=os.environ['CM_KEY'], country='IT'). Async: from corp_merch import AsyncCorpMerch; stessa firma. Country applica IVA 22% via SdI instradato attraverso hub Milano.
Quickstart — invio ordine
order = cm.orders.create(idempotency_key=str(uuid4()), buyer={'vat_id': 'IT…'}, lines=[{'sku': 'TSH-001', 'qty': 200}], promised_date=date(2026,7,1)). Ritorna modello Pydantic Order con typing completo. Errori sollevati come ValidationError, RateLimitError ecc. Equivalente async: await acm.orders.acreate(…).
Verifica webhook (FastAPI)
@app.post('/wh') async def wh(req: Request): event = cm.webhooks.construct_event(await req.body(), req.headers['x-corp-signature'], os.environ['CM_WEBHOOK_SECRET']); …. Solleva SignatureVerificationError su firma errata; FastAPI converte in 400 via exception handler registrato sull'app.
FAQ
Funziona con Django/Flask?
Sì — framework-agnostic. Spediamo middleware per Django (corp_merch.django) e Flask (corp_merch.flask) per route webhook.
Sync e async entrambi supportati?
Sì — client separati (CorpMerch / AsyncCorpMerch) condividono gli stessi tipi. Usa httpx sotto; bring your own event loop.
Come paginare il catalogo?
for item in cm.catalog.list(country='IT'): … itera tutte le pagine (cursor pagination gestita). Async: async for item in acm.catalog.alist(country='IT'): …
Type hints / mypy?
Copertura completa. Marker ./py.typed. Testato con mypy --strict e pyright. Modelli Pydantic v2 per tutte le response.
Source code?
MIT su GitHub: github.com/corp-merch/sdk-python. Issue tracker per bug / RFC.