Crea il catalogo del tuo Account Verificato in modo programmatico, direttamente dal tuo sistema.
L'API Catalogo è uno dei tre modi per creare il catalogo del tuo Account Verificato ed è l'opzione pensata per gli spedizionieri che dispongono di risorse di sviluppo e di un sistema che contiene già i dati dei loro prodotti: un ERP, un WMS, un PIM o una piattaforma di spedizione. Quel sistema resta la fonte di riferimento dei dati e scrive i prodotti direttamente in Zonos, invece di sincronizzarli da un'integrazione di canale o di caricare un file CSV. Se vendi tramite un canale supportato, o preferisci non scrivere codice, queste due opzioni creano lo stesso catalogo con meno lavoro.
Gli articoli creati tramite l'API vengono trattati esattamente come gli articoli provenienti da qualsiasi altra fonte: una volta che un articolo è nel tuo catalogo, per Zonos non ha importanza come ci sia arrivato. Ogni articolo viene classificato ai fini doganali se non hai fornito un codice HS, verificato rispetto ai requisiti delle Partner Government Agency (PGA) statunitensi e utilizzato per calcolare dazi e imposte sulle spedizioni in cui compare.
C'è però una parte che resta al di fuori dell'API. Quando la verifica PGA segnala un articolo come Richiede attenzione, il questionario di conformità collegato a quella segnalazione deve essere compilato e confermato in Dashboard: non esiste un'API per farlo, e Zonos precompila tutto ciò che può, quindi la maggior parte del lavoro consiste nel rivedere e confermare. Chi realizza questa integrazione di solito non è la stessa persona che risolve queste segnalazioni, quindi prevedi che qualcuno della tua organizzazione le gestisca in Dashboard dopo il caricamento del catalogo. Gli articoli segnalati non sono bloccati per la spedizione, ma risolvere le segnalazioni prima di spedire è ciò che evita che una spedizione venga trattenuta alla frontiera degli Stati Uniti.
Crea un articolo del catalogo per ogni prodotto che spedisci.
Assicurati che ogni articolo contenga un identificatore che il tuo vettore postale trasmetterà.
Quando i dati della tua spedizione raggiungono Zonos, ogni riga viene associata all'articolo corrispondente del tuo catalogo e i dati di prodotto di quell'articolo vengono applicati al calcolo.
Creare articoli del catalogo
catalogItemCreate accetta un elenco, quindi puoi inviare molti prodotti in un'unica richiesta.
Se invii un prodotto il cui SKU o ID prodotto esiste già, Zonos aggiorna quel prodotto invece di aggiungerne un secondo. Nuovi tentativi ed esecuzioni ripetute sono quindi sicuri.
Il rovescio della medaglia è che due prodotti diversi con lo stesso SKU o ID prodotto verranno uniti in uno solo. Verifica che i tuoi dati non contengano duplicati prima di un caricamento massivo.
Il tuo identificatore univoco del prodotto. *Ogni prodotto richiede uno SKU, un ID prodotto o entrambi.
productId
Sì*
L'identificatore del prodotto nella tua piattaforma. *Ogni prodotto richiede uno SKU, un ID prodotto o entrambi.
manufacturerProductId
Solo UE
Il Non-Standardised Manufacturer Product Identifier (NS-PID). Obbligatorio per le spedizioni B2C verso l'UE di valore pari o inferiore a 150 EUR.
gtin
Solo UE
Lo Standardised Manufacturer Product Identifier (S-PID), solo cifre. Obbligatorio per le spedizioni B2C verso l'UE di valore pari o inferiore a 150 EUR, se il prodotto ha un codice a barre.
name
Sì
Il nome del prodotto.
customsDescription
Consigliato
Che cos'è il prodotto, in termini semplici, per la dichiarazione doganale. Usa "T-shirt in cotone", non "Summer Vibes Tee".
countryOfOrigin
Consigliato
Il codice ISO di 2 lettere del Paese in cui il prodotto è stato fabbricato. Necessario per calcolare i dazi con precisione.
measurements
Consigliato
Peso e dimensioni, utilizzati per il calcolo delle tariffe di spedizione e per le dichiarazioni doganali.
hsCode
No
Il codice HS universale a 6 cifre. Se lo ometti, Zonos classifica il prodotto in base al nome e alla descrizione.
amount
No
Il prezzo del prodotto come valore numerico.
currencyCode
No
Il codice ISO di 3 lettere della valuta del prezzo. Obbligatorio quando fornisci amount.
itemType
No
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE o PARTIAL_ITEM. Evita che gli articoli non fisici vengano dichiarati come merce.
provinceOfOrigin
No
Lo stato o la provincia di origine del prodotto. Richiesto da alcuni Paesi di destinazione.
productComposition
No
Un elenco di {material, percentage}. Senza di esso, i tessili non possono essere classificati oltre le 6 cifre.
catalogItemUrl
No
Un link alla pagina del prodotto sul tuo sito. Migliora l'accuratezza della classificazione.
imageUrl
No
Un URL pubblicamente accessibile dell'immagine del prodotto. Migliora l'accuratezza della classificazione.
Aggiungere gli identificatori di prodotto UE (PID)
Se spedisci verso l'UE con il tuo Account Verificato, dal 1° novembre 2026 l'UE richiede gli identificatori di prodotto (PID) sulle spedizioni business-to-consumer (B2C) di valore pari o inferiore a 150 EUR. Memorizzali negli articoli del tuo catalogo. Per la maggior parte degli Account Verificati, il tuo servizio postale invia a Zonos i dati della spedizione e Zonos associa ogni articolo della spedizione al tuo catalogo applicando gli identificatori che hai salvato, quindi al momento della spedizione non devi inviare nulla in più.
Invia gli identificatori con catalogItemCreate per i nuovi prodotti. Per i prodotti già presenti nel tuo catalogo, inviali con catalogItemUpdate, che accetta gli stessi campi. Fai corrispondere lo sku di ogni articolo allo SKU che usi ovunque, così Zonos può collegare i due.
Invia il gtin solo come cifre, senza trattini né spazi. I valori UPC, EAN, JAN e ISBN a 13 cifre vanno tutti in questo unico campo. Se disponi di un ISBN a 10 cifre, invia invece la versione a 13 cifre.
Se un prodotto non ha un codice a barre, ometti gtin invece di inviare una stringa vuota, riutilizzare il tuo SKU o compilarlo con testo segnaposto come N/A.
Zonos collega ogni riga della spedizione a un articolo del catalogo utilizzando i tuoi identificatori, in questo ordine: ID prodotto, poi SKU, poi nome. Mantieni gli identificatori che utilizzi accurati e coerenti tra il tuo catalogo e i dati che invii al tuo vettore.
Le spedizioni postali comportano un ulteriore vincolo. Zonos riceve dai vettori postali un insieme limitato di campi e, su molte tratte, la descrizione doganale è l'unico campo che arriva con informazioni specifiche sul prodotto. Una descrizione identica per tutto il catalogo non può, da sola, identificare nulla.
Il modo in cui formattare l'identificatore nei dati di spedizione che invii al tuo vettore dipende dal tuo servizio postale, perché ogni servizio postale associa le spedizioni al tuo catalogo in modo diverso. Vai a tutti i servizi postali e seleziona il tuo. La sua pagina mostra come funziona l'associazione per quel servizio postale e cosa inviare esattamente.
Impostare il customsDescription dell'articolo sulla stessa stringa che invii al tuo vettore non è obbligatorio, ma rende i due lati direttamente confrontabili quando una riga non viene associata e devi capirne il motivo.
L'associazione non riesce solitamente quando:
L'identificatore su cui il tuo servizio postale basa l'associazione manca nei dati della spedizione.
L'identificatore non corrisponde esattamente ad alcun elemento del tuo catalogo.
L'identificatore viene troncato dal limite di caratteri del vettore.
La formattazione cambia da una spedizione all'altra.
Questo comportamento è ancora in fase di definizione e potrebbe cambiare prima del lancio.
Aggiornare articoli del catalogo
catalogItemUpdate accetta lo stesso tipo di input della creazione. Invia solo i campi che desideri modificare.
Nota: i campi omessi restano invariati, il che rende sicuri gli aggiornamenti parziali. L'invio di null non cancella un valore: viene ignorato. Puoi sovrascrivere un valore con uno diverso, ma non puoi svuotarlo tramite l'API. Contatta il tuo rappresentante Zonos se hai bisogno di cancellare un campo.
Rileggere i tuoi articoli
La query catalogItem accetta id, productId o sku. Utilizzala per verificare quali dati Zonos conserva per un prodotto.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Eliminare articoli del catalogo
catalogItemDelete accetta gli ID degli articoli del catalogo Zonos, non i tuoi SKU o ID prodotto. Recupera prima l'ID con la query catalogItem.
API Catalogo
API Catalogo
Crea il catalogo del tuo Account Verificato in modo programmatico, direttamente dal tuo sistema.
L'API Catalogo è uno dei tre modi per creare il catalogo del tuo Account Verificato ed è l'opzione pensata per gli spedizionieri che dispongono di risorse di sviluppo e di un sistema che contiene già i dati dei loro prodotti: un ERP, un WMS, un PIM o una piattaforma di spedizione. Quel sistema resta la fonte di riferimento dei dati e scrive i prodotti direttamente in Zonos, invece di sincronizzarli da un'integrazione di canale o di caricare un file CSV. Se vendi tramite un canale supportato, o preferisci non scrivere codice, queste due opzioni creano lo stesso catalogo con meno lavoro.
Gli articoli creati tramite l'API vengono trattati esattamente come gli articoli provenienti da qualsiasi altra fonte: una volta che un articolo è nel tuo catalogo, per Zonos non ha importanza come ci sia arrivato. Ogni articolo viene classificato ai fini doganali se non hai fornito un codice HS, verificato rispetto ai requisiti delle Partner Government Agency (PGA) statunitensi e utilizzato per calcolare dazi e imposte sulle spedizioni in cui compare.
C'è però una parte che resta al di fuori dell'API. Quando la verifica PGA segnala un articolo come Richiede attenzione, il questionario di conformità collegato a quella segnalazione deve essere compilato e confermato in Dashboard: non esiste un'API per farlo, e Zonos precompila tutto ciò che può, quindi la maggior parte del lavoro consiste nel rivedere e confermare. Chi realizza questa integrazione di solito non è la stessa persona che risolve queste segnalazioni, quindi prevedi che qualcuno della tua organizzazione le gestisca in Dashboard dopo il caricamento del catalogo. Gli articoli segnalati non sono bloccati per la spedizione, ma risolvere le segnalazioni prima di spedire è ciò che evita che una spedizione venga trattenuta alla frontiera degli Stati Uniti.
Come funziona
Crea un articolo del catalogo per ogni prodotto che spedisci.
Assicurati che ogni articolo contenga un identificatore che il tuo vettore postale trasmetterà.
Quando i dati della tua spedizione raggiungono Zonos, ogni riga viene associata all'articolo corrispondente del tuo catalogo e i dati di prodotto di quell'articolo vengono applicati al calcolo.
Creare articoli del catalogo
catalogItemCreateaccetta un elenco, quindi puoi inviare molti prodotti in un'unica richiesta.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Inviare lo stesso prodotto due volte
Se invii un prodotto il cui SKU o ID prodotto esiste già, Zonos aggiorna quel prodotto invece di aggiungerne un secondo. Nuovi tentativi ed esecuzioni ripetute sono quindi sicuri.
Il rovescio della medaglia è che due prodotti diversi con lo stesso SKU o ID prodotto verranno uniti in uno solo. Verifica che i tuoi dati non contengano duplicati prima di un caricamento massivo.
Campi
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEoPARTIAL_ITEM. Evita che gli articoli non fisici vengano dichiarati come merce.provinceOfOriginproductComposition{material, percentage}. Senza di esso, i tessili non possono essere classificati oltre le 6 cifre.catalogItemUrlimageUrlAggiungere gli identificatori di prodotto UE (PID)
Se spedisci verso l'UE con il tuo Account Verificato, dal 1° novembre 2026 l'UE richiede gli identificatori di prodotto (PID) sulle spedizioni business-to-consumer (B2C) di valore pari o inferiore a 150 EUR. Memorizzali negli articoli del tuo catalogo. Per la maggior parte degli Account Verificati, il tuo servizio postale invia a Zonos i dati della spedizione e Zonos associa ogni articolo della spedizione al tuo catalogo applicando gli identificatori che hai salvato, quindi al momento della spedizione non devi inviare nulla in più.
skumanufacturerProductIdgtinInvia gli identificatori con
catalogItemCreateper i nuovi prodotti. Per i prodotti già presenti nel tuo catalogo, inviali concatalogItemUpdate, che accetta gli stessi campi. Fai corrispondere loskudi ogni articolo allo SKU che usi ovunque, così Zonos può collegare i due.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtinInvia il
gtinsolo come cifre, senza trattini né spazi. I valori UPC, EAN, JAN e ISBN a 13 cifre vanno tutti in questo unico campo. Se disponi di un ISBN a 10 cifre, invia invece la versione a 13 cifre.Se un prodotto non ha un codice a barre, ometti
gtininvece di inviare una stringa vuota, riutilizzare il tuo SKU o compilarlo con testo segnaposto comeN/A.Se chiami tu stesso la Landed Cost API, puoi anche includere questi identificatori nella tua richiesta di landed cost. La maggior parte degli Account Verificati non lo fa, perché è il servizio postale a inviare a Zonos i dati della spedizione.
Per i requisiti previsti dalla normativa, consulta la guida agli identificatori di prodotto UE.
Rendere i tuoi articoli associabili
Zonos collega ogni riga della spedizione a un articolo del catalogo utilizzando i tuoi identificatori, in questo ordine: ID prodotto, poi SKU, poi nome. Mantieni gli identificatori che utilizzi accurati e coerenti tra il tuo catalogo e i dati che invii al tuo vettore.
Le spedizioni postali comportano un ulteriore vincolo. Zonos riceve dai vettori postali un insieme limitato di campi e, su molte tratte, la descrizione doganale è l'unico campo che arriva con informazioni specifiche sul prodotto. Una descrizione identica per tutto il catalogo non può, da sola, identificare nulla.
Il modo in cui formattare l'identificatore nei dati di spedizione che invii al tuo vettore dipende dal tuo servizio postale, perché ogni servizio postale associa le spedizioni al tuo catalogo in modo diverso. Vai a tutti i servizi postali e seleziona il tuo. La sua pagina mostra come funziona l'associazione per quel servizio postale e cosa inviare esattamente.
Impostare il
customsDescriptiondell'articolo sulla stessa stringa che invii al tuo vettore non è obbligatorio, ma rende i due lati direttamente confrontabili quando una riga non viene associata e devi capirne il motivo.L'associazione non riesce solitamente quando:
Aggiornare articoli del catalogo
catalogItemUpdateaccetta lo stesso tipo di input della creazione. Invia solo i campi che desideri modificare.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Rileggere i tuoi articoli
La query
catalogItemaccettaid,productIdosku. Utilizzala per verificare quali dati Zonos conserva per un prodotto.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Eliminare articoli del catalogo
catalogItemDeleteaccetta gli ID degli articoli del catalogo Zonos, non i tuoi SKU o ID prodotto. Recupera prima l'ID con la querycatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Risorse correlate
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Questa pagina è stata utile?