Shopify · ERP · E-commerce
Integrare Shopify con l'ERP: ordini, stock e catalogo
Shopify è una delle piattaforme e-commerce più diffuse, ma da solo non parla con il gestionale. Integrare Shopify con l'ERP significa tenere allineati catalogo, stock e ordini in modo affidabile, evitando il doppio inserimento e gli errori manuali.
Gli strumenti di Shopify
| Strumento | Uso |
|---|---|
| Admin GraphQL API | Leggere/scrivere prodotti, inventario, ordini |
| Webhook | Notifiche di eventi (ordini, aggiornamenti) |
| Bulk Operations | Estrazioni e modifiche su grandi volumi |
La Admin GraphQL API è oggi la via principale; i webhook abilitano flussi event-driven; le bulk operations servono per cataloghi grandi.
Gli ordini: meglio i webhook
Per importare gli ordini, i webhook (es. orders/create) sono preferibili al polling: Shopify notifica l'evento, l'integrazione lo accoda e un worker crea l'ordine in ERP. Due accortezze indispensabili:
- verifica della firma HMAC per accettare solo webhook autentici;
- idempotenza: i webhook possono ripetersi, quindi si deduplica per id ordine.
Stock e catalogo
Lo stock va sincronizzato a livello di inventory item e location: Shopify gestisce le giacenze per sede. Dall'ERP si propagano le quantità (con buffer anti-overselling) e dal catalogo si allineano prodotti, varianti e prezzi. Conviene lavorare per delta ed evitare di riscrivere l'intero catalogo a ogni ciclo.
Mappare prodotti e varianti
Le varianti Shopify (per opzioni come taglia/colore) vanno mappate sugli SKU del gestionale. È utile mantenere un legame stabile tra SKU ERP e variant id Shopify, così gli aggiornamenti colpiscono sempre l'entità giusta senza ambiguità.
Architettura event-driven su Azure
Una integrazione robusta su Microsoft Azure: un endpoint (Azure Function) che riceve i webhook, ne verifica la firma e li accoda su Service Bus; worker che creano ordini in ERP, propagano stock e catalogo verso Shopify con retry e rate limiting; gestione sicura dei token in Key Vault; osservabilità con correlation ID.
Rate limit di Shopify
Shopify applica limiti (con costo per query nella GraphQL API). Vanno gestiti con throttling e backoff, monitorando il costo residuo restituito dall'API per non superare il budget. Le bulk operations aiutano a ridurre il numero di chiamate per i grandi volumi.
Esempio pratico: mapping SKU e aggiornamento stock
Il dato più importante da salvare non è solo lo SKU, ma la relazione tra SKU ERP, variantId, inventoryItemId e location Shopify. Senza questa tabella gli aggiornamenti stock diventano ambigui appena hai varianti o più magazzini.
{
"erpSku": "TSHIRT-BLK-M",
"shopifyVariantId": "gid://shopify/ProductVariant/431234567890",
"inventoryItemId": "gid://shopify/InventoryItem/9876543210",
"locationId": "gid://shopify/Location/123456789",
"safetyBuffer": 2
}Un aggiornamento ERP da 17 pezzi disponibili diventa quindi 15 pezzi pubblicabili, se il buffer anti-overselling è 2. La mutation GraphQL deve essere emessa solo quando la quantità calcolata cambia davvero.
mutation inventorySetQuantities($input: InventorySetQuantitiesInput!) {
inventorySetQuantities(input: $input) {
inventoryAdjustmentGroup { createdAt reason }
userErrors { field message }
}
}Gestione reale dei webhook duplicati
Per orders/create salvo sempre l'header X-Shopify-Webhook-Id e l'id ordine. Se lo stesso webhook rientra entro 48 ore, rispondo 200 ma non ricreo l'ordine. Se invece cambia solo lo stato dell'ordine, genero un evento separato di aggiornamento.
Errori comuni
- webhook senza verifica HMAC e senza idempotenza;
- stock sincronizzato senza tenere conto delle location;
- riscrittura completa del catalogo invece dei delta;
- nessun legame stabile tra SKU ERP e variant id.
Conclusione
Integrare Shopify con l'ERP è soprattutto questione di eventi affidabili e mapping stabile: webhook firmati e idempotenti per gli ordini, sincronizzazione di stock per location e catalogo per delta, il tutto su un'architettura event-driven. Documentazione ufficiale: Shopify Admin GraphQL API.