Vai al contenuto principale
Torna in alto

Domande frequenti sulle API di Sendcloud

Louise Thomasson
  • Aggiornato
🤖Articolo tradotto con IA

Argomento: In questo articolo rispondiamo alle domande più frequenti relative alle integrazioni personalizzate dei negozi che utilizzano le API di Sendcloud.

Quali sono i limiti di richiesta (rate limits)?

Le richieste alla nostra API sono limitate per ciascun account Sendcloud. Se disponi di più chiavi API per lo stesso account Sendcloud, il limite viene condiviso tra queste chiavi.

Limiti di richiesta

La nostra API prevede dei rate limits che limitano il numero di richieste effettuabili al minuto. Tieni presente che esistono limiti differenti per gli endpoint relativi alle spedizioni.

  • Richieste sicure (GET): 1000 richieste al minuto
  • Richieste non sicure (POST/PATCH/PUT/DELETE): 100 richieste al minuto.

Burst massimo

Gli endpoint considerati non sicuri prevedono un limite di burst, ovvero il numero massimo di richieste simultanee che l’API può gestire. Questo consente un aumento temporaneo della frequenza delle richieste per gestire brevi periodi di traffico elevato senza superare i limiti complessivi.

  • Richieste non sicure (POST/PATCH/PUT/DELETE): 15 richieste al secondo.
Per evitare interruzioni e mantenere un utilizzo ottimale dell’API, è fondamentale rispettare i limiti di richiesta. Se il limite viene superato, riceverai una risposta HTTP 429 (Too Many Requests).

Per maggiori informazioni sui limiti di richiesta, consulta la nostra documentazione per sviluppatori.

Queste informazioni possono essere soggette a modifiche a discrezione di Sendcloud.

Voglio creare le etichette immediatamente quando creo una spedizione tramite API. Come posso fare?

Per creare spedizioni ed etichette di spedizione con una sola chiamata API, utilizza l’endpoint sincrono delle Shipments oppure della Ship an Order API. L’etichetta verrà restituita automaticamente nella risposta nel campo data.parcels.label_file. Questa funzionalità è disponibile solo per spedizioni Single Collo (spedizioni composte da un solo pacco).

Come posso mantenere l’idempotenza per ordini/spedizioni che importo o creo in Sendcloud?

Nel contesto delle API, l’idempotenza indica che effettuare più richieste produce lo stesso effetto di una singola richiesta. Questo serve a prevenire errori utente e, nel caso delle API Sendcloud, la duplicazione degli ordini nel nostro sistema. Ci sono quattro endpoint che cercano di essere idempotenti:

  • Tutti gli endpoint POST delle shipments
    Utilizza il campo external_reference_id  per mantenere l’idempotenza. 

Posso utilizzare le regole di spedizione quando creo spedizioni tramite API?

Le regole di spedizione verranno applicate alle spedizioni create tramite API, purché vengano create utilizzando l’endpoint Crea una spedizione con regole e/o impostazioni predefinite sincrono oppure asincrono. Ti consigliamo di utilizzare l’opzione di spedizione “Lettera non affrancata” ("shipping_option_code": "sendcloud:letter") per creare le tue spedizioni se desideri che le regole vengano applicate correttamente. In questo modo potrai bypassare l’oggetto obbligatorio ship_with e qualsiasi regola configurata che influisce sulla selezione dell’opzione di spedizione verrà applicata correttamente al tuo pacco. 

Posso testare l’API senza essere addebitato per le etichette create? 

Puoi utilizzare l’opzione di spedizione Sendcloud “Lettera non affrancata” ("shipping_option_code": "sendcloud:letter") per creare le tue spedizioni. Questo ti consente di testare l’API senza il rischio di essere addebitato per le etichette create.

Tieni presente che non è possibile utilizzare questa opzione di spedizione per testare la creazione di etichette di reso. Per testare le etichette di reso, utilizza un’opzione di spedizione che supporti le richieste di annullamento da Sendcloud e annulla l’etichetta entro le 23:59 del giorno di creazione. Consulta la nostra documentazione sulle etichette di test per maggiori informazioni. 

Ricevo il messaggio di errore “User is not allowed to announce”. Cosa significa?

Assicurati di aver seguito tutti i passaggi per la configurazione di base dell’account e di aver attivato un metodo di pagamento tramite addebito diretto. Consulta: Come iniziare con Sendcloud. 

Posso visualizzare tutte le mie opzioni di spedizione tramite API quando collego un contratto diretto con un corriere?

Sì - se hai collegato il tuo contratto diretto con un corriere, potrai recuperare le tue opzioni di spedizione insieme alle opzioni di spedizione Sendcloud effettuando una richiesta all’ endpoint Shipping options API. Nota che i prezzi del tuo contratto non verranno recuperati a meno che tu non abbia caricato i tuoi listini personalizzati. 

Posso visualizzare i miei prezzi dal contratto diretto con il corriere quando utilizzo l’API per verificare le tariffe e confrontare i metodi?

