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.
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_itemWooCommerce 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.
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
Importate gli ordini WooCommerce, generate le etichette BRT, GLS e Poste Italiane e riportate il tracking da un'unica dashboard.
Esplora la piattaforma →Ritentate gli ordini falliti, correggete i dati del destinatario e riassegnate il corriere senza intervento manuale.
Scopri l'automazione →Mantenete il tracking coerente su tutti i corrieri, così lo stato dell'ordine corrisponde a quello che succede davvero.
Scopri Track & Trace →Autenticazione, endpoint ed eventi webhook per collegare i vostri sistemi in modo diretto.
Consulta la documentazione →Collegate lo store una volta sola e lasciate che sia l'integrazione a gestire credenziali, tentativi e tracking.
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.
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.
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 |
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.
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.
Una consumer key non valida o revocata, oppure un header Authorization che non arriva a destinazione perché la richiesta non viaggia su HTTPS.
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.
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
Come scegliere la piattaforma giusta per corrieri, volumi e integrazioni del vostro store.
Leggi di più →Confronto su profondità dell'automazione, accesso API e copertura dei corrieri italiani.
Leggi di più →Dove l'automazione incide davvero sulla gestione ordini e sugli errori di spedizione.
Leggi di più →Guide pratiche su gestione corrieri, automazione e operazioni post-vendita.
Sfoglia le risorse →Provate ShippyPro gratis per 14 giorni. Senza carta di credito.