Mantenere l'inventario accurato e aggiornato è fondamentale per qualsiasi rivenditore ad alto volume. Per Wellcare e Raf Pharmacy—due catene di farmacie leader in Qatar con oltre 10.000 SKU, 100+ negozi fisici, e vendite attive su negozi web Shopify, app mobili, e sistemi POS—abbiamo costruito una soluzione robusta di aggiornamento stock ERP-to-Shopify in tempo reale. Di seguito, condividiamo la nostra architettura end-to-end, frammenti di codice e risultati delle prestazioni.

Ambito del Progetto & Sfide

  • Clienti: Wellcare Pharmacy e Raf Pharmacy, Qatar
  • Dimensione del Catalogo: 10.000+ SKU
  • Canali di Vendita: Negozio Shopify, app mobili headless, oltre 100 sedi fisiche
  • ERP: INNSOF ERP che spinge gli aggiornamenti di magazzino
  • Requisiti:
    • Sincronizzazione in tempo reale per prevenire sovrasvendite
    • Scalabile per un alto volume di aggiornamenti
    • Latenza API e errori minimi
    • Gestione accurata delle scorte in più sedi

1. Approccio Iniziale: Shopify REST API

Abbiamo prima utilizzato l'endpoint dell'API REST Admin di Shopify /admin/api/2024‑01/inventory_levels/set.json per inviare aggiornamenti di stock.

// Sample REST payload
$payload = [
  'location_id'      => $locationId,
  'inventory_item_id'=> $inventoryItemId,
  'available'        => $newStock
];
$response = $this->shopifyService->restRequest('POST', "/inventory_levels/set.json", $payload);

Limitazioni delle API REST

  • Nessun aggiornamento in batch: Un SKU per richiesta
  • Limiti di velocità rigorosi: ~2 chiamate/sec per negozio → collo di bottiglia per migliaia di SKU
  • Alta latenza: 50–100 ms per richiesta, ritardi accumulati
  • Errore-prone: Errori di limite di frequenza frequenti sotto carico

2. Migrazione all'API GraphQL di Shopify

Per superare le limitazioni di REST, siamo passati a GraphQL Admin API di Shopify, sbloccando:

  • Aggiornamenti batch con inventoryAdjustQuantities mutation
  • Limitazione basata sui costi (più flessibile rispetto a REST)
  • Riduci il sovraccarico di rete richiedendo solo i campi necessari
  • Regolazioni basate su Delta (aggiorna solo quando il titolo cambia effettivamente)

3. Panoramica dell'Architettura

  1. ERP → Middleware
    • INNSOF ERP invia un payload JSON tramite HTTP POST al nostro StockController.
  2. Arricchimento & Registrazione
    • Analizziamo, convalidiamo e registriamo la richiesta in un DB locale (api_request_log).
    • Arricchiamo ogni SKU con location_id e inventory_item_id (dalle tabelle memorizzate nella cache).
  3. Ottieni Stock Corrente
    • Recupera i livelli di stock esistenti tramite GraphQL (per posizione e SKU).
  4. Calcola Deltas
    • Confronta le scorte ERP con le scorte di Shopify per determinare delta.
  5. Regola l'inventario
    • Invia una singola mutazione GraphQL per batch (fino a 100 SKU).
  6. Gestione delle Risposte
    • Registra successi/fallimenti e invia lo stato di aggiornamento all'ERP.
  7. Ritenti & Ripristino
    • I lavori cron automatizzati riprovano i batch non riusciti; ripristino a REST se necessario.

4. Recupero delle Azioni Correnti tramite GraphQL

Il calcolo del delta accurato inizia con il recupero delle quantità esistenti. Raggruppiamo fino a 60 articoli per query:

query inventoryItems {
  item1: inventoryItem(id: "gid://shopify/InventoryItem/123456789") {
    id
    tracked
    sku
    inventoryLevels(first: 10) {
      edges {
        node {
          location { id name }
          quantities(names: "available") {
            quantity
          }
        }
      }
    }
  }
  # item2, item3… up to 60
}

Il nostro metodo PHP raccoglie questi in un array:

private function getCurrentStock(array $products): array {
    $batches = array_chunk($products, 60);
    $results = [];
    foreach ($batches as $batch) {
        // Build GraphQL query dynamically…
        $response = $this->shopifyService->executeGraphQl($query, []);
        // Parse `$response['data']` into $results[]
    }
    return $results;  // [ ['inventory_item_id'=>…, 'location_id'=>…, 'quantity'=>…], … ]
}

5. Regolazione dell'inventario tramite GraphQL

Una volta che conosciamo l'attuale stock, prepariamo il delta payload di aggiornamento:

