DOCS
HemPostala utgående lösningar Verktyg för avsändare Verified Accounts Katalog-API

Katalog-API

Bygg katalogen för ditt verifierade konto programmatiskt, direkt från ditt eget system.

Katalog-API:t är ett av tre sätt att bygga upp katalogen för ditt verifierade konto, och det är alternativet för avsändare som har utvecklarresurser och ett system som redan innehåller deras produktdata—ett affärssystem (ERP), lagerhanteringssystem (WMS), PIM-system eller en fraktplattform. Det systemet förblir den primära datakällan och skriver produkter direkt till Zonos, i stället för att synkronisera från en kanalintegration eller ladda upp en CSV-fil. Om du säljer via en kanal som stöds, eller hellre slipper skriva kod, bygger de två alternativen samma katalog med mindre arbete.

Artiklar som skapas via API:t behandlas exakt som artiklar från alla andra källor—när en artikel väl finns i din katalog spelar det ingen roll för Zonos hur den kom dit. Varje artikel klassificeras för tullen om du inte angav någon HS-kod, granskas mot krav från amerikanska myndigheter (Partner Government Agencies, PGA) och används för att beräkna tullar och skatter på de sändningar den ingår i.

En del av detta ligger utanför API:t. När PGA-granskningen flaggar en artikel som Behöver åtgärd måste det frågeformulär om efterlevnad som ligger bakom flaggan besvaras och bekräftas i Dashboard—det finns inget API för det, och Zonos fyller i det som går i förväg så att det mesta av arbetet består av att granska och bekräfta. Den som bygger integrationen är oftast inte samma person som hanterar flaggorna, så planera för att någon i din organisation går igenom dem i Dashboard när katalogen har lästs in. Flaggade artiklar blockeras inte från att skickas, men att åtgärda flaggorna innan du skickar är det som förhindrar att en sändning hålls kvar vid den amerikanska gränsen.

Så fungerar det 

  1. Skapa en katalogartikel för varje produkt du skickar.

  2. Se till att varje artikel har en identifierare som ditt postbefordringsföretag vidarebefordrar.

  3. När dina sändningsdata når Zonos matchas varje rad mot din katalogartikel, och artikelns produktdata tillämpas i beräkningen.

Skapa katalogartiklar 

catalogItemCreate tar emot en lista, så du kan skicka många produkter i en enda begäran.

1mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
2 catalogItemCreate(input: $input) {
3 id
4 itemKey
5 name
6 productId
7 sku
8 hsCode
9 customsDescription
10 countryOfOrigin
11 }
12}

Skicka samma produkt två gånger

Om du skickar en produkt vars SKU eller produkt-ID redan finns uppdaterar Zonos den produkten i stället för att lägga till en till. Omförsök och upprepade körningar är därför säkra.

Baksidan är att två olika produkter som delar SKU eller produkt-ID slås samman till en. Kontrollera dina data efter dubbletter innan en massinläsning.

Fält

Fält↕Obligatoriskt↕Beskrivning↕
skuJa*Din unika identifierare för produkten. *Varje produkt behöver en SKU eller ett produkt-ID, eller båda.
productIdJa*Din plattforms identifierare för produkten. *Varje produkt behöver en SKU eller ett produkt-ID, eller båda.
nameJaProduktens namn.
customsDescriptionRekommenderasVad produkten är, i klartext, för tulldeklarationen. Använd ”Cotton t-shirt”, inte ”Summer Vibes Tee”.
countryOfOriginRekommenderasDen tvåbokstaviga ISO-koden för landet där produkten tillverkades. Behövs för att beräkna tullen korrekt.
measurementsRekommenderasVikt och mått, som används för fraktberäkning och tulldeklaration.
hsCodeNejDen universella sexsiffriga HS-koden. Om du utelämnar den klassificerar Zonos produkten utifrån dess namn och beskrivning.
amountNejProduktens pris som ett tal.
currencyCodeNejDen trebokstaviga ISO-koden för prisets valuta. Obligatorisk när du anger amount.
itemTypeNejPHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE eller PARTIAL_ITEM. Förhindrar att icke-fysiska artiklar deklareras som handelsvaror.
provinceOfOriginNejDelstaten eller provinsen där produkten har sitt ursprung. Krävs av vissa destinationsländer.
productCompositionNejEn lista med {material, percentage}. Textilier kan inte klassificeras bortom sex siffror utan den.
catalogItemUrlNejEn länk till produktsidan på din webbplats. Förbättrar klassificeringens träffsäkerhet.
imageUrlNejEn offentligt tillgänglig URL till produktbilden. Förbättrar klassificeringens träffsäkerhet.

