SDK Python para Portugal
corp-merch (PyPI) — clientes sync e async, Python 3.10+, type hints completos, modelos Pydantic v2, FastAPI-friendly.
Instalação e init
pip install corp-merch. Sync: from corp_merch import CorpMerch; cm = CorpMerch(api_key=os.environ['CM_KEY'], country='PT'). Async: from corp_merch import AsyncCorpMerch; mesma assinatura. País aplica IVA 23% via Portal das Finanças (AT) encaminhado pelo hub Lisboa.
Quickstart — submeter encomenda
order = cm.orders.create(idempotency_key=str(uuid4()), buyer={'vat_id': 'PT…'}, lines=[{'sku': 'TSH-001', 'qty': 200}], promised_date=date(2026,7,1)). Devolve modelo Pydantic Order com typing completo. Erros levantados como ValidationError, RateLimitError etc. Equivalente async: await acm.orders.acreate(…).
Verificação 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']); …. Levanta SignatureVerificationError em assinatura inválida; FastAPI converte em 400 via exception handler registado na app.
FAQ
Funciona com Django/Flask?
Sim — framework-agnostic. Enviamos middleware para Django (corp_merch.django) e Flask (corp_merch.flask) para rotas webhook.
Sync e async ambos suportados?
Sim — clientes separados (CorpMerch / AsyncCorpMerch) partilham os mesmos tipos. Usam httpx por baixo; traga o seu event loop.
Como paginar o catálogo?
for item in cm.catalog.list(country='PT'): … itera todas as páginas (cursor pagination interno). Async: async for item in acm.catalog.alist(country='PT'): …
Type hints / mypy?
Cobertura completa. Marker ./py.typed. Testado com mypy --strict e pyright. Modelos Pydantic v2 para todas as responses.
Source code?
MIT no GitHub: github.com/corp-merch/sdk-python. Issue tracker para bugs / RFCs.