API REST per il procurement in Italia
Accesso programmatico a Corp-Merch — invia ordini, sincronizza il catalogo, ricevi eventi webhook. JSON su HTTPS, autenticazione Bearer, SLA 99,95%.
Autenticazione e rate limit
OAuth 2.0 client credentials o token Bearer a lunga durata (rotazione ogni 90 giorni). Base URL: https://api.corp-merch.com/v1. Rate limit: 600 req/min per token, burst 60 req/sec. Tutti i payload UTF-8 JSON; timestamp ISO 8601. Errori secondo RFC 7807 (application/problem+json).
Panoramica degli endpoint
POST /v1/orders — invia un ordine d'acquisto. GET /v1/catalog — recupera SKU localizzati per l'Italia (prezzi in EUR IVA 22% inclusa). GET /v1/orders/{id} — stato ordine con tracking. POST /v1/webhooks — registra URL di callback per eventi order.shipped, invoice.issued (via SdI), invoice.paid. OpenAPI 3.1 completo su /v1/openapi.json.
Conformità e fatturazione in Italia
Ogni ordine genera automaticamente una fattura IVA 22% via SdI (obbligatorio in Italia). XML disponibile via GET /v1/invoices/{id}; firmato con QES secondo eIDAS. Conservato 10 anni. Il webhook invoice.issued si attiva entro 60 secondi dalla notifica di SdI. L'hub di Milano processa gli ordini API in giornata se ricevuti entro le 14:00 ora locale.
FAQ
Quale autenticazione usa l'API?
OAuth 2.0 client_credentials che restituisce un token Bearer (scadenza 1 ora). Token a lunga durata per server-to-server con rotazione a 90 giorni. Supportiamo anche mTLS per clienti enterprise.
Come testare prima della produzione?
Sandbox su https://api.sandbox.corp-merch.com — parità di funzionalità, catalogo di esempio, fatture mock. Eventi webhook riproducibili per gli ultimi 30 giorni dalla dashboard.
Qual è lo SLA?
99,95% uptime sugli endpoint v1 (misurato mensilmente). Status page su status.corp-merch.com con sottoscrizioni RSS/webhook per gli incidenti.
Le fatture sono conformi alle normative italiane?
Sì — tutte le fatture instradate via SdI con IVA 22%. Formato FatturaPA XML 1.2.2, validato server-side prima dell'invio.
Come gestite i retry dei webhook?
Backoff esponenziale: 1m, 5m, 15m, 1h, 6h, 24h. Dopo 6 fallimenti la sottoscrizione si mette in pausa e avvisiamo via email. Firmati con HMAC-SHA256 nell'header X-Corp-Signature.