Buduj katalog zweryfikowanego konta programowo, bezpośrednio z własnego systemu.
Catalog API to jeden z trzech sposobów budowania katalogu zweryfikowanego konta i jest to opcja dla nadawców, którzy dysponują zasobami programistycznymi oraz systemem przechowującym już dane ich produktów—ERP, WMS, PIM lub platformą do wysyłek. Ten system pozostaje źródłem prawdy i zapisuje produkty bezpośrednio w Zonos, zamiast synchronizować je z integracji z kanałem sprzedaży lub przesyłać plik CSV. Jeśli sprzedajesz przez obsługiwany kanał lub wolisz nie pisać kodu, te dwie opcje pozwalają zbudować ten sam katalog mniejszym nakładem pracy.
Pozycje utworzone przez API są traktowane dokładnie tak samo jak pozycje z każdego innego źródła—gdy pozycja trafi do katalogu, dla Zonos nie ma znaczenia, w jaki sposób się tam znalazła. Każda z nich jest klasyfikowana na potrzeby celne, jeśli nie podano kodu HS, sprawdzana pod kątem wymogów amerykańskich agencji rządowych (Partner Government Agency, PGA) i wykorzystywana do obliczania ceł i podatków od przesyłek, w których się pojawia.
Jeden element tego procesu pozostaje poza API. Gdy kontrola PGA oznaczy pozycję jako Needs attention, kwestionariusz zgodności powiązany z tym oznaczeniem trzeba wypełnić i potwierdzić w Dashboard—nie ma do tego API, a Zonos wstępnie uzupełnia wszystko, co może, więc większość pracy polega na przejrzeniu i potwierdzeniu odpowiedzi. Osoba budująca tę integrację zwykle nie jest tą samą osobą, która obsługuje te oznaczenia, dlatego zaplanuj, że ktoś w Twojej organizacji zajmie się nimi w Dashboard po załadowaniu katalogu. Oznaczone pozycje nie są blokowane przed wysyłką, ale ich wyjaśnienie przed nadaniem przesyłki zapobiega jej zatrzymaniu na granicy USA.
Utwórz pozycję katalogu dla każdego wysyłanego produktu.
Upewnij się, że każda pozycja zawiera identyfikator, który Twój przewoźnik pocztowy przekaże dalej.
Gdy dane Twojej przesyłki trafią do Zonos, każda linia zostaje dopasowana do odpowiedniej pozycji katalogu, a dane produktu z tej pozycji są uwzględniane w obliczeniach.
Tworzenie pozycji katalogu
catalogItemCreate przyjmuje listę, dzięki czemu możesz wysłać wiele produktów w jednym żądaniu.
Jeśli wyślesz produkt, którego SKU lub identyfikator produktu już istnieje, Zonos zaktualizuje ten produkt zamiast dodawać drugi. Ponowne próby i powtarzane uruchomienia są bezpieczne.
Druga strona medalu jest taka, że dwa różne produkty o tym samym SKU lub identyfikatorze produktu zostaną scalone w jeden. Przed zbiorczym załadowaniem sprawdź dane pod kątem duplikatów.
Twój unikalny identyfikator produktu. *Każdy produkt wymaga SKU lub identyfikatora produktu albo obu.
productId
Tak*
Identyfikator produktu na Twojej platformie. *Każdy produkt wymaga SKU lub identyfikatora produktu albo obu.
manufacturerProductId
Tylko UE
Niestandaryzowany identyfikator produktu producenta (NS-PID). Wymagany w przesyłkach B2C do UE o wartości do 150 EUR.
gtin
Tylko UE
Standaryzowany identyfikator produktu producenta (S-PID), wyłącznie cyfry. Wymagany w przesyłkach B2C do UE o wartości do 150 EUR, jeśli produkt ma kod kreskowy.
name
Tak
Nazwa produktu.
customsDescription
Zalecane
Prosty opis tego, czym jest produkt, na potrzeby zgłoszenia celnego. Używaj „Koszulka bawełniana”, a nie „Summer Vibes Tee”.
countryOfOrigin
Zalecane
Dwuliterowy kod ISO kraju, w którym produkt został wyprodukowany. Niezbędny do dokładnego obliczenia cła.
measurements
Zalecane
Waga i wymiary, wykorzystywane do wyceny wysyłki i zgłoszeń celnych.
hsCode
Nie
Uniwersalny 6-cyfrowy kod HS. Jeśli go pominiesz, Zonos sklasyfikuje produkt na podstawie jego nazwy i opisu.
amount
Nie
Cena produktu jako liczba.
currencyCode
Nie
Trzyliterowy kod ISO waluty ceny. Wymagany, gdy podajesz amount.
itemType
Nie
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE lub PARTIAL_ITEM. Zapobiega zgłaszaniu pozycji niefizycznych jako towarów.
provinceOfOrigin
Nie
Stan lub prowincja, z której pochodzi produkt. Wymagane przez niektóre kraje docelowe.
productComposition
Nie
Lista {material, percentage}. Bez niej tekstyliów nie można sklasyfikować powyżej 6 cyfr.
catalogItemUrl
Nie
Link do strony produktu w Twoim sklepie. Zwiększa dokładność klasyfikacji.
imageUrl
Nie
Publicznie dostępny adres URL zdjęcia produktu. Zwiększa dokładność klasyfikacji.
Jeśli wysyłasz towary do UE w ramach konta zweryfikowanego, od 1 listopada 2026 r. UE wymaga identyfikatorów produktów (PID) w przesyłkach między firmą a konsumentem (B2C) o wartości do 150 EUR. Przechowuj je w pozycjach katalogu. W przypadku większości kont zweryfikowanych to operator pocztowy przesyła do Zonos dane przesyłki, a Zonos dopasowuje każdą pozycję przesyłki do Twojego katalogu i stosuje zapisane identyfikatory, więc w momencie wysyłki nie musisz przesyłać niczego dodatkowo.
Identyfikator↕
Czym jest↕
Pole API↕
Wymagany?↕
Identyfikator produktu sprzedawcy (M-PID)
Twoje SKU lub kod pozycji
sku
Zawsze
Niestandaryzowany identyfikator produktu producenta (NS-PID)
Numer modelu lub numer części producenta. Jeśli sam wytwarzasz produkt, użyj własnego numeru modelu lub numeru części.
manufacturerProductId
Zawsze
Standaryzowany identyfikator produktu producenta (S-PID)
Kod kreskowy (UPC, EAN lub ISBN)
gtin
Tylko jeśli produkt go ma
W przypadku nowych produktów wyślij identyfikatory za pomocą catalogItemCreate. W przypadku produktów, które są już w katalogu, wyślij je za pomocą catalogItemUpdate, która przyjmuje te same pola. Dopilnuj, aby sku każdej pozycji odpowiadało SKU, którego używasz we wszystkich innych miejscach, aby Zonos mógł je ze sobą powiązać.
Wysyłaj gtin wyłącznie jako cyfry, bez myślników i spacji. Wartości UPC, EAN, JAN i 13-cyfrowe numery ISBN trafiają do tego jednego pola. Jeśli masz 10-cyfrowy numer ISBN, wyślij zamiast niego wersję 13-cyfrową.
Jeśli produkt nie ma kodu kreskowego, pomiń gtin zamiast wysyłać pusty ciąg, ponownie używać SKU lub wpisywać tekst zastępczy, taki jak N/A.
Jeśli samodzielnie wywołujesz Landed Cost API, możesz również uwzględnić te identyfikatory w żądaniu landed cost. Większość kont zweryfikowanych tego nie robi, ponieważ to operator pocztowy przesyła do Zonos dane przesyłki.
Zonos łączy każdą linię przesyłki z pozycją katalogu na podstawie Twoich identyfikatorów, w następującej kolejności: identyfikator produktu, następnie SKU, a na końcu nazwa. Dbaj o to, aby używane identyfikatory były dokładne i spójne między katalogiem a danymi przesyłanymi przewoźnikowi.
W przypadku przesyłek pocztowych obowiązuje dodatkowe ograniczenie. Zonos otrzymuje od przewoźników pocztowych ograniczony zestaw pól, a na wielu trasach opis celny jest jedynym polem zawierającym jakiekolwiek informacje specyficzne dla produktu. Opis identyczny w całym katalogu sam w sobie niczego nie identyfikuje.
Sposób formatowania identyfikatora w danych przesyłki wysyłanych przewoźnikowi zależy od operatora pocztowego, ponieważ każdy z nich dopasowuje przesyłki do Twojego katalogu inaczej. Przejdź do wszystkich operatorów pocztowych i wybierz swojego operatora. Na jego stronie znajdziesz informacje o tym, jak działa dopasowywanie w przypadku tego operatora i co dokładnie należy wysyłać.
Ustawienie w pozycji wartości customsDescription na ten sam ciąg, który wysyłasz przewoźnikowi, nie jest wymagane, ale pozwala bezpośrednio porównać obie strony, gdy linia nie zostanie dopasowana i trzeba ustalić przyczynę.
Dopasowanie najczęściej się nie udaje, gdy:
W danych przesyłki brakuje identyfikatora, na podstawie którego dopasowuje Twój operator pocztowy.
Identyfikator nie odpowiada dokładnie niczemu w Twoim katalogu.
Identyfikator zostaje obcięty przez limit znaków przewoźnika.
Formatowanie zmienia się między przesyłkami.
To zachowanie nie jest jeszcze ostatecznie ustalone i może ulec zmianie przed premierą.
Aktualizowanie pozycji katalogu
catalogItemUpdate przyjmuje ten sam typ danych wejściowych co tworzenie. Wysyłaj tylko te pola, które chcesz zmienić.
Uwaga: Pominięte pola pozostają bez zmian, dzięki czemu częściowe aktualizacje są bezpieczne. Wysłanie null nie czyści wartości—jest ignorowane. Możesz nadpisać wartość inną wartością, ale nie możesz jej wyczyścić przez API. Jeśli chcesz wyczyścić pole, skontaktuj się ze swoim przedstawicielem Zonos.
Odczytywanie pozycji
Zapytanie catalogItem przyjmuje id, productId lub sku. Użyj go, aby sprawdzić, jakie dane o produkcie przechowuje Zonos.
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}
Usuwanie pozycji katalogu
catalogItemDelete przyjmuje identyfikatory pozycji katalogu Zonos, a nie Twoje SKU ani identyfikatory produktów. Najpierw ustal identyfikator za pomocą zapytania catalogItem.
Catalog API
Catalog API
Buduj katalog zweryfikowanego konta programowo, bezpośrednio z własnego systemu.
Catalog API to jeden z trzech sposobów budowania katalogu zweryfikowanego konta i jest to opcja dla nadawców, którzy dysponują zasobami programistycznymi oraz systemem przechowującym już dane ich produktów—ERP, WMS, PIM lub platformą do wysyłek. Ten system pozostaje źródłem prawdy i zapisuje produkty bezpośrednio w Zonos, zamiast synchronizować je z integracji z kanałem sprzedaży lub przesyłać plik CSV. Jeśli sprzedajesz przez obsługiwany kanał lub wolisz nie pisać kodu, te dwie opcje pozwalają zbudować ten sam katalog mniejszym nakładem pracy.
Pozycje utworzone przez API są traktowane dokładnie tak samo jak pozycje z każdego innego źródła—gdy pozycja trafi do katalogu, dla Zonos nie ma znaczenia, w jaki sposób się tam znalazła. Każda z nich jest klasyfikowana na potrzeby celne, jeśli nie podano kodu HS, sprawdzana pod kątem wymogów amerykańskich agencji rządowych (Partner Government Agency, PGA) i wykorzystywana do obliczania ceł i podatków od przesyłek, w których się pojawia.
Jeden element tego procesu pozostaje poza API. Gdy kontrola PGA oznaczy pozycję jako Needs attention, kwestionariusz zgodności powiązany z tym oznaczeniem trzeba wypełnić i potwierdzić w Dashboard—nie ma do tego API, a Zonos wstępnie uzupełnia wszystko, co może, więc większość pracy polega na przejrzeniu i potwierdzeniu odpowiedzi. Osoba budująca tę integrację zwykle nie jest tą samą osobą, która obsługuje te oznaczenia, dlatego zaplanuj, że ktoś w Twojej organizacji zajmie się nimi w Dashboard po załadowaniu katalogu. Oznaczone pozycje nie są blokowane przed wysyłką, ale ich wyjaśnienie przed nadaniem przesyłki zapobiega jej zatrzymaniu na granicy USA.
Jak to działa
Utwórz pozycję katalogu dla każdego wysyłanego produktu.
Upewnij się, że każda pozycja zawiera identyfikator, który Twój przewoźnik pocztowy przekaże dalej.
Gdy dane Twojej przesyłki trafią do Zonos, każda linia zostaje dopasowana do odpowiedniej pozycji katalogu, a dane produktu z tej pozycji są uwzględniane w obliczeniach.
Tworzenie pozycji katalogu
catalogItemCreateprzyjmuje listę, dzięki czemu możesz wysłać wiele produktów w jednym żądaniu.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Ponowne wysłanie tego samego produktu
Jeśli wyślesz produkt, którego SKU lub identyfikator produktu już istnieje, Zonos zaktualizuje ten produkt zamiast dodawać drugi. Ponowne próby i powtarzane uruchomienia są bezpieczne.
Druga strona medalu jest taka, że dwa różne produkty o tym samym SKU lub identyfikatorze produktu zostaną scalone w jeden. Przed zbiorczym załadowaniem sprawdź dane pod kątem duplikatów.
Pola
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLElubPARTIAL_ITEM. Zapobiega zgłaszaniu pozycji niefizycznych jako towarów.provinceOfOriginproductComposition{material, percentage}. Bez niej tekstyliów nie można sklasyfikować powyżej 6 cyfr.catalogItemUrlimageUrlDodawanie unijnych identyfikatorów produktów (PID)
Jeśli wysyłasz towary do UE w ramach konta zweryfikowanego, od 1 listopada 2026 r. UE wymaga identyfikatorów produktów (PID) w przesyłkach między firmą a konsumentem (B2C) o wartości do 150 EUR. Przechowuj je w pozycjach katalogu. W przypadku większości kont zweryfikowanych to operator pocztowy przesyła do Zonos dane przesyłki, a Zonos dopasowuje każdą pozycję przesyłki do Twojego katalogu i stosuje zapisane identyfikatory, więc w momencie wysyłki nie musisz przesyłać niczego dodatkowo.
skumanufacturerProductIdgtinW przypadku nowych produktów wyślij identyfikatory za pomocą
catalogItemCreate. W przypadku produktów, które są już w katalogu, wyślij je za pomocącatalogItemUpdate, która przyjmuje te same pola. Dopilnuj, abyskukażdej pozycji odpowiadało SKU, którego używasz we wszystkich innych miejscach, aby Zonos mógł je ze sobą powiązać.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtinWysyłaj
gtinwyłącznie jako cyfry, bez myślników i spacji. Wartości UPC, EAN, JAN i 13-cyfrowe numery ISBN trafiają do tego jednego pola. Jeśli masz 10-cyfrowy numer ISBN, wyślij zamiast niego wersję 13-cyfrową.Jeśli produkt nie ma kodu kreskowego, pomiń
gtinzamiast wysyłać pusty ciąg, ponownie używać SKU lub wpisywać tekst zastępczy, taki jakN/A.Jeśli samodzielnie wywołujesz Landed Cost API, możesz również uwzględnić te identyfikatory w żądaniu landed cost. Większość kont zweryfikowanych tego nie robi, ponieważ to operator pocztowy przesyła do Zonos dane przesyłki.
Informacje o wymogach wynikających z przepisów znajdziesz w przewodniku po unijnych identyfikatorach produktów.
Zapewnienie dopasowania pozycji
Zonos łączy każdą linię przesyłki z pozycją katalogu na podstawie Twoich identyfikatorów, w następującej kolejności: identyfikator produktu, następnie SKU, a na końcu nazwa. Dbaj o to, aby używane identyfikatory były dokładne i spójne między katalogiem a danymi przesyłanymi przewoźnikowi.
W przypadku przesyłek pocztowych obowiązuje dodatkowe ograniczenie. Zonos otrzymuje od przewoźników pocztowych ograniczony zestaw pól, a na wielu trasach opis celny jest jedynym polem zawierającym jakiekolwiek informacje specyficzne dla produktu. Opis identyczny w całym katalogu sam w sobie niczego nie identyfikuje.
Sposób formatowania identyfikatora w danych przesyłki wysyłanych przewoźnikowi zależy od operatora pocztowego, ponieważ każdy z nich dopasowuje przesyłki do Twojego katalogu inaczej. Przejdź do wszystkich operatorów pocztowych i wybierz swojego operatora. Na jego stronie znajdziesz informacje o tym, jak działa dopasowywanie w przypadku tego operatora i co dokładnie należy wysyłać.
Ustawienie w pozycji wartości
customsDescriptionna ten sam ciąg, który wysyłasz przewoźnikowi, nie jest wymagane, ale pozwala bezpośrednio porównać obie strony, gdy linia nie zostanie dopasowana i trzeba ustalić przyczynę.Dopasowanie najczęściej się nie udaje, gdy:
Aktualizowanie pozycji katalogu
catalogItemUpdateprzyjmuje ten sam typ danych wejściowych co tworzenie. Wysyłaj tylko te pola, które chcesz zmienić.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Odczytywanie pozycji
Zapytanie
catalogItemprzyjmujeid,productIdlubsku. Użyj go, aby sprawdzić, jakie dane o produkcie przechowuje Zonos.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Usuwanie pozycji katalogu
catalogItemDeleteprzyjmuje identyfikatory pozycji katalogu Zonos, a nie Twoje SKU ani identyfikatory produktów. Najpierw ustal identyfikator za pomocą zapytaniacatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Powiązane
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Czy ta strona była pomocna?