Modello di Mutazione

mutation AdjustMultipleInventoryQuantities($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      createdAt
      changes { name delta }
    }
    userErrors { field message }
  }
}

Formato delle variabili PHP

$changes = [];
foreach ($updatedProducts as $p) {
    $changes[] = [
      'inventoryItemId'=> "gid://shopify/InventoryItem/{$p['inventory_item_id']}",
      'locationId'     => "gid://shopify/Location/{$p['location_id']}",
      'delta'          => $p['erp_stock'] - $p['current_stock']
    ];
}

$variables = [
  'input' => [
    'reason'               => 'correction',
    'name'                 => 'available',
    'referenceDocumentUri' => 'logistics://erp/batch-2025-07-29',
    'changes'              => $changes
  ]
];

$response = $this->shopifyService->executeGraphQl($mutation, $variables);

Questa singola chiamata aggiorna fino a 100 SKU alla volta, riducendo significativamente il traffico di rete.

6. Punti salienti dell'ottimizzazione

  • Batching & Chunking: 60 elementi/query per letture; 100 elementi/mutazione per scritture.
  • Cache Locale: Memorizza inventory_item_id & location_id in MySQL per evitare ricerche ripetitive.
  • Delta Logic: Aggiorna solo gli SKU il cui stock attuale differisce dallo stock ERP.
  • Consapevolezza del limite di velocità: Inserire sleep()/usleep() in modo strategico e tornare a REST per tentativi urgenti.
  • Registrazione Robusta: Ogni richiesta e risposta è registrata nelle tabelle api_request_log e stock_update_log.

7. Confronto delle Prestazioni

MetricoREST APIAPI GraphQL
Supporto per aggiornamenti batch❌✅
Tempo medio per 100 SKU~60 s~5 s
Errori di limitazione della velocità (sotto carico)FrequenteRaro
Precision in tempo realeModeratoAlto
Integrazione del feedback ERPParzialeCompleto, registrato

8. Tecnologie & Strumenti

  • Shopify GraphQL Admin API
  • PHP (StockController) con ShopifyService, LogManager, DBOps, ApiService
  • MySQL per la cache locale e i log
  • INNSOF ERP webhook
  • Cron Jobs per i tentativi e i callback ERP

9. Vantaggi per Wellcare & Raf Pharmacy

  • 🔄 Accuratezza dei stock in tempo reale in oltre 100 negozi e canali
  • 🚫 Nessun oversell e un'esperienza cliente senza soluzione di continuità
  • ⚡ Alta capacità di elaborazione: migliaia di aggiornamenti SKU all'ora
  • 🔍 Traccia audit dettagliata per la conformità e il debug
  • 📈 SEO e UX migliorati sui negozi online e mobili

10. Domande Frequenti

  1. Perché recuperare lo stock attuale prima di aggiornare?
    Assicura che calcoliamo il delta corretto, prevenendo sovrascritture accidentali o aggiustamenti duplicati.
  2. Quanti SKU può gestire GraphQL in un batch?
    Fino a 100 SKU per mutazione e 60 per query, configurabile in base al piano del negozio.
  3. Posso mescolare REST e GraphQL?
    Sì. Manteniamo REST come opzione di riserva per aggiornamenti critici quando GraphQL è limitato.
  4. Funziona l'inventario multi-sede?
    Assolutamente. Interroghiamo e aggiorniamo i livelli per sede utilizzando locationId.
  5. Questo approccio è adattabile ad altri ERP?
    Sì. Il nostro design modulare può integrarsi con Odoo, SAP, Oracle 6i e altro ancora.

Perché scegliere le soluzioni e-commerce di Seamedia?
In Seamedia, combiniamo una profonda esperienza in Shopify con una solida conoscenza dell'integrazione ERP per offrire soluzioni personalizzate e ad alte prestazioni che generano risultati concreti per il business. Il nostro team—guidato da consulenti esperti come Prajosh VM—comprende le complessità dell'inventario multi-sede, dei volumi elevati di SKU e del retail omnicanale. Progettiamo flussi di lavoro scalabili e guidati da API che mantengono il tuo stock accurato, i tuoi clienti soddisfatti e le tue operazioni efficienti. Che tu sia una catena di farmacie in rapida crescita, un rivenditore nazionale o un produttore di grandi dimensioni, Seamedia offre sviluppo end-to-end, connettività ERP senza soluzione di continuità e supporto 24/7.

Pronto a semplificare il tuo inventario e potenziare le tue vendite?
Contattaci oggi a hello@seamedia.in o visita www.seamedia.in per discutere di come possiamo costruire una soluzione personalizzata di sincronizzazione delle scorte in tempo reale per la tua azienda.