Sì, se hai caricato i tuoi prezzi nel tuo account Sendcloud seguendo i passaggi descritti in questo articolo.  

Ricevo il messaggio di errore “No shipping option could be found for[…]” quando provo a creare una spedizione tramite API. Cosa significa?

Probabilmente il shipping_option_code che stai utilizzando si riferisce a un’opzione di spedizione che non supporta la spedizione da o verso l’indirizzo indicato, ad esempio se stai utilizzando un metodo nazionale per una spedizione internazionale. Potrebbe anche trattarsi dell’utilizzo di un’opzione di reso per una spedizione in uscita, o viceversa. Puoi utilizzare l’ endpoint Shipping options per trovare un’opzione di spedizione adatta in base ai parametri definiti nella richiesta.

L’API supporta l’importazione di note o campi commento negli ordini?

Sì. Ad esempio, puoi utilizzarla per aggiungere note agli ordini come “Si prega di confezionare questo articolo come regalo prima della spedizione”. Queste note appariranno anche sulle packing slip o picking list se utilizzi Pack & Go. 

Ho creato un report tramite API, ma il file CSV è vuoto. Cosa significa?

Presta attenzione al filtro direction quando crei la richiesta all’endpoint di reporting. Se specifichi direction come incoming, vedrai solo i pacchi di reso. Se non hai resi in arrivo, il report sarà vuoto.

Inoltre, devi specificare l’ID dell’integrazione nella richiesta. Non è possibile creare un report per tutte le integrazioni contemporaneamente, quindi assicurati di indicare l’ID corretto per visualizzare i pacchi in uscita o in entrata per integrazione. 

Come posso trovare il mio integration_id?

Puoi trovare il tuo integration_id tramite l’ endpoint Retrieve a list of integrations, oppure dal pannello Sendcloud (Impostazioni > Integrazioni > trova l’integrazione nell’elenco > Modifica). L’ID dell’integrazione verrà mostrato alla fine dell’URL, ad esempio: ‘https://app.sendcloud.com/v2/settings/integrations/api/95977’

Come posso trovare il mio sender_address_id? 

Tramite l’ endpoint Retrieve a list of sender addresses, oppure dal pannello Sendcloud (Impostazioni > Indirizzi > Modifica un indirizzo). L’ID sarà mostrato alla fine dell’URL, ad esempio: ‘https://app.sendcloud.com/v2/settings/addresses/sender/132258’

Come posso trovare il mio brand_id?

Tramite l’ endpoint Retrieve configured brands, oppure nel pannello Sendcloud (Impostazioni > Brand > Modifica un brand). L’ID verrà mostrato alla fine dell’URL, ad esempio: ‘https://app.sendcloud.com/v2/settings/brands/86054’

Ricevo il messaggio di errore “Service point delivery is not enabled for this integration.” Cosa significa?

Devi abilitare la consegna presso punto di ritiro nel pannello Sendcloud andando su Impostazioni > Integrazioni > API > Modifica > Seleziona la casella per abilitare la consegna presso punto di ritiro. Questo è descritto più nel dettaglio qui. 

I numeri civici sono duplicati sulle mie etichette di spedizione quando creo pacchi tramite API. Cosa significa?

Il formato di indirizzo più utilizzato è il seguente:

  • address : Stadhuisplein
  • house_number: 10

Un altro metodo comune è:

  • address: Stadhuisplein 10

Posso creare spedizioni multi-collo (multicollo) tramite API?

Sì, puoi farlo — maggiori dettagli sono disponibili nella nostra documentazione. 

Posso assegnare lo stesso brand a più indirizzi del mittente?

Sì, puoi assegnare lo stesso brand ad alcuni o a tutti i tuoi indirizzi del mittente.

Posso assegnare più brand allo stesso indirizzo del mittente?

È possibile assegnare un solo brand per indirizzo del mittente. Come soluzione alternativa, puoi creare un indirizzo del mittente duplicato e assegnare un brand diverso a ciascuno. Solo uno può essere impostato come indirizzo predefinito, quindi ti consigliamo di assegnare al duplicato un nome facilmente riconoscibile, così da identificarlo rapidamente nel pannello. 

Posso creare spedizioni internazionali tramite API?

Sì, assolutamente. I documenti doganali verranno generati automaticamente, purché i campi obbligatori (vedi sotto) siano correttamente specificati per ciascun prodotto incluso nella spedizione. Questo è spiegato più nel dettaglio nella nostra documentazione: Spedizioni internazionali

Quali campi sono obbligatori per le spedizioni internazionali?

  • customs_invoice_number
  • customs_shipment_type
  • country_state (Obbligatorio solo per Australia, Canada, Italia e USA.)
  • parcel_items
    • origin_country (ISO 2) 
    • hs_code

Articoli e risorse correlate

→ Documentazione API

→ Riferimento API Sendcloud

→ Portale sviluppatori Sendcloud

→ I Service Points (punti di consegna e ritiro) per le integrazioni API