Opbyg dit Verified Account-katalog programmatisk, direkte fra dit eget system.
Catalog API er en af tre måder at opbygge dit Verified Account-katalog på, og det er muligheden for forsendere med udviklerressourcer og et system, der allerede indeholder deres produktdata—et ERP-, WMS-, PIM-system eller en forsendelsesplatform. Det system forbliver den autoritative kilde og skriver produkter direkte til Zonos i stedet for at synkronisere fra en kanalintegration eller uploade en CSV-fil. Hvis du sælger via en understøttet kanal, eller hvis du helst ikke vil skrive kode, opbygger de to muligheder det samme katalog med mindre arbejde.
Varer, der oprettes via API'et, behandles præcis som varer fra enhver anden kilde—når en vare først er i dit katalog, er det ligegyldigt for Zonos, hvordan den kom derind. Hver vare klassificeres til toldformål, hvis du ikke har angivet en HS-kode, screenes for krav fra amerikanske Partner Government Agencies (PGA) og bruges til at beregne told og afgifter på de forsendelser, den indgår i.
Én del af det ligger uden for API'et. Når PGA-screeningen markerer en vare som Needs attention, skal det compliance-spørgeskema, der ligger bag markeringen, besvares og bekræftes i Dashboard—der findes ikke noget API til det, og Zonos udfylder på forhånd, hvad der kan udfyldes, så det meste af arbejdet består i at gennemgå og bekræfte. Den person, der bygger integrationen, er som regel ikke den samme, som rydder markeringerne, så planlæg, at nogen i din organisation gennemgår dem i Dashboard, når dit katalog er indlæst. Markerede varer blokeres ikke fra at blive sendt, men ved at rydde markeringerne, før du sender, undgår du, at en forsendelse bliver tilbageholdt ved den amerikanske grænse.
Hvis du sender et produkt, hvis SKU eller produkt-id allerede findes, opdaterer Zonos det produkt i stedet for at tilføje et nyt. Genforsøg og gentagne kørsler er sikre.
Bagsiden er, at to forskellige produkter med samme SKU eller produkt-id bliver slået sammen til ét. Tjek dine data for dubletter før en masseindlæsning.
Din unikke identifikator for produktet. *Hvert produkt skal have en SKU eller et produkt-id, eller begge.
productId
Ja*
Din platforms identifikator for produktet. *Hvert produkt skal have en SKU eller et produkt-id, eller begge.
manufacturerProductId
Kun EU
Den ikke-standardiserede producentproduktidentifikator (NS-PID). Påkrævet på B2C-forsendelser til EU med en værdi på 150 EUR eller derunder.
gtin
Kun EU
Den standardiserede producentproduktidentifikator (S-PID), kun cifre. Påkrævet på B2C-forsendelser til EU med en værdi på 150 EUR eller derunder, hvis produktet har en stregkode.
name
Ja
Produktnavnet.
customsDescription
Anbefalet
Hvad produktet er, i klare vendinger, til tolderklæringen. Brug "Bomulds-t-shirt", ikke "Summer Vibes Tee".
countryOfOrigin
Anbefalet
Den 2-bogstavs ISO-kode for, hvor produktet er fremstillet. Nødvendig for at beregne told nøjagtigt.
measurements
Anbefalet
Vægt og dimensioner, der bruges til fragtberegning og toldindberetning.
hsCode
Nej
Den universelle 6-cifrede HS-kode. Hvis du udelader den, klassificerer Zonos produktet ud fra navn og beskrivelse.
amount
Nej
Produktets pris som et tal.
currencyCode
Nej
Den 3-bogstavs ISO-kode for prisens valuta. Påkrævet, når du angiver amount.
itemType
Nej
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE eller PARTIAL_ITEM. Forhindrer, at ikke-fysiske varer deklareres som handelsvarer.
provinceOfOrigin
Nej
Den stat eller provins, hvor produktet har oprindelse. Kræves af nogle destinationslande.
productComposition
Nej
En liste af {material, percentage}. Tekstiler kan ikke klassificeres ud over 6 cifre uden den.
catalogItemUrl
Nej
Et link til produktsiden på dit website. Forbedrer klassificeringens nøjagtighed.
imageUrl
Nej
En offentligt tilgængelig URL til produktbilledet. Forbedrer klassificeringens nøjagtighed.
Tilføj EU-produktidentifikatorer (PID'er)
Hvis du sender til EU med din Verified Account, kræver EU fra den 1. november 2026 produktidentifikatorer (PID'er) på business-to-consumer-forsendelser (B2C) med en værdi på 150 EUR eller derunder. Gem dem på dine katalogvarer. For de fleste Verified Accounts sender dit postselskab forsendelsesdataene til Zonos, og Zonos matcher hver vare på forsendelsen med dit katalog og anvender de identifikatorer, du har gemt, så du ikke skal sende noget ekstra, når du afsender.
Send identifikatorerne med catalogItemCreate for nye produkter. For produkter, der allerede er i dit katalog, skal du sende dem med catalogItemUpdate, som tager de samme felter. Sørg for, at hver vares sku matcher den SKU, du bruger alle andre steder, så Zonos kan forbinde de to.
Send gtin som kun cifre, uden bindestreger eller mellemrum. UPC-, EAN-, JAN- og 13-cifrede ISBN-værdier går alle i dette ene felt. Hvis du har et 10-cifret ISBN, skal du sende den 13-cifrede version i stedet.
Hvis et produkt ikke har en stregkode, skal du udelade gtin i stedet for at sende en tom streng, genbruge din SKU eller udfylde det med pladsholdertekst som N/A.
Zonos forbinder hver forsendelseslinje med en katalogvare ved hjælp af dine identifikatorer i denne rækkefølge: produkt-id, derefter SKU og til sidst navn. Hold de identifikatorer, du bruger, nøjagtige og konsistente mellem dit katalog og de data, du sender til dit fragtselskab.
Postforsendelser har en yderligere begrænsning. Zonos modtager et begrænset sæt felter fra postselskaber, og på mange ruter er tolderklæringens varebeskrivelse det eneste felt, der indeholder noget produktspecifikt. En beskrivelse, der er identisk på tværs af hele dit katalog, kan ikke i sig selv identificere noget.
Hvordan identifikatoren skal formateres i de forsendelsesdata, du sender til dit fragtselskab, afhænger af dit postselskab, fordi hvert postselskab matcher forsendelser med dit katalog på forskellig måde. Gå til alle postselskaber, og vælg dit postselskab. Dets side viser, hvordan matchning fungerer for det pågældende postselskab, og præcis hvad du skal sende.
Det er ikke påkrævet at sætte varens customsDescription til den samme streng, som du sender til dit fragtselskab, men det gør de to sider direkte sammenlignelige, når en linje ikke matcher, og du skal finde ud af hvorfor.
Matchning mislykkes typisk, når:
Den identifikator, dit postselskab matcher på, mangler i forsendelsesdataene.
Identifikatoren ikke matcher noget i dit katalog nøjagtigt.
Identifikatoren afkortes af fragtselskabets tegngrænse.
Formateringen ændrer sig mellem forsendelser.
Denne funktionalitet er stadig under færdiggørelse og kan ændre sig før lancering.
Opdater katalogvarer
catalogItemUpdate bruger den samme inputtype som oprettelse. Send kun de felter, du vil ændre.
Bemærk: Udeladte felter forbliver uændrede, hvilket gør delvise opdateringer sikre. At sende null rydder ikke en værdi, det ignoreres. Du kan overskrive en værdi med en anden, men du kan ikke tømme den via API'et. Kontakt din Zonos-repræsentant, hvis et felt skal ryddes.
Læs dine varer tilbage
catalogItem-forespørgslen accepterer id, productId eller sku. Brug den til at bekræfte, 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}
Slet katalogvarer
catalogItemDelete tager Zonos-katalogvare-id'er, ikke dine SKU'er eller produkt-id'er. Find først id'et med catalogItem-forespørgslen.
Catalog API
Catalog API
Opbyg dit Verified Account-katalog programmatisk, direkte fra dit eget system.
Catalog API er en af tre måder at opbygge dit Verified Account-katalog på, og det er muligheden for forsendere med udviklerressourcer og et system, der allerede indeholder deres produktdata—et ERP-, WMS-, PIM-system eller en forsendelsesplatform. Det system forbliver den autoritative kilde og skriver produkter direkte til Zonos i stedet for at synkronisere fra en kanalintegration eller uploade en CSV-fil. Hvis du sælger via en understøttet kanal, eller hvis du helst ikke vil skrive kode, opbygger de to muligheder det samme katalog med mindre arbejde.
Varer, der oprettes via API'et, behandles præcis som varer fra enhver anden kilde—når en vare først er i dit katalog, er det ligegyldigt for Zonos, hvordan den kom derind. Hver vare klassificeres til toldformål, hvis du ikke har angivet en HS-kode, screenes for krav fra amerikanske Partner Government Agencies (PGA) og bruges til at beregne told og afgifter på de forsendelser, den indgår i.
Én del af det ligger uden for API'et. Når PGA-screeningen markerer en vare som Needs attention, skal det compliance-spørgeskema, der ligger bag markeringen, besvares og bekræftes i Dashboard—der findes ikke noget API til det, og Zonos udfylder på forhånd, hvad der kan udfyldes, så det meste af arbejdet består i at gennemgå og bekræfte. Den person, der bygger integrationen, er som regel ikke den samme, som rydder markeringerne, så planlæg, at nogen i din organisation gennemgår dem i Dashboard, når dit katalog er indlæst. Markerede varer blokeres ikke fra at blive sendt, men ved at rydde markeringerne, før du sender, undgår du, at en forsendelse bliver tilbageholdt ved den amerikanske grænse.
Sådan fungerer det
Opret en katalogvare for hvert produkt, du sender.
Sørg for, at hver vare har en identifikator, som dit postselskab videregiver.
Når dine forsendelsesdata når Zonos, matches hver linje tilbage til din katalogvare, og varens produktdata anvendes i beregningen.
Opret katalogvarer
catalogItemCreateaccepterer en liste, så du kan sende mange produkter i en enkelt anmodning.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Afsendelse af det samme produkt to gange
Hvis du sender et produkt, hvis SKU eller produkt-id allerede findes, opdaterer Zonos det produkt i stedet for at tilføje et nyt. Genforsøg og gentagne kørsler er sikre.
Bagsiden er, at to forskellige produkter med samme SKU eller produkt-id bliver slået sammen til ét. Tjek dine data for dubletter før en masseindlæsning.
Felter
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEellerPARTIAL_ITEM. Forhindrer, at ikke-fysiske varer deklareres som handelsvarer.provinceOfOriginproductComposition{material, percentage}. Tekstiler kan ikke klassificeres ud over 6 cifre uden den.catalogItemUrlimageUrlTilføj EU-produktidentifikatorer (PID'er)
Hvis du sender til EU med din Verified Account, kræver EU fra den 1. november 2026 produktidentifikatorer (PID'er) på business-to-consumer-forsendelser (B2C) med en værdi på 150 EUR eller derunder. Gem dem på dine katalogvarer. For de fleste Verified Accounts sender dit postselskab forsendelsesdataene til Zonos, og Zonos matcher hver vare på forsendelsen med dit katalog og anvender de identifikatorer, du har gemt, så du ikke skal sende noget ekstra, når du afsender.
skumanufacturerProductIdgtinSend identifikatorerne med
catalogItemCreatefor nye produkter. For produkter, der allerede er i dit katalog, skal du sende dem medcatalogItemUpdate, som tager de samme felter. Sørg for, at hver varesskumatcher den SKU, du bruger alle andre steder, så Zonos kan forbinde de to.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}Send
gtinsom kun cifre, uden bindestreger eller mellemrum. UPC-, EAN-, JAN- og 13-cifrede ISBN-værdier går alle i dette ene felt. Hvis du har et 10-cifret ISBN, skal du sende den 13-cifrede version i stedet.Hvis et produkt ikke har en stregkode, skal du udelade
gtini stedet for at sende en tom streng, genbruge din SKU eller udfylde det med pladsholdertekst somN/A.Hvis du selv kalder Landed Cost API, kan du også inkludere disse identifikatorer i din landed cost-anmodning. De fleste Verified Accounts gør det ikke, fordi det er postselskabet, der sender forsendelsesdataene til Zonos.
Se vejledningen om EU-produktidentifikatorer for, hvad forordningen kræver.
Gør dine varer matchbare
Zonos forbinder hver forsendelseslinje med en katalogvare ved hjælp af dine identifikatorer i denne rækkefølge: produkt-id, derefter SKU og til sidst navn. Hold de identifikatorer, du bruger, nøjagtige og konsistente mellem dit katalog og de data, du sender til dit fragtselskab.
Postforsendelser har en yderligere begrænsning. Zonos modtager et begrænset sæt felter fra postselskaber, og på mange ruter er tolderklæringens varebeskrivelse det eneste felt, der indeholder noget produktspecifikt. En beskrivelse, der er identisk på tværs af hele dit katalog, kan ikke i sig selv identificere noget.
Hvordan identifikatoren skal formateres i de forsendelsesdata, du sender til dit fragtselskab, afhænger af dit postselskab, fordi hvert postselskab matcher forsendelser med dit katalog på forskellig måde. Gå til alle postselskaber, og vælg dit postselskab. Dets side viser, hvordan matchning fungerer for det pågældende postselskab, og præcis hvad du skal sende.
Det er ikke påkrævet at sætte varens
customsDescriptiontil den samme streng, som du sender til dit fragtselskab, men det gør de to sider direkte sammenlignelige, når en linje ikke matcher, og du skal finde ud af hvorfor.Matchning mislykkes typisk, når:
Opdater katalogvarer
catalogItemUpdatebruger den samme inputtype som oprettelse. Send kun de felter, du vil ændre.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Læs dine varer tilbage
catalogItem-forespørgslen acceptererid,productIdellersku. Brug den til at bekræfte, hvilke data Zonos har for et produkt.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Slet katalogvarer
catalogItemDeletetager Zonos-katalogvare-id'er, ikke dine SKU'er eller produkt-id'er. Find først id'et medcatalogItem-forespørgslen.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Relateret
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Var denne side nyttig?