Bygg Verified Account-katalogen din programmatisk, rett fra ditt eget system.
Catalog API er én av tre måter å bygge opp Verified Account-katalogen din på, og det er alternativet for avsendere som har utviklerressurser og et system som allerede inneholder produktdataene deres—et ERP-, WMS- eller PIM-system eller en fraktplattform. Det systemet forblir den autoritative kilden og skriver produkter direkte til Zonos, i stedet for å synkronisere fra en kanalintegrasjon eller laste opp en CSV-fil. Hvis du selger gjennom en støttet kanal, eller helst vil slippe å skrive kode, bygger disse to alternativene den samme katalogen med mindre arbeid.
Artikler som opprettes gjennom API-et, behandles nøyaktig som artikler fra enhver annen kilde—når en artikkel først er i katalogen din, spiller det ingen rolle for Zonos hvordan den kom dit. Hver artikkel klassifiseres for toll hvis du ikke oppga en HS-kode, kontrolleres for krav fra amerikanske Partner Government Agencies (PGA), og brukes til å beregne toll og avgifter på sendingene den inngår i.
Én del av dette ligger utenfor API-et. Når PGA-kontrollen flagger en artikkel som Trenger oppmerksomhet, må samsvarsspørreskjemaet bak flagget besvares og bekreftes i Dashboard—det finnes ikke noe API for det, og Zonos forhåndsutfyller det som er mulig, slik at mesteparten av jobben er å gjennomgå og bekrefte. Personen som bygger denne integrasjonen, er vanligvis ikke den samme som håndterer flaggene, så planlegg at noen i organisasjonen din går gjennom dem i Dashboard etter at katalogen er lastet inn. Flaggede artikler blokkeres ikke fra å sendes, men å håndtere flaggene før du sender er det som hindrer at en sending blir holdt tilbake ved den amerikanske grensen.
Hvis du sender et produkt med en SKU eller produkt-ID som allerede finnes, oppdaterer Zonos det produktet i stedet for å legge til et nytt. Nye forsøk og gjentatte kjøringer er trygge.
Baksiden er at to forskjellige produkter som deler SKU eller produkt-ID, slås sammen til ett. Kontroller dataene dine for duplikater før en masseinnlasting.
Din unike identifikator for produktet. *Hvert produkt trenger en SKU eller en produkt-ID, eller begge deler.
productId
Ja*
Plattformens identifikator for produktet. *Hvert produkt trenger en SKU eller en produkt-ID, eller begge deler.
manufacturerProductId
Kun EU
Den ikke-standardiserte produsentproduktidentifikatoren (NS-PID). Påkrevd på B2C-sendinger til EU med en verdi på 150 EUR eller mindre.
gtin
Kun EU
Den standardiserte produsentproduktidentifikatoren (S-PID), kun sifre. Påkrevd på B2C-sendinger til EU med en verdi på 150 EUR eller mindre, hvis produktet har en strekkode.
name
Ja
Produktets navn.
customsDescription
Anbefalt
Hva produktet er, i klartekst, for tolldeklarasjonen. Bruk «T-skjorte i bomull», ikke «Summer Vibes Tee».
countryOfOrigin
Anbefalt
Den 2-bokstavs ISO-koden for landet der produktet ble produsert. Nødvendig for nøyaktig tollberegning.
measurements
Anbefalt
Vekt og dimensjoner, brukt til fraktprising og tollinnlevering.
hsCode
Nei
Den universelle 6-sifrede HS-koden. Hvis du utelater den, klassifiserer Zonos produktet ut fra navn og beskrivelse.
amount
Nei
Produktets pris som et tall.
currencyCode
Nei
Den 3-bokstavs ISO-koden for prisvalutaen. Obligatorisk når du oppgir amount.
itemType
Nei
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE eller PARTIAL_ITEM. Hindrer at ikke-fysiske artikler deklareres som handelsvarer.
provinceOfOrigin
Nei
Delstaten eller provinsen produktet stammer fra. Påkrevd av enkelte destinasjonsland.
productComposition
Nei
En liste med {material, percentage}. Tekstiler kan ikke klassifiseres utover 6 sifre uten den.
catalogItemUrl
Nei
En lenke til produktsiden på nettstedet ditt. Gir mer nøyaktig klassifisering.
imageUrl
Nei
En offentlig tilgjengelig URL for produktbildet. Gir mer nøyaktig klassifisering.
Legg til EU-produktidentifikatorer (PID-er)
Hvis du sender til EU med Verified Account-kontoen din, krever EU produktidentifikatorer (PID-er) på sendinger fra bedrift til forbruker (B2C) med en verdi på 150 EUR eller mindre, fra og med 1. november 2026. Lagre dem på katalogartiklene dine. For de fleste Verified Accounts er det postoperatøren din som sender sendingsdataene til Zonos, og Zonos matcher hver artikkel i sendingen mot katalogen din og bruker identifikatorene du har lagret, så du trenger ikke å sende noe ekstra når du sender pakken.
Send identifikatorene med catalogItemCreate for nye produkter. For produkter som allerede ligger i katalogen din, sender du dem med catalogItemUpdate, som tar de samme feltene. Sørg for at hver artikkels sku samsvarer med SKU-en du bruker overalt ellers, slik at Zonos kan koble de to sammen.
Send gtin kun som sifre, uten bindestreker eller mellomrom. UPC-, EAN-, JAN- og 13-sifrede ISBN-verdier går alle i dette ene feltet. Hvis du har et 10-sifret ISBN, sender du den 13-sifrede versjonen i stedet.
Hvis et produkt ikke har strekkode, utelater du gtin i stedet for å sende en tom streng, gjenbruke SKU-en din eller fylle feltet med plassholdertekst som N/A.
Zonos kobler hver sendingslinje tilbake til en katalogartikkel ved hjelp av identifikatorene dine, i denne rekkefølgen: produkt-ID, deretter SKU, deretter navn. Hold identifikatorene du bruker nøyaktige og konsistente mellom katalogen din og dataene du sender til transportøren.
Postsendinger har en ytterligere begrensning. Zonos mottar et begrenset sett med felt fra posttransportører, og på mange ruter er tollbeskrivelsen det eneste feltet som inneholder noe produktspesifikt. En beskrivelse som er identisk på tvers av hele katalogen din, kan ikke identifisere noe på egen hånd.
Hvordan du formaterer identifikatoren i sendingsdataene du sender til transportøren, avhenger av postoperatøren din, fordi hver postoperatør matcher sendinger mot katalogen din på sin egen måte. Gå til alle postoperatører og velg din. Siden for postoperatøren viser hvordan matchingen fungerer for akkurat den, og nøyaktig hva du skal sende.
Det er ikke påkrevd å sette artikkelens customsDescription til den samme strengen du sender til transportøren, men det gjør de to sidene direkte sammenlignbare når en linje ikke matcher og du må finne ut hvorfor.
Matching mislykkes vanligvis når:
Identifikatoren postoperatøren din matcher på, mangler i sendingsdataene.
Identifikatoren ikke samsvarer nøyaktig med noe i katalogen din.
Identifikatoren blir avkortet av transportørens tegnbegrensning.
Formateringen endres mellom sendinger.
Denne oppførselen er fortsatt under utarbeidelse og kan endres før lansering.
Oppdater katalogartikler
catalogItemUpdate bruker samme inndatatype som opprettelse. Send bare feltene du vil endre.
Merk: Utelatte felt forblir uendret, noe som gjør delvise oppdateringer trygge. Å sende null tømmer ikke en verdi; den ignoreres. Du kan overskrive en verdi med en annen, men du kan ikke tømme den via API-et. Kontakt Zonos-representanten din hvis du trenger at et felt tømmes.
Les artiklene dine tilbake
Spørringen catalogItem godtar id, productId eller sku. Bruk den til å bekrefte hvilke data Zonos har for et produkt.
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}
Slett katalogartikler
catalogItemDelete tar Zonos-katalogartikkel-ID-er, ikke SKU-ene eller produkt-ID-ene dine. Finn ID-en med spørringen catalogItem først.
Catalog API
Catalog API
Bygg Verified Account-katalogen din programmatisk, rett fra ditt eget system.
Catalog API er én av tre måter å bygge opp Verified Account-katalogen din på, og det er alternativet for avsendere som har utviklerressurser og et system som allerede inneholder produktdataene deres—et ERP-, WMS- eller PIM-system eller en fraktplattform. Det systemet forblir den autoritative kilden og skriver produkter direkte til Zonos, i stedet for å synkronisere fra en kanalintegrasjon eller laste opp en CSV-fil. Hvis du selger gjennom en støttet kanal, eller helst vil slippe å skrive kode, bygger disse to alternativene den samme katalogen med mindre arbeid.
Artikler som opprettes gjennom API-et, behandles nøyaktig som artikler fra enhver annen kilde—når en artikkel først er i katalogen din, spiller det ingen rolle for Zonos hvordan den kom dit. Hver artikkel klassifiseres for toll hvis du ikke oppga en HS-kode, kontrolleres for krav fra amerikanske Partner Government Agencies (PGA), og brukes til å beregne toll og avgifter på sendingene den inngår i.
Én del av dette ligger utenfor API-et. Når PGA-kontrollen flagger en artikkel som Trenger oppmerksomhet, må samsvarsspørreskjemaet bak flagget besvares og bekreftes i Dashboard—det finnes ikke noe API for det, og Zonos forhåndsutfyller det som er mulig, slik at mesteparten av jobben er å gjennomgå og bekrefte. Personen som bygger denne integrasjonen, er vanligvis ikke den samme som håndterer flaggene, så planlegg at noen i organisasjonen din går gjennom dem i Dashboard etter at katalogen er lastet inn. Flaggede artikler blokkeres ikke fra å sendes, men å håndtere flaggene før du sender er det som hindrer at en sending blir holdt tilbake ved den amerikanske grensen.
Slik fungerer det
Opprett en katalogartikkel for hvert produkt du sender.
Sørg for at hver artikkel har en identifikator som posttransportøren din vil videreformidle.
Når sendingsdataene dine når Zonos, matches hver linje tilbake til katalogartikkelen din, og artikkelens produktdata brukes i beregningen.
Opprett katalogartikler
catalogItemCreategodtar en liste, så du kan sende mange produkter i én enkelt forespørsel.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Sende samme produkt to ganger
Hvis du sender et produkt med en SKU eller produkt-ID som allerede finnes, oppdaterer Zonos det produktet i stedet for å legge til et nytt. Nye forsøk og gjentatte kjøringer er trygge.
Baksiden er at to forskjellige produkter som deler SKU eller produkt-ID, slås sammen til ett. Kontroller dataene dine for duplikater før en masseinnlasting.
Felt
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEellerPARTIAL_ITEM. Hindrer at ikke-fysiske artikler deklareres som handelsvarer.provinceOfOriginproductComposition{material, percentage}. Tekstiler kan ikke klassifiseres utover 6 sifre uten den.catalogItemUrlimageUrlLegg til EU-produktidentifikatorer (PID-er)
Hvis du sender til EU med Verified Account-kontoen din, krever EU produktidentifikatorer (PID-er) på sendinger fra bedrift til forbruker (B2C) med en verdi på 150 EUR eller mindre, fra og med 1. november 2026. Lagre dem på katalogartiklene dine. For de fleste Verified Accounts er det postoperatøren din som sender sendingsdataene til Zonos, og Zonos matcher hver artikkel i sendingen mot katalogen din og bruker identifikatorene du har lagret, så du trenger ikke å sende noe ekstra når du sender pakken.
skumanufacturerProductIdgtinSend identifikatorene med
catalogItemCreatefor nye produkter. For produkter som allerede ligger i katalogen din, sender du dem medcatalogItemUpdate, som tar de samme feltene. Sørg for at hver artikkelsskusamsvarer med SKU-en du bruker overalt ellers, slik at Zonos kan koble de to sammen.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}Send
gtinkun som sifre, uten bindestreker eller mellomrom. UPC-, EAN-, JAN- og 13-sifrede ISBN-verdier går alle i dette ene feltet. Hvis du har et 10-sifret ISBN, sender du den 13-sifrede versjonen i stedet.Hvis et produkt ikke har strekkode, utelater du
gtini stedet for å sende en tom streng, gjenbruke SKU-en din eller fylle feltet med plassholdertekst somN/A.Hvis du kaller Landed Cost API selv, kan du også ta med disse identifikatorene i landed cost-forespørselen din. De fleste Verified Accounts gjør ikke det, fordi det er postoperatøren som sender sendingsdataene til Zonos.
Se veiledningen om EU-produktidentifikatorer for hva regelverket krever.
Gjør artiklene dine matchbare
Zonos kobler hver sendingslinje tilbake til en katalogartikkel ved hjelp av identifikatorene dine, i denne rekkefølgen: produkt-ID, deretter SKU, deretter navn. Hold identifikatorene du bruker nøyaktige og konsistente mellom katalogen din og dataene du sender til transportøren.
Postsendinger har en ytterligere begrensning. Zonos mottar et begrenset sett med felt fra posttransportører, og på mange ruter er tollbeskrivelsen det eneste feltet som inneholder noe produktspesifikt. En beskrivelse som er identisk på tvers av hele katalogen din, kan ikke identifisere noe på egen hånd.
Hvordan du formaterer identifikatoren i sendingsdataene du sender til transportøren, avhenger av postoperatøren din, fordi hver postoperatør matcher sendinger mot katalogen din på sin egen måte. Gå til alle postoperatører og velg din. Siden for postoperatøren viser hvordan matchingen fungerer for akkurat den, og nøyaktig hva du skal sende.
Det er ikke påkrevd å sette artikkelens
customsDescriptiontil den samme strengen du sender til transportøren, men det gjør de to sidene direkte sammenlignbare når en linje ikke matcher og du må finne ut hvorfor.Matching mislykkes vanligvis når:
Oppdater katalogartikler
catalogItemUpdatebruker samme inndatatype som opprettelse. Send bare feltene du vil endre.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Les artiklene dine tilbake
Spørringen
catalogItemgodtarid,productIdellersku. Bruk den til å bekrefte hvilke data Zonos har for et produkt.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Slett katalogartikler
catalogItemDeletetar Zonos-katalogartikkel-ID-er, ikke SKU-ene eller produkt-ID-ene dine. Finn ID-en med spørringencatalogItemførst.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Relatert
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Var denne siden nyttig?