Admin API: l'interfaccia backend di Shopware 6 per ERP e automazione

L’Admin API è l’interfaccia con cui Shopware 6 viene gestito dall’esterno: prodotti, giacenze, ordini, clienti e impostazioni si possono leggere e scrivere. È il metodo standard per collegare ERP, PIM, CRM e middleware allo shop, anche per i merchant in Italia che devono integrare gestionali e processi locali.

Tutto ciò che si può fare nell’amministrazione di Shopware 6 si può fare anche tramite l’Admin API: creare prodotti, modificare giacenze, leggere ordini, aggiornare clienti, attivare cambi di stato. L’amministrazione stessa è solo un client di questa API: ogni azione nel backend è una chiamata API.

Proprio per questo l’Admin API è il metodo standard per le integrazioni con sistemi terzi. ERP, PIM, gestionale di magazzino, CRM e middleware comunicano con Shopware attraverso questa interfaccia, di solito in background e senza interazione dell’utente. È basata su REST, restituisce JSON e raggiunge tutte le entità del Data Abstraction Layer.

Shopware 6 mette a disposizione due interfacce che vengono spesso confuse:

• Admin API: per processi backend e integrazioni di sistema. Accesso completo nei limiti dei permessi assegnati, autenticazione tramite OAuth 2.0, endpoint sotto /api/.
• Store API: per i frontend rivolti ai clienti, come storefront, app o shop headless. Lavora nel contesto di un canale di vendita e di un cliente, autenticazione tramite sw-access-key, endpoint sotto /store-api/.

Regola pratica: ciò che fa un collaboratore nell’amministrazione appartiene all’Admin API. Ciò che fa un cliente nello shop appartiene alla Store API. Le differenze nel dettaglio sono spiegate nel nostro articolo su GraphQL e API REST in Shopware.

L’accesso avviene tramite OAuth 2.0. Per le integrazioni di sistema crei in Impostazioni → Sistema → Integrazioni un’integrazione con un ruolo dedicato e ottiene ID della chiave di accesso e chiave di sicurezza. Con questi dati richiede un token:

POST /api/oauth/token
{
"grant_type": "client_credentials",
"client_id": "IL_SUO_ID_CHIAVE_ACCESSO",
"client_secret": "LA_SUA_CHIAVE_DI_SICUREZZA"
}

Il token è valido dieci minuti e viene inviato come header Authorization: Bearer. Per gli strumenti che operano per conto di un utente esiste anche il grant type password con refresh token. Assegni a ogni integrazione solo i permessi di cui il processo ha bisogno: con i ruoli ACL l’accesso si può limitare fino a singole entità e operazioni. Approfondimenti sul protocollo nella voce OAuth.

• Leggere e scrivere entità: GET /api/product, POST /api/product, PATCH /api/product/{id}, DELETE /api/product/{id}, e allo stesso modo per ordini, clienti, categorie, media e tutte le altre entità.
• Ricerca con criteri: POST /api/search/product con filtri, ordinamento, paginazione, aggregazioni e associazioni. Così, ad esempio, carica tutti gli ordini di un giorno con le relative righe in un’unica chiamata.
• Sync API: POST /api/_action/sync scrive molti record di più entità in una sola richiesta. È la strada giusta per allineare giacenze e prezzi su migliaia di articoli.
• Azioni: cambi di stato tramite state machine (/api/_action/order/{id}/state/…), generazione di documenti, invio di e-mail, avvio dell’indicizzazione.
• Versioni e metadati: /api/_info/ restituisce versione, entità disponibili e schema OpenAPI; l’interfaccia Swagger su /api/_info/swagger.html documenta tutti gli endpoint.

In una tipica integrazione ERP l’Admin API gestisce questi flussi di dati:

• Articoli e prezzi: l’ERP è il sistema master, Shopware riceve anagrafiche, varianti e prezzi tramite Sync API.
• Giacenze: le giacenze vengono aggiornate a intervalli brevi o in base a eventi, perché le disponibilità nello shop siano corrette.
• Ordini: l’ERP recupera i nuovi ordini con una ricerca per criterio «stato ordine aperto e non ancora esportato» e poi li contrassegna, ad esempio tramite un campo personalizzato. In Italia è da qui che di solito parte la fatturazione elettronica tramite SDI, gestita dall’ERP o dal gestionale.
• Stati e numeri di tracking: stato di spedizione e di pagamento vengono riscritti tramite azioni della state machine, i numeri di tracking vengono associati alla consegna.

Invece di interrogare il sistema a intervalli, può farsi notificare da Shopware: i webhook segnalano nuovi ordini o prodotti modificati, e l’integrazione carica solo ciò che è cambiato. Quali sistemi si possono collegare in questo modo lo mostra la nostra panoramica su integrazioni ERP e CRM, un esempio concreto è la guida a Xentral e Shopware 6.

• Sync API per i dati massivi: le singole chiamate per articolo sono troppo lente con cataloghi grandi; raggruppi le scritture in pacchetti di alcune centinaia di record.
• Trasferire solo le modifiche: con filtri updatedAt o webhook trasferisce solo le differenze invece dell’intero archivio.
• Lavorare in modo idempotente: usi ID fissi (UUID) dal sistema master, così le chiamate ripetute non creano duplicati.
• Gestire gli errori: la Sync API segnala gli errori per singolo record; registri e ripeta in modo mirato le voci non riuscite.
• Attenzione all’indicizzazione: dopo import di grandi dimensioni gli indexer girano tramite la message queue; il worker deve essere attivo, altrimenti i dati compaiono nello shop in ritardo.
• Permessi e secret: un’integrazione dedicata per ogni sistema, ruolo minimo, chiavi in un secret store, rotazione regolare.

• 401 Unauthorized: token scaduto o credenziali errate. Rinnovare il token, verificare l’integrazione.
• 403 Forbidden: il ruolo dell’integrazione non ha il permesso per questa entità o operazione.
• 400 in scrittura: mancano campi obbligatori o i tipi di dato non corrispondono; il messaggio di errore indica campo e percorso.
• I dati non compaiono nello shop: indexer o cache. Verificare il worker della message queue, svuotare la cache.
• Import lenti: chiamate singole invece della Sync API o pacchetti troppo grandi; con l’header indexing-behavior: use-queue-indexing l’indicizzazione si sposta nella coda.

L’Admin API è la spina dorsale di ogni integrazione Shopware. Chi ne comprende la logica, con OAuth 2.0, ricerca con criteri, Sync API e state machine, può collegare ERP, PIM e CRM in modo affidabile. Per integrazioni personalizzate e plugin che estendono l’Admin API con endpoint propri, supportiamo anche merchant in Italia con lo sviluppo di plugin Shopware.