WooCommerce non è solo un plugin per vendere prodotti online. Sotto la superficie dellinterfaccia grafica si nasconde una REST API completa e potente che permette di leggere e scrivere dati dello store da qualsiasi applicazione esterna. Questa API apre possibilità enormi: integrazioni con gestionali ERP, app mobile personalizzate, sincronizzazione inventario con magazzini fisici, dashboard analytics custom e architetture headless commerce. Questa guida copre tutto quello che serve per iniziare a lavorare con la WooCommerce REST API.
Che cosè la WooCommerce REST API
La REST API di WooCommerce è uninterfaccia programmabile che espone i dati dello store attraverso endpoint HTTP standard. Invece di accedere al database direttamente (operazione rischiosa e sconsigliata), le applicazioni esterne comunicano con WooCommerce inviando richieste HTTP (GET, POST, PUT, DELETE) a URL specifici e ricevono risposte in formato JSON.
Per esempio, una richiesta GET a /wp-json/wc/v3/products restituisce la lista di tutti i prodotti dello store in formato JSON, con tutti i dettagli: nome, prezzo, descrizione, immagini, categorie, variazioni, stato dello stock. Una richiesta POST allo stesso endpoint crea un nuovo prodotto. Una richiesta PUT aggiorna un prodotto esistente. Una richiesta DELETE lo elimina.
LAPI segue lo standard REST, il che significa che qualsiasi linguaggio di programmazione o strumento in grado di effettuare richieste HTTP può comunicare con WooCommerce: PHP, Python, JavaScript, Java, C#, Ruby, Go, e persino strumenti no-code come Zapier o Make (ex Integromat).
Autenticazione: Consumer Key e Consumer Secret
Ogni richiesta allAPI deve essere autenticata. WooCommerce utilizza un sistema basato su Consumer Key e Consumer Secret, simile concettualmente a username e password ma specifico per l accesso API.
Per generare le chiavi, vai in WooCommerce → Impostazioni → Avanzate → REST API e clicca su “Aggiungi chiave”. Inserisci una descrizione identificativa (per esempio, “Integrazione Gestionale” o “App Mobile”), seleziona l utente WordPress associato e scegli il livello di permessi:
- Lettura — la chiave può solo leggere dati (GET)
- Scrittura — la chiave può solo scrivere dati (POST, PUT, DELETE)
- Lettura/Scrittura — accesso completo a tutte le operazioni
Dopo la generazione, WooCommerce mostra la Consumer Key e la Consumer Secret. La Consumer Secret viene mostrata una sola volta: copiala e conservala in un luogo sicuro. Se la perdi, dovrai generare una nuova coppia di chiavi.
Metodi di autenticazione
Per i siti con HTTPS (obbligatorio per qualsiasi e-commerce), l autenticazione avviene tramite HTTP Basic Auth: la Consumer Key funge da username e la Consumer Secret da password. Nella pratica, si traduce in un header Authorization: Basic base64(ck_xxx:cs_xxx) oppure, più semplicemente, passando le chiavi come parametri nellURL: ?consumer_key=ck_xxx&consumer_secret=cs_xxx.
Per i siti senza HTTPS (solo per ambienti di sviluppo locale), WooCommerce supporta l autenticazione OAuth 1.0a, un processo più complesso che genera firme crittografiche per ogni richiesta.
Panoramica degli Endpoint
La WooCommerce REST API v3 espone endpoint per tutte le entità principali dello store. Ogni endpoint segue la struttura /wp-json/wc/v3/{risorsa}.
Prodotti
Lendpoint /products gestisce lintero catalogo. Le operazioni disponibili includono:
GET /products— lista tutti i prodotti (paginata, 10 per pagina di default)GET /products/{id}— dettaglio di un singolo prodottoPOST /products— crea un nuovo prodottoPUT /products/{id}— aggiorna un prodotto esistenteDELETE /products/{id}— elimina un prodotto (sposta nel cestino)POST /products/batch— operazioni in blocco (crea, aggiorna, elimina più prodotti in una richiesta)
Sotto-endpoint correlati: /products/categories, /products/tags, /products/attributes, /products/{id}/variations per i prodotti variabili.
Ordini
Lendpoint /orders gestisce il ciclo di vita degli ordini:
GET /orders— lista ordini con filtri per stato, data, clienteGET /orders/{id}— dettaglio ordine con righe, totali, indirizzi, notePUT /orders/{id}— aggiorna lo stato dellordine (per esempio, da “in lavorazione” a “completato”)POST /orders/{id}/notes— aggiunge una nota allordinePOST /orders/{id}/refunds— emette un rimborso
Clienti
Lendpoint /customers gestisce gli account dei clienti registrati: dati anagrafici, indirizzi di fatturazione e spedizione, storico ordini e totale speso.
Coupon
Lendpoint /coupons permette di creare e gestire coupon sconto programmaticamente, utile per campagne marketing automatizzate o integrazioni con CRM esterni.
Report e impostazioni
Gli endpoint /reports forniscono dati aggregati su vendite, prodotti più venduti e clienti migliori. Lendpoint /settings permette di leggere e modificare le impostazioni dello store.
Creare un Prodotto via API
Creare un prodotto tramite API significa inviare una richiesta POST allendpoint /wp-json/wc/v3/products con un body JSON che contiene tutti i dati del prodotto. Ecco un esempio di body JSON per creare un prodotto semplice:
{
"name": "Maglietta Premium Cotone Bio",
"type": "simple",
"regular_price": "29.90",
"description": "Maglietta in cotone biologico certificato GOTS...",
"short_description": "Cotone bio, taglio regular, disponibile in 5 colori.",
"categories": [{"id": 15}],
"images": [{"src": "https://esempio.it/img/maglietta.jpg"}],
"manage_stock": true,
"stock_quantity": 100,
"sku": "MAG-PREM-001"
}
La risposta della API restituisce l oggetto prodotto completo con lID assegnato, il permalink generato e tutti i campi calcolati. I campi obbligatori sono solo name e type; tutti gli altri sono opzionali ma consigliati per un catalogo di qualità.
Per i prodotti variabili, il processo richiede due passaggi: prima crei il prodotto padre con type: "variable" e gli attributi (taglia, colore), poi crei le variazioni attraverso lendpoint /products/{id}/variations, ognuna con il proprio prezzo, SKU e stock.
Leggere gli Ordini via API
La lettura degli ordini rappresenta il caso d uso più comune per le integrazioni ERP e gestionali. Una richiesta GET a /wp-json/wc/v3/orders restituisce gli ordini con tutti i dettagli necessari per la fatturazione e la spedizione.
I filtri più utili per la lettura degli ordini includono:
?status=processing— solo ordini in lavorazione (pagati, da spedire)?after=2026-05-01T00:00:00— ordini successivi a una data specifica?per_page=50&page=2— paginazione personalizzata?customer=42— ordini di un cliente specifico?search=ORD-12345— ricerca per numero ordine
Ogni ordine nella risposta contiene le righe (line_items) con prodotto, quantità e prezzo, gli indirizzi di fatturazione e spedizione (billing, shipping), i totali (total, total_tax, shipping_total), il metodo di pagamento e le note. Questi dati sono sufficienti per generare fatture, bolle di accompagnamento e aggiornare il gestionale aziendale automaticamente.
Webhook per Notifiche in Tempo Reale
I webhook risolvono un problema fondamentale: invece di interrogare continuamente lAPI per verificare se ci sono nuovi ordini (polling), WooCommerce invia automaticamente una notifica al tuo sistema ogni volta che si verifica un evento specifico.
Per configurare un webhook, vai in WooCommerce → Impostazioni → Avanzate → Webhook oppure crealo via API con lendpoint /webhooks. Ogni webhook richiede:
- Nome — descrizione identificativa del webhook
- Stato — attivo o disattivato
- Argomento — levento che attiva la notifica (order.created, order.updated, product.created, customer.created, ecc.)
- URL di consegna — lendpoint del tuo sistema che riceverà la notifica
- Segreto — una stringa utilizzata per firmare il payload e verificarne lautenticità
Quando levento si verifica, WooCommerce invia una richiesta POST allURL di consegna con il payload JSON completo dellentità interessata. Il tuo sistema riceve i dati, li elabora e risponde con un codice HTTP 200 per confermare la ricezione.
Gli argomenti webhook più utilizzati nelle integrazioni reali sono:
order.created— nuovo ordine ricevuto (per aggiornare il gestionale)order.updated— stato ordine modificato (per tracciare il fulfillment)product.updated— prodotto modificato (per sincronizzare il catalogo esterno)customer.created— nuovo cliente registrato (per aggiornare il CRM)
Casi d Uso Pratici
Integrazione con gestionale ERP
L integrazione ERP rappresenta il caso d uso principale della WooCommerce REST API nelle aziende italiane. Il flusso tipico prevede: un webhook order.created notifica il gestionale, che importa l ordine, genera la fattura elettronica (XML conforme al formato SDI), aggiorna il magazzino e restituisce il numero di tracking a WooCommerce attraverso una richiesta PUT sullordine. Lintero processo avviene senza intervento manuale.
App mobile personalizzata
La REST API permette di costruire unapp mobile (iOS/Android) che si connette direttamente allo store WooCommerce. Lapp legge il catalogo prodotti, gestisce il carrello, processa gli ordini e mostra lo storico acquisti dellutente. Framework come React Native o Flutter rendono lo sviluppo efficiente, e la API fornisce tutti i dati necessari.
Sincronizzazione inventario multi-canale
Se vendi su più piattaforme (WooCommerce, Amazon, eBay, negozio fisico), la REST API permette di mantenere sincronizzato l inventario. Un sistema centralizzato riceve aggiornamenti da tutte le piattaforme e aggiorna le quantità di stock su WooCommerce in tempo reale, evitando overselling.
Dashboard analytics personalizzata
Gli endpoint /reports e /orders forniscono i dati grezzi per costruire dashboard personalizzate con strumenti come Grafana, Metabase o Google Data Studio. Puoi visualizzare metriche specifiche per il tuo business che WooCommerce Analytics non offre nativamente.
Headless commerce
Nel modello headless, WooCommerce funge esclusivamente da backend (gestione prodotti, ordini, pagamenti) mentre il frontend è unapplicazione separata costruita con React, Vue.js, Next.js o Nuxt. La REST API è il ponte tra i due mondi. Questo approccio offre massima libertà nel design del frontend e performance superiori, ma richiede competenze di sviluppo avanzate.
Rate Limiting e Performance
WooCommerce non implementa un rate limiting nativo, ma il server web e lhosting possono imporre limiti sulle richieste per secondo. Per evitare problemi di performance quando si lavora con volumi elevati di dati, segui queste linee guida:
- Usa le operazioni batch — lendpoint
/products/batchpermette di creare, aggiornare o eliminare fino a 100 prodotti in una singola richiesta, riducendo drasticamente il numero di chiamate API - Pagina i risultati — non richiedere mai tutti i prodotti o ordini in una sola richiesta; usa
per_pageepageper elaborare i dati in blocchi - Filtra i campi — il parametro
_fieldspermette di richiedere solo i campi necessari, riducendo la dimensione della risposta - Implementa la cache lato client — memorizza le risposte e aggiornale solo quando necessario, usando gli header
Last-ModifiedeETag - Rispetta i retry-after — se ricevi un codice HTTP 429 (Too Many Requests), attendi il tempo indicato nellheader
Retry-Afterprima di riprovare
Sicurezza delle Integrazioni API
Le chiavi API hanno accesso diretto ai dati dello store, incluse informazioni sensibili come dati dei clienti, ordini e configurazioni. La sicurezza dell integrazione risulta quindi critica.
Best practice di sicurezza
- HTTPS obbligatorio — mai esporre le chiavi API su connessioni non cifrate
- Principio del minimo privilegio — crea chiavi con solo i permessi necessari (lettura se basta la lettura)
- Una chiave per integrazione — se hai tre sistemi che accedono allAPI, crea tre coppie di chiavi separate. Se una viene compromessa, puoi revocarla senza impattare le altre
- Non inserire le chiavi nel codice sorgente — usa variabili dambiente o file di configurazione esclusi dal repository Git
- Monitora gli accessi — controlla periodicamente i log del server per identificare richieste anomale
- Ruota le chiavi periodicamente — genera nuove chiavi ogni 6-12 mesi e revoca quelle vecchie
- IP whitelisting — se possibile, limita l accesso API solo agli IP dei sistemi autorizzati tramite il firewall del server o regole nel file
.htaccess
Testare lAPI con Postman
Postman è lo strumento standard per testare le API REST prima di scrivere codice. Permette di inviare richieste HTTP, visualizzare le risposte JSON formattate e salvare collezioni di richieste per riutilizzarle.
Per configurare Postman con WooCommerce:
- Crea una nuova collezione chiamata “WooCommerce API”
- Nelle impostazioni della collezione, configura l autenticazione Basic Auth con Consumer Key e Consumer Secret
- Crea una variabile di collezione
base_urlcon valorehttps://tuosito.it/wp-json/wc/v3 - Aggiungi le richieste utilizzando
{{base_url}}/products,{{base_url}}/orders, ecc.
Postman permette anche di scrivere test automatici che verificano la correttezza delle risposte: codice HTTP, struttura JSON, valori specifici dei campi. Questa funzionalità risulta preziosa per validare che l integrazione funzioni correttamente dopo aggiornamenti di WooCommerce o del plugin di terze parti.
WP-CLI e Comandi WC
Per chi ha accesso SSH al server, WP-CLI offre uninterfaccia a riga di comando per interagire con WooCommerce senza passare dallAPI REST. Il pacchetto wp wc espone comandi per gestire prodotti, ordini, clienti e impostazioni direttamente dal terminale.
Alcuni comandi utili:
wp wc product list --user=1 — lista tutti i prodotti
wp wc product create --name="Nuovo Prodotto" --regular_price=19.90 --user=1 — crea un prodotto
wp wc order list --status=processing --user=1 — lista ordini in lavorazione
wp wc customer list --user=1 — lista clienti registrati
wp wc tool run regenerate_product_lookup_tables --user=1 — rigenera le tabelle di lookup
Il parametro --user=1 è obbligatorio: specifica l utente WordPress sotto il quale eseguire il comando (tipicamente lamministratore con ID 1). WP-CLI è particolarmente utile per operazioni di manutenzione, migrazioni di dati e automazioni server-side tramite cron job.
Costruire una Semplice Integrazione
Per illustrare concretamente il funzionamento dellAPI, consideriamo un esempio pratico: uno script PHP che legge gli ordini in lavorazione e li esporta in un file CSV per l importazione nel gestionale.
Lo script utilizza la libreria ufficiale automattic/woocommerce disponibile tramite Composer. Dopo aver configurato le credenziali API, il codice effettua una richiesta GET allendpoint ordini con filtro status=processing, itera sui risultati e scrive una riga CSV per ogni ordine con: numero ordine, data, nome cliente, email, totale, metodo di pagamento e indirizzo di spedizione.
Le librerie client ufficiali e della community semplificano enormemente lo sviluppo delle integrazioni:
- PHP —
automattic/woocommerce(Composer) - Python —
woocommerce(pip) - Node.js —
@woocommerce/woocommerce-rest-api(npm) - Ruby —
woocommerce_api(gem) - .NET —
WooCommerceNET(NuGet)
Queste librerie gestiscono automaticamente l autenticazione, la costruzione delle URL, la serializzazione JSON e la gestione degli errori, permettendoti di concentrarti sulla logica di business.
Versioning dellAPI
La WooCommerce REST API segue un sistema di versioning esplicito nellURL: /wp-json/wc/v3/ indica la versione 3, attualmente la più recente e stabile. Le versioni precedenti (v1, v2) sono ancora funzionanti ma deprecate; tutte le nuove integrazioni dovrebbero utilizzare esclusivamente la v3.
Quando WooCommerce rilascia una nuova versione dellAPI, le versioni precedenti continuano a funzionare per un periodo di transizione. Tuttavia, le nuove funzionalità e i bug fix vengono applicati solo alla versione corrente. Monitorare le note di rilascio di WooCommerce ti permette di pianificare l aggiornamento delle integrazioni con anticipo.
Un aspetto importante riguarda i campi personalizzati. Se i tuoi prodotti o ordini hanno meta dati custom (aggiunti da plugin di terze parti), questi vengono esposti nellarray meta_data della risposta API. Per aggiungere endpoint completamente nuovi o modificare quelli esistenti, puoi utilizzare i filtri WordPress woocommerce_rest_prepare_{object} e register_rest_route.
Conclusione su WooCommerce REST API
La WooCommerce REST API trasforma il tuo store da unapplicazione web isolata in un hub dati connesso con il resto dellecosistema aziendale. Che tu debba integrare un gestionale, costruire unapp mobile, sincronizzare l inventario multi-canale o implementare unarchitettura headless, lAPI fornisce tutti gli strumenti necessari. La documentazione ufficiale su woocommerce.github.io/woocommerce-rest-api-docs resta il riferimento principale per esplorare tutti gli endpoint e i parametri disponibili.
Se hai bisogno di sviluppare integrazioni personalizzate con la WooCommerce REST API, contattaci per una consulenza tecnica. Il nostro team progetta e implementa integrazioni su misura per le esigenze specifiche del tuo business.
Vuoi un e-commerce WooCommerce costruito fin dallinizio per integrarsi con i tuoi sistemi aziendali? Scopri il nostro servizio di realizzazione e-commerce professionale con architettura predisposta per le integrazioni API.