By
·
6 minute read
Quasi tutti i problemi dell'API WooCommerce legati alle spedizioni nascono da quattro cause: credenziali senza permessi di scrittura, la Legacy API disattivata, un server che blocca le richieste PUT, oppure dati del corriere in un formato che l'API non accetta. Nessuno di questi è un bug di WooCommerce. Ed è proprio per questo che i ticket rimbalzano per giorni tra il vostro store e il corriere, senza che nessuna delle due parti trovi nulla di rotto.
Qui trovate come capire in quale dei quattro casi vi trovate, e come una connessione API gestita ne elimini la maggior parte.
Punti Chiave
- WooCommerce non modifica i propri ordini attraverso la sua REST API. Se uno stato cambia da solo, l'ha scritto un sistema esterno.
- Un 401 significa che le credenziali sono sbagliate o revocate. Un 403 significa che sono valide ma non autorizzate a fare quell'operazione.
- Le chiavi API in sola lettura sono una causa frequente di ordini che si importano ma non si aggiornano mai.
- Il blocco del metodo PUT lato server e i timeout a 60 secondi generano errori che sembrano casuali, ma non lo sono.
- ShippyPro collega WooCommerce tramite un'integrazione gestita e può ritentare in automatico gli ordini falliti.
Perché l'API WooCommerce smette di funzionare
Un caso discusso sul forum di supporto WooCommerce mostra bene lo schema. Un merchant si ritrovava ordini segnati come "Completato" mentre gli stessi pacchi erano ancora fermi nel pannello del corriere. Il corriere dava la colpa a WooCommerce, WooCommerce dava la colpa al corriere, e il merchant è rimasto in mezzo per due settimane. A chiarire tutto è stato il log. Ogni cambio di stato portava allo stesso punto:
woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php → update_itemCosa significa davvero
WooCommerce non aggiorna i propri ordini tramite la sua REST API. Se un cambio di stato arriva da update_item, l'ha inviato un sistema esterno. Ogni scrittura verso la REST API di WooCommerce è una richiesta autenticata che proviene da fuori dallo store: la domanda quindi non è mai "WooCommerce è rotto", ma "quale integrazione ha inviato questa chiamata, e perché". Partite dai log dei webhook in uscita del vostro fornitore e nella maggior parte dei casi avrete la risposta in pochi minuti.
Quattro controlli prima di aprire un ticket
Eseguiteli in questo ordine. Nella maggior parte dei casi l'errore sparisce già al terzo passaggio.
WooCommerce > Impostazioni > Avanzate > Legacy API. L'attivazione deve essere fatta da un account amministratore.
WooCommerce > Impostazioni > API > Chiavi/App. Aprite la chiave esistente e modificate il permesso.
Molti hosting permettono GET e POST ma bloccano PUT. Per riscrivere i dati di tracking servono tutti e tre.
Controllate che i webhook siano attivi in WooCommerce > Impostazioni > Avanzate > WebHooks, e inserite l'URL base nel formato https://www.vostrostore.it.
Se usate WooCommerce versione 9, vi serve l'estensione ufficiale Legacy REST API di WooCommerce prima che la connessione possa funzionare. Attenzione però: questa estensione non è compatibile con HPOS, quindi verificate quale sistema di archiviazione ordini usa il vostro store prima di installarla.
Cloudflare e i firewall lato server spesso bloccano il traffico delle integrazioni senza restituire un errore comprensibile. Gli IP di ShippyPro sono dinamici, quindi non esiste una lista fissa da autorizzare. Create invece una regola che permetta il traffico con User Agent impostato su "ShippyPro".
Prodotto & Risorse
Shipping Platform
Importate gli ordini WooCommerce, generate le etichette BRT, GLS e Poste Italiane e riportate il tracking da un'unica dashboard.
Esplora la piattaforma →Automazione Spedizioni IA
Ritentate gli ordini falliti, correggete i dati del destinatario e riassegnate il corriere senza intervento manuale.
Scopri l'automazione →Track & Trace
Mantenete il tracking coerente su tutti i corrieri, così lo stato dell'ordine corrisponde a quello che succede davvero.
Scopri Track & Trace →Documentazione API ShippyPro
Autenticazione, endpoint ed eventi webhook per collegare i vostri sistemi in modo diretto.
Consulta la documentazione →Smettete di fare debug dell'API WooCommerce
Collegate lo store una volta sola e lasciate che sia l'integrazione a gestire credenziali, tentativi e tracking.
Gli errori più comuni dell'API WooCommerce e come risolverli
Prima di toccare qualsiasi impostazione, distinguete i due tipi di errore. Un 401 significa che le credenziali sono state rifiutate. Un 403 significa che sono valide, ma l'utente collegato non può eseguire quell'operazione. Trattare un problema di permessi come un problema di credenziali è il motivo per cui certi team generano una chiave dopo l'altra senza cambiare nulla.
| Errore | Cosa sta succedendo davvero | Soluzione |
|---|---|---|
| The consumer key is not valid (HTTP 401) | Credenziali rifiutate o revocate | Create una nuova connessione WooCommerce con l'opzione "Use Consumer and Secret Keys" attiva |
| CURL error 28: operation timed out after 60001 ms | Il vostro hosting ha raggiunto ShippyPro ma non ha ricevuto risposta entro 60 secondi | Riprovate la connessione più tardi |
| Params.from_address.country: must be at most 2 characters long | Paese di origine salvato per esteso invece che come codice | Impostatelo in formato ISO (IT, ES, DE) in WooCommerce > Spedizioni > ShippyPro Live Shipping Rates |
| Missing parameter app_name | L'URL di autorizzazione non contiene app_name | Rigenerate la connessione in modo che app_name sia presente nell'URL |
| /wc-auth/v1/authorize was not found on this server | L'indirizzo dello store è errato | Verificate l'indirizzo dello store salvato nel profilo WooCommerce |
| Gli ordini si importano con l'indirizzo sbagliato | Il campo indirizzo di spedizione è vuoto | ShippyPro importa l'indirizzo di spedizione WooCommerce e usa quello di fatturazione solo quando il primo è vuoto |
ShippyPro classifica i messaggi di errore dei corrieri in cinque tipi e associa a ciascuno una descrizione e una soluzione: un'etichetta fallita vi dice cosa fare, non solo che qualcosa è andato storto. Se lavorate direttamente con le API, la sezione API del vostro account conserva lo storico delle chiamate fallite sotto View API Errors, e uno Status pari a 2 nella risposta della Ship indica che la chiamata è partita ma l'etichetta non è stata creata.
Quando le richieste vanno in timeout
Le richieste di spedizione che finiscono in timeout restituiscono un 500 anche quando l'etichetta è stata creata. Per evitarlo, inviate la chiamata Ship con il parametro Async impostato su true. Ricevete subito una risposta OK con un numero d'ordine, poi recuperate l'etichetta con GetLabelURL o tramite il webhook Order Shipped, una volta che il corriere l'ha generata.
API dirette o connessione gestita?
Entrambi gli approcci funzionano, e WooCommerce mette a disposizione anche una shipping method API per i plugin che aggiungono tariffe proprie. La differenza sta in come falliscono, ed è questa la parte da valutare prima di impegnare tempo di sviluppo.
| Criterio | Chiamate API dirette al corriere | Connessione gestita |
|---|---|---|
| Autenticazione | Credenziali e logica di refresh separate per ogni corriere | Una sola connessione, credenziali gestite centralmente |
| Recupero etichette fallite | Manuale, quando qualcuno se ne accorge | Auto-Retry, oppure un workflow con trigger "Ordine in errore" |
| Dati destinatario errati | Correzione e reinvio a mano, ordine per ordine | L'azione Autofix recipient info corregge e ritenta l'etichetta |
| Aggiunta di un corriere | Un nuovo progetto di integrazione ogni volta | Attivazione dalla libreria integrazioni |
| Dove emergono gli errori | Nei vostri log, se qualcuno li controlla | In una vista Errori dedicata, con la soluzione documentata |
Dove se ne va davvero il tempo
Il costo di un'integrazione fatta in casa non è quasi mai il primo sviluppo. È la manutenzione: un corriere cambia un campo obbligatorio, un indirizzo supera il limite di caratteri, un timeout fa saltare un lotto di etichette alle 23. Una connessione gestita assorbe questa categoria di problemi, e potete comunque usare le API dirette per tutto ciò che è davvero su misura.
Quando una chiamata fallisce, salvate lo status code e il messaggio, e lasciate fuori la consumer secret. Non passate mai i secret nell'URL e non allargate i permessi di un utente solo per far sparire un errore. Se un ruolo più ampio risolve il problema, avete confermato che si tratta di permessi, non lo avete risolto.
Perché WooCommerce segna gli ordini come Completati prima della spedizione?
Non è WooCommerce a farlo. È un'integrazione esterna che invia una scrittura via REST API. Controllate i log dei webhook in uscita del vostro fornitore di spedizioni per individuare la chiamata.
Cosa causa l'errore 401 della REST API di WooCommerce?
Una consumer key non valida o revocata, oppure un header Authorization che non arriva a destinazione perché la richiesta non viaggia su HTTPS.
Perché l'API WooCommerce non funziona dopo la configurazione?
Di solito la Legacy API è disattivata, la chiave API è in sola lettura, oppure il server blocca il metodo PUT. Verificate questi tre punti prima di guardare il codice.
Come si risolve un timeout dell'API WooCommerce?
Un CURL error 28 indica che nessuna risposta è arrivata entro 60 secondi: riprovate più tardi. Per le richieste di etichetta inviate via API, usate la chiamata Ship con il parametro Async impostato su true, così la richiesta non va in timeout.
Articoli correlati
Le migliori piattaforme di spedizione per e-commerce nel 2026
Come scegliere la piattaforma giusta per corrieri, volumi e integrazioni del vostro store.
Leggi di più →Le 5 migliori piattaforme di automazione spedizioni nel 2026
Confronto su profondità dell'automazione, accesso API e copertura dei corrieri italiani.
Leggi di più →Automazione spedizioni: vantaggi e 10 applicazioni per il 2026
Dove l'automazione incide davvero sulla gestione ordini e sugli errori di spedizione.
Leggi di più →Risorse e guide sulle spedizioni
Guide pratiche su gestione corrieri, automazione e operazioni post-vendita.
Sfoglia le risorse →Collegate WooCommerce una volta e smettete di rincorrere gli errori
Provate ShippyPro gratis per 14 giorni. Senza carta di credito.
Come Growth Manager di ShippyPro, aiuto le aziende ecommerce a ottimizzare la gestione delle spedizioni, automatizzare i flussi logistici e scalare in modo più efficiente. Il mio lavoro si concentra sull’intersezione tra operations ecommerce, customer experience e tecnologia. Scrivo di innovazione nel settore delle spedizioni, automazione e futuro della logistica per l’ecommerce.
