Domande frequenti sulle API di Sendcloud

Argomento: Domande frequenti relative alle integrazioni di negozi online personalizzati che utilizzano le API di Sendcloud.

Quali sono i limiti dell'API? 

Limiti di velocità

La nostra API ha dei limiti di velocità che limitano il numero di richieste che possono essere effettuate al minuto. Tieni presente che ci sono limiti di velocità diversi per gli endpoint relativi alle spedizioni.

• Safe requests (GET): 1000 richieste al minuto.
• Unsafe requests (POST/PATCH/PUT/DELETE): 100 richieste al minuto.
• Shipping-related safe requests (GET): 420 richieste al minuto.
• Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 100 richieste al minuto.

Limiti dei picchi

Gli endpoint considerati "non sicuri" (unsafe) hanno un limite di picco impostato, che è il numero massimo di richieste simultanee che l'API può gestire. Consente un aumento temporaneo della velocità di richieste per soddisfare brevi periodi di traffico elevato senza superare i limiti generali.

• Unsafe requests (POST/PATCH/PUT/DELETE): 15 richieste al secondo.
• Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 15 richieste al secondo.

Per saperne di più sulla limitazione della velocità, consulta la nostra documentazione per gli sviluppatori.

Sendcloud si riserva il diritto di apportare modifiche.

Come posso utilizzare in modo efficiente l'API di Sendcloud?

Esistono vari modi per utilizzare in modo efficiente la nostra API. Ad esempio, puoi creare pacchi in massa, ottenere i nuovi pacchi aggiornati utilizzando il parametro updated_after o utilizzare i webhook per ricevere gli aggiornamenti direttamente nel tuo sistema.

Fai annunci in massa in parallelo alla nostra API, in piccoli lotti. Per annunciare 100 pacchi potresti effettuare 5 lotti da 20 chiamate in parallelo alla nostra API.

Voglio creare le etichette direttamente quando creo un pacco tramite l'API. Come posso fare?

Per creare pacchi ed etichette di spedizione con un'unica chiamata API, imposta il campo request_label su 'true' nella richiesta all'endpoint Create a parcel (crea un pacco). Questo processo è spiegato in modo più dettagliato nella nostra documentazione. 

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

Nel contesto delle API, l'idempotenza si riferisce al momento in cui effettuare più richieste ha lo stesso effetto di una singola richiesta. Questo per evitare errori da parte dell'utente e, nel caso delle API di Sendcloud, la duplicazione degli ordini nel nostro sistema. Ci sono due endpoint che cercano di essere idempotenti:

• Update a parcel (aggiornare un pacco)
  Utilizza il campo external_reference per mantenere l'idempotenza.

• Create/Update a list of shipments (creare/aggiornare un elenco di spedizioni)
  Si tratta di un endpoint di upsert (insert/update), il che significa che se una spedizione risulta già esistente nel database di Sendcloud, la spedizione sarà aggiornata. Se non c'è corrispondenza, sarà invece creata. Per mantenere l'idempotenza, devi utilizzare una combinazione di external_order_id e external_shipment_id. Si aggiorneranno solo le spedizioni il cui timestamp updated_at (ISO 8601 DateTime) è stato modificato. Si consiglia di utilizzare una combinazione di questi campi per ottenere un'integrazione solida. 

Perché sender_address è un campo obbligatorio quando si creano etichette tramite l'API?

I corrieri richiedono che l'indirizzo del mittente sia presente su ogni etichetta di spedizione per identificare la provenienza del pacco. Se quando crei un pacco tramite l'API non è specificato l'indirizzo del mittente, per stampare l'etichetta si userà l'indirizzo predefinito (salvato nel tuo account Sendcloud). Nella nostra documentazione spieghiamo più dettagliatamente come ottenere un ID dell'indirizzo del mittente e la relazione tra indirizzi del mittente, etichette e brand. 

Posso usare le regole di spedizione quando creo pacchi tramite l'API?

