Strona głównaRozwiązania pocztowe dla wysyłek wychodzących Narzędzia dla nadawców Konta Verified 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

catalogItemCreate przyjmuje listę, dzięki czemu możesz wysłać wiele produktów w jednym żądaniu.

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}

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

Pole↕	Wymagane↕	Opis↕
`sku`	Tak*	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.
`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.

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.

Dołączaj identyfikator produktu lub SKU do opisu celnego przesyłanego przewoźnikowi.

Men's bifold wallet, cowhide leather - 123456

Dołączony identyfikator musi dokładnie odpowiadać wartości productId lub sku w odpowiedniej pozycji katalogu.

Pola opisu są krótkie. Na przykład zgłoszenia do Canada Post dopuszczają około 49 znaków, więc skróć część opisową, jeśli Twoje identyfikatory są długie. Identyfikator jest ważniejszy niż sam opis.

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 opisie brakuje identyfikatora.
Identyfikator nie odpowiada żadnej wartości productId ani sku 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ć.

1mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {

2 catalogItemUpdate(input: $input) {

3 id

4 itemKey

5 hsCode

6 customsDescription

7 }

8}

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.

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}

Usuwanie pozycji katalogu

catalogItemDelete przyjmuje identyfikatory pozycji katalogu Zonos, a nie Twoje SKU ani identyfikatory produktów. Najpierw ustal identyfikator za pomocą zapytania catalogItem.

1mutation CatalogItemDelete($input: [ID!]!) {

2 catalogItemDelete(input: $input)

3}

Powiązane

Integracje z kanałami sprzedaży — Synchronizuj katalog automatycznie z obsługiwanego kanału sprzedaży.
Import CSV — Przesyłaj pozycje katalogu za pomocą arkusza kalkulacyjnego zamiast pisania kodu.
Kontrole PGA — Sprawdzaj pozycje katalogu pod kątem wymogów amerykańskich agencji (PGA).
Jak działa Catalog — Co Zonos robi z danymi Twoich produktów.

GraphQL API ReferenceTypes, inputs, and operations used in this guide

INPUTS

CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate

Zarezerwuj demonstrację

Catalog API

Jak to działa

Tworzenie pozycji katalogu

Ponowne wysłanie tego samego produktu

Pola

Zapewnienie dopasowania pozycji

Aktualizowanie pozycji katalogu

Odczytywanie pozycji

Usuwanie pozycji katalogu

Powiązane

Czy ta strona była pomocna?