Shopware offre due interfacce REST, la Store-API e la Admin-API, ma nessuna API GraphQL ufficiale. Mostriamo autenticazione e richieste di esempio per entrambe e valutiamo cosa offrono progetti GraphQL come SwagGraphQL, con indicazioni utili per gli shop in Italia.
REST (Representational State Transfer) è uno stile architetturale per applicazioni in rete. Le API REST si interrogano via HTTP e le operazioni più comuni passano per i metodi GET (lettura), POST (creazione), PATCH o PUT (modifica) e DELETE (eliminazione). Shopware 6 mette a disposizione due interfacce REST, le stesse che usano anche i merchant in Italia per collegare frontend, gestionali e strumenti di marketing:
Entrambe le interfacce scambiano dati in formato JSON e restituiscono l’esito tramite codici di stato HTTP, ad esempio 200 per una richiesta riuscita o 401 per autorizzazione mancante. Le sezioni seguenti mostrano autenticazione e richieste di esempio. Le basi della piattaforma sono descritte nella nostra pagina dedicata allo sviluppo Shopware.
La Store-API è l’accesso alla storefront di Shopware. Ecco come autorizzarsi e inviare le prime richieste.
La Store-API richiede una sw-access-key legata a un canale di vendita:
https://il-tuo-shop.it/admin.Shopware include un’interfaccia Swagger per testare la Store-API:
https://il-tuo-shop.it/store-api/_info/swagger.html.sw-access-key e confermi.A questo punto può provare tutti gli endpoint direttamente nel browser.
Per ottenere un elenco di prodotti si invia una richiesta POST a /store-api/product. La Store-API accetta nel body criteri di ricerca come limite, filtri e ordinamento. Con cURL:
curl -X POST https://il-tuo-shop.it/store-api/product \
-H "sw-access-key: LA_TUA_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'La risposta è un JSON con un array elements che contiene i prodotti con nome, prezzo e ID:
{
"elements": [
{
"id": "0190d2e8f2b47c6f9d1a0c5e8b3f1a2b",
"name": "Prodotto di esempio",
"calculatedPrice": { "totalPrice": 19.99 },
"stock": 100
}
],
"total": 1
}Gli shop headless funzionano interamente tramite queste interfacce. La scelta tra REST e GraphQL è quindi una decisione architetturale: REST è maturo ed è supportato dagli strumenti ufficiali di Shopware, GraphQL consente un caricamento dei dati più flessibile per frontend complessi, ma in Shopware non ha uno status ufficiale (ne parliamo più avanti).
La Admin-API è pensata per le integrazioni di backend e dà accesso ai dati anagrafici di Shopware. Utilizza OAuth 2.0.
Con le credenziali dell’integrazione richiede un token tramite POST /api/oauth/token:
curl -X POST https://il-tuo-shop.it/api/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "IL_TUO_ID_CHIAVE_DI_ACCESSO",
"client_secret": "LA_TUA_CHIAVE_DI_SICUREZZA"
}'La risposta contiene un token valido per dieci minuti:
{
"token_type": "Bearer",
"expires_in": 600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}Con il token può interrogare la Admin-API. Un elenco di prodotti si ottiene con GET /api/product:
curl -X GET https://il-tuo-shop.it/api/product \
-H "Authorization: Bearer IL_TUO_ACCESS_TOKEN" \
-H "Content-Type: application/json"La giacenza si modifica con una richiesta PATCH a /api/product/{id-prodotto}:
curl -X PATCH https://il-tuo-shop.it/api/product/0190d2e8f2b47c6f9d1a0c5e8b3f1a2b \
-H "Authorization: Bearer IL_TUO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "stock": 150 }'Per le modifiche massive la Admin-API offre l’endpoint di sincronizzazione POST /api/_action/sync, che scrive molti record in una sola chiamata. Se preferisce essere avvisato delle modifiche invece di interrogare il sistema, legga il nostro articolo sui webhook in Shopware 6.
GraphQL è un linguaggio di interrogazione in cui il client specifica esattamente quali dati gli servono. Si evita così l’over-fetching e si può ottenere più efficienza rispetto a REST. Invece di tanti endpoint ne esiste uno solo, di solito /graphql. Shopware però non offre un’API GraphQL ufficiale. GraphQL si può aggiungere solo tramite progetti della community come SwagGraphQL.
SwagGraphQL è un proof of concept di shopwareLabs che sovrappone un’API GraphQL all’API core di Shopware. Si basa sulla libreria webonyx/graphql-php ed è integrato come plugin in Shopware 6. Il progetto non è più mantenuto, è stato sviluppato per le prime versioni di Shopware 6 e non andrebbe usato in produzione senza adattamenti consistenti.
Per provarlo in un ambiente di sviluppo:
# Clonare il repository nella cartella dei plugin
git clone https://github.com/shopwareLabs/SwagGraphQL.git custom/plugins/SwagGraphQL
# Installare le dipendenze del plugin
cd custom/plugins/SwagGraphQL && composer install && cd -
# Registrare e attivare il plugin
bin/console plugin:refresh
bin/console plugin:install --activate SwagGraphQL
bin/console cache:clearDopo l’installazione l’endpoint è raggiungibile all’indirizzo https://il-tuo-shop.it/graphql/query e si può interrogare con strumenti come GraphiQL. Una query sui prodotti si presenta così:
query {
products {
id
name
price
}
}Chi ha bisogno di GraphQL nel frontend in pratica costruisce un proprio livello: un BFF (Backend for Frontend) in Node.js o PHP che espone GraphQL verso l’esterno e internamente richiama Store-API e Admin-API. Piattaforme middleware come Alumio collegano Shopware a sistemi basati su GraphQL, ma non sostituiscono un’API GraphQL nativa nel core di Shopware. Per automazioni semplici tra sistemi spesso basta anche n8n.
sw-access-key manca, è errata o appartiene a un altro canale di vendita./store-api/product.includes e associations), paginare i risultati, mettere in cache le risposte.Con Store-API e Admin-API Shopware copre interamente via REST il collegamento di frontend personalizzati e sistemi esterni. Un’API GraphQL ufficiale non esiste e progetti della community come SwagGraphQL sono adatti solo a esperimenti. Chi ha bisogno di GraphQL nel frontend antepone un proprio livello alle interfacce REST. Configurate correttamente e gestite secondo le regole descritte, le API di Shopware sono la base per frontend headless, sincronizzazioni con il CRM e automazioni, anche per i merchant in Italia che collegano gestionale e fatturazione elettronica. Se per questo Le serve un plugin o un’app, La supportiamo con lo sviluppo di plugin Shopware; una prima panoramica del Suo shop la offre la nostra analisi dello shop.