Gör dina artiklar matchningsbara 

Zonos kopplar varje sändningsrad till en katalogartikel med hjälp av dina identifierare, i denna ordning: produkt-ID, sedan SKU och sedan namn. Håll de identifierare du använder korrekta och konsekventa mellan din katalog och de data du skickar till ditt fraktbolag.

Postsändningar innebär ytterligare en begränsning. Zonos tar emot en begränsad uppsättning fält från postbefordringsföretag, och på många rutter är tullbeskrivningen det enda fält som innehåller något produktspecifikt. En beskrivning som är identisk i hela din katalog kan inte identifiera något på egen hand.

Lägg till ditt produkt-ID eller din SKU i slutet av tullbeskrivningen du skickar till ditt fraktbolag.

Men's bifold wallet, cowhide leather - 123456

Den tillagda identifieraren måste exakt matcha productId eller sku på motsvarande katalogartikel.

Beskrivningsfälten är korta. Canada Post tillåter till exempel ungefär 49 tecken, så korta ned den beskrivande delen om dina identifierare är långa. Identifieraren är viktigare än texten.

Det krävs inte att artikelns customsDescription sätts till samma sträng som du skickar till ditt fraktbolag, men det gör de två sidorna direkt jämförbara när en rad inte matchar och du behöver ta reda på varför.

Matchningen misslyckas ofta när:

  • Identifieraren saknas i beskrivningen.
  • Identifieraren inte motsvarar något productId eller någon sku i din katalog.
  • Identifieraren kortas av på grund av fraktbolagets teckengräns.
  • Formateringen ändras mellan sändningar.

Det här beteendet finslipas fortfarande och kan ändras innan lansering.

Uppdatera katalogartiklar 

catalogItemUpdate använder samma indatatyp som create. Skicka bara de fält du vill ändra.

1mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
2 catalogItemUpdate(input: $input) {
3 id
4 itemKey
5 hsCode
6 customsDescription
7 }
8}

Obs: Utelämnade fält lämnas orörda, vilket gör partiella uppdateringar säkra. Att skicka null rensar inte ett värde, det ignoreras. Du kan skriva över ett värde med ett annat, men du kan inte tömma det via API:t. Kontakta din Zonos-representant om du behöver få ett fält rensat.

Läs tillbaka dina artiklar 

Frågan catalogItem tar emot id, productId eller sku. Använd den för att bekräfta vad Zonos har lagrat för en produkt.

1query CatalogItem($sku: String!) {
2 catalogItem(sku: $sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11 }
12}

Radera katalogartiklar 

catalogItemDelete tar emot Zonos katalogartikel-ID:n, inte dina SKU:er eller produkt-ID:n. Hämta ID:t med frågan catalogItem först.

1mutation CatalogItemDelete($input: [ID!]!) {
2 catalogItemDelete(input: $input)
3}

Relaterat 

  • Kanalintegrationer — Synkronisera din katalog automatiskt från en säljkanal som stöds.
  • CSV-import — Ladda upp katalogartiklar med ett kalkylark i stället för att skriva kod.
  • PGA-kontroller — Granska dina katalogartiklar mot krav från amerikanska myndigheter (PGA).
  • Så fungerar Catalog — Vad Zonos gör med dina produktdata.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate

Var den här sidan till hjälp?

Få support·Juridiska dokument·© 2026 Zonos
På den här sidan:
  • Katalog-API
  • Så fungerar det
  • Skapa katalogartiklar
  • Gör dina artiklar matchningsbara
  • Uppdatera katalogartiklar
  • Läs tillbaka dina artiklar
  • Radera katalogartiklar
  • Relaterat