Le regole di spedizione si applicano ai pacchi creati tramite il pannello, a condizione che il campo apply_shipping_rules sia true. Ti consigliamo di utilizzare il metodo di spedizione "Unstamped Letter" per creare i tuoi pacchi se vuoi che le regole di spedizione siano applicate correttamente ai tuoi pacchi. In questo modo potrai evitare i campi richiesti per il shipping_method e tutte le regole che hai configurato per la selezione del metodo di spedizione saranno applicate correttamente al tuo pacco. 

Posso testare l'API senza che mi siano addebitate le etichette che creo?

Puoi utilizzare il metodo di spedizione Sendcloud "Unstamped Letter" per creare i tuoi pacchi. In questo modo puoi testare l'API senza correre il rischio che ti vengano addebitate le etichette create.

Tieni presente che non è possibile utilizzare questo metodo per testare la creazione di etichette di reso. Per testare le etichette di reso, utilizza un metodo di spedizione che supporti le richieste di cancellazione da Sendcloud e annulla l'etichetta prima delle 23:59 del giorno di creazione. Per maggiori informazioni, consulta la nostra documentazione sulle etichette di prova. 

Ricevo il messaggio di errore “User is not allowed to announce”. Cosa c'è che non va?

Assicurati di aver seguito tutte le fasi di configurazione di base dell'account e di aver attivato un metodo di pagamento. Vedi: Sendcloud ti dà il benvenuto!

Posso vedere tutti i miei metodi di spedizione tramite l'API quando collego un contratto di trasporto diretto?

Sì: se hai collegato il tuo contratto con un corriere potrai recuperare i tuoi metodi di spedizione insieme a quelli di Sendcloud effettuando una richiesta GET all'endpoint Retrieve a list of shipping methods (Recupera un elenco di metodi di spedizione). Nota che i prezzi del tuo contratto non saranno recuperati a meno che tu non abbia caricato i prezzi del tuo corriere. 

Posso vedere i prezzi dei miei contratti diretti con i corrieri quando utilizzo l'API per controllare le tariffe e confrontare i metodi?

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

Ricevo il messaggio di errore "“Invalid shipment ID” quando cerco di creare un pacco tramite l'API. Cosa c'è che non va?

È probabile che il shipping_method_id che stai utilizzando si riferisca a un metodo 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 essere che tu stia cercando di utilizzare un metodo di reso per una spedizione in uscita o viceversa. Puoi utilizzare l'endpoint Shipping products (prodotti di spedizione) per trovare il metodo più adatto al tuo pacco in base ai parametri che definisci nella richiesta.

Infine, fai attenzione che il nome del metodo di spedizione si riferisca al metodo che vuoi utilizzare. Il nome dei metodi di spedizione nel nostro database sono volatili e non dovrebbero essere memorizzati nella cache per più di un'ora. 

Ho creato una richiesta di pacco, ma il pacco non compare nel mio account Sendcloud. Cosa c'è che non va?

È probabile che la richiesta non includa un valore per il campo booleano request_label.

• Quando questo campo è true, l'etichetta sarà stampata insieme alla richiesta di creazione di un pacco e il pacco apparirà nella scheda Etichette create di Sendcloud.
• Quando il valore è false, l'oggetto pacco è creato ma apparirà nella panoramica degli ordini in arrivo, in attesa di essere elaborato.
• Se non hai aggiunto un valore, puoi utilizzare l'endpoint Update a parcel (aggiorna un pacco) per modificare il campo request_labelin true o false. Puoi trovare l'ID univoco del pacco (che ti servirà nella tua richiesta) tramite l'endpoint Retrieve all parcels (recupera tutti i pacchi). 

L'API supporta l'importazione di campi di note o commenti negli ordini?

Sì. Ad esempio, questo può essere utilizzato per aggiungere note agli ordini, come "È un regalo. Si prega di incartare questo articolo prima della spedizione". Queste note appariranno anche sulle bolle di accompagnamento o sulle liste di prelievo se utilizzi il Pack & Go.

Ho creato un rapporto tramite l'API, ma il mio file CSV è vuoto. Cosa c'è che non va?

Tieni presente il filtro direction quando crei la richiesta all'endpoint di reporting. Se specifichi la direction in incoming, vedrai solo i pacchi di ritorno (resi). Se non ci sono resi in arrivo, il report sarà vuoto.

Inoltre, dovrai specificare l'ID dell'integrazione nella tua richiesta. Non è possibile creare un rapporto per tutte le tue integrazioni contemporaneamenteo, quindi assicurati di specificare l'ID corretto per vedere i tuoi pacchi in uscita o in entrata per ogni integrazione. 

Come posso trovare il mio integration_id?

Puoi trovare l'integration_id tramite l'endpoint Retrieve a list of integrations (Recupera un elenco di integrazioni) o dal tuo pannello Sendcloud (Impostazioni > Integrazioni > Trova la tua integrazione nell'elenco > Modifica). L'ID dell'integrazione sarà indicato 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 (Recupera un elenco di indirizzi mittente) o dal tuo pannello Sendcloud (Impostazioni > Indirizzi > Modifica indirizzo). L'ID sarà indicato 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 a list of brands (Recupera un elenco di brand) o nel tuo pannello Sendcloud (Impostazioni > Brand> Modifica brand). L'ID è visualizzato alla fine dell'URL, per esempio "https://app.sendcloud.com/v2/settings/brands/86054".

Ricevo il messaggio di errore “Service point delivery is not enabled for this integration". Cosa c'è che non va?

Devi abilitare la consegna nei punti di ritiro nel pannello di Sendcloud, andando su Impostazioni > Integrazioni > API > Modifica > Spunta la casella per abilitare la consegna nei service points. Questa procedura è descritta in modo più dettagliato qui. 

Non vedo i metodi di tutti i corrieri quando faccio una richiesta GET per recuperare un elenco di metodi di spedizione.

Innanzitutto, verifica di aver abilitato tutti i corrieri che vuoi utilizzare andando su Impostazioni > Corrieri nel tuo account Sendcloud. Usa il menu a tendina per selezionare più corrieri per ogni paese in cui hai un indirizzo mittente attivo.

In secondo luogo, dovrai specificare uno dei tuoi indirizzi mittente nella chiamata API agli endpoint dei Metodi di spedizione (Shipping methods)  per vedere i metodi per i paesi diversi da quello del tuo indirizzo mittente predefinito. Ad esempio, se il tuo indirizzo mittente predefinito si trova in Italia, ma vuoi vedere i metodi di Post NL (Paesi Bassi), dovrai specificare l'ID dell'indirizzo mittente dei Paesi Bassi per recuperare i metodi applicabili nei Paesi Bassi. Questo aspetto è spiegato in modo più dettagliato nella nostra documentazione.

I numeri civici sono duplicati sulle mie etichette di spedizione quando creo pacchi tramite l'API. Cosa c'è che non va?

Il formato di indirizzo più utilizzato è il seguente:

• address : Via del Corso
• house_number: 10

Un altro formato comune è:

• address: Via del Corso 10

Posso creare spedizioni multicollo tramite l'API?

Sì, è possibile: questo è descritto in modo più dettagliato nella nostra documentazione. 

Posso assegnare lo stesso brand a più indirizzi mittente?

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

Posso assegnare più brand allo stesso indirizzo mittente?

È possibile assegnare un solo brand per ogni indirizzo mittente. La soluzione consiste nel creare un indirizzo mittente duplicato e assegnare a ciascuno un brand diverso. Solo uno può essere specificato come indirizzo predefinito, quindi ti consigliamo di assegnare al duplicato un nome riconoscibile, in modo da poterlo identificare facilmente nel pannello. 

Posso creare spedizioni internazionali tramite l'API?

Sì, assolutamente. I documenti doganali saranno generati automaticamente, a condizione che i campi obbligatori (vedi sotto) siano specificati correttamente per ogni prodotto incluso nella spedizione. Questo aspetto è spiegato in modo più dettagliato nella nostra documentazione: Spedizione internazionale.

Quali campi sono obbligatori per la spedizione internazionale?

• customs_invoice_number
• customs_shipment_type
• country_state(Richiesto solo per Australia, Canada, Italia e Stati Uniti).
• parcel_items
  • origin_country (ISO 2) 
  • hs_code

Articoli e risorse correlate

→ Documentazione API

→ Guida di riferimento alle API di Sendcloud

→ Portale per gli sviluppatori di Sendcloud

→ Punti di ritiro per le integrazioni API