Utwórz pojedynczą przesyłkę

CreateDeclarationShipment łączy w łańcuch sześć mutacji *Workflow w jedno żądanie GraphQL. Każdy krok opiera się na danych dostarczonych przez poprzednie kroki, a wszystkie są przesyłane razem, dzięki czemu kompletną przesyłkę można utworzyć w jednej rundzie:

partyCreateWorkflow            → opisz strony źródłową i docelową
itemCreateWorkflow             → opisz pozycje towarowe
cartonsCreateWorkflow          → opisz fizyczne opakowanie
shipmentRatingCreateWorkflow   → zarejestruj ofertę stawki przewoźnika
landedCostCalculateWorkflow    → oblicz cła / podatki / opłaty
shipmentCreateWorkflow         → utwórz przesyłkę + etykietę

Mutacje Workflow są zaprojektowane do łańcuchowania: nie musisz przekazywać identyfikatorów z jednego kroku do następnego i nie musisz wysyłać osobnego żądania na każdy krok. Przesyłasz cały dokument i otrzymujesz ostateczny Shipment.

Gdy serviceLevel w ostatnim kroku jest poziomem usług Japan Post (japan_post.*), Zonos wywołuje w Twoim imieniu Japan Post Label API (kod 52), używając numerów Later Pay Twojego konta zweryfikowanego, generuje etykietę i numer śledzenia, tworzy identyfikator deklaracji i łączy je – wszystko wewnątrz tego ostatniego kroku shipmentCreateWorkflow.

Dlaczego jedna mutacja? Każdy krok zależy od poprzedniego (Landed cost wymaga pozycji towarowych i stron; etykieta wymaga wszystkiego). Zebranie ich w jednym dokumencie GraphQL zapewnia spójność danych i pozwala uniknąć pięciu dodatkowych rund.

Punkt końcowy i uwierzytelnianie 

Wszystkie żądania w tym łańcuchu używają tego samego punktu końcowego. Co przesyłasz w nagłówkach, zależy od Twojej konfiguracji – wybierz swoją kartę.

URL:

https://api.zonos.com/graphql

Nagłówki:

credentialToken: {{YOUR_API_TOKEN}}

Przykładowe żądanie 

Pełne żądanie CreateDeclarationShipment, które możesz skopiować i dostosować – mutacja, jej zmienne i odpowiedź – dla pojedynczej paczki Japan Post wysłanej DDP do USA. Każde wejście zostało rozłożone na czynniki w sekcji krok po kroku poniżej.

Krok po kroku 

Kolumna Status w każdej tabeli poniżej używa tych terminów:

• Wymagane – żądanie nie powiedzie się bez tego.
• Wymagane dla etykiety – opcjonalne w schemacie GraphQL, ale potrzebne do utworzenia prawidłowej etykiety Japan Post dla USA.
• Warunkowe – wymagane w zależności od innego pola (zanotowane w tekście).
• Rekomendowane – opcjonalne, ale zapewnia dokładne cła i podatki.
• Opcjonalne – nie jest potrzebne.

1. partyCreateWorkflow

Tworzy strony zaangażowane w przesyłkę – co najmniej ORIGIN (miejsce, z którego wysyłana jest przesyłka) i DESTINATION (kupujący / odbiorca).

Przykładowy payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

Odpowiedź zwraca utworzone identyfikatory Party i uzupełnione pola adresu.

2. itemCreateWorkflow

Tworzy pozycje towarowe, które składają się na przesyłkę. Są to jednostki SKU, które pojawią się na fakturze handlowej i zasilą obliczenie Landed cost.

Kod HS, kraj pochodzenia i kwota to trzy pola, które najbardziej wpływają na wynik cła / podatku w kroku 5.

3. cartonsCreateWorkflow

Tworzy paczki fizyczne – pudełka, worki foliowe lub listy, które będą zawierać towary.

Każdy karton staje się jedną przesyłką na etykiecie przewoźnika w kroku 6. Wiele kartonów → przesyłka wieloczęściowa z jednym numerem śledzenia na karton.

4. shipmentRatingCreateWorkflow

Rejestruje ofertę stawki, którą kupiec pobiera od kupującego za wysyłkę.

To jest stawka, jaką kupujący otrzymał w kasie. Zasila ona obliczenie Landed cost jako podsumę „shipping”, dzięki czemu cła i podatki są liczone względem prawidłowej wartości CIF.

5. landedCostCalculateWorkflow

Uruchamia obliczenie ceł, podatków i opłat dla kraju docelowego. Wykorzystuje towary, strony i koszt wysyłki z poprzednich kroków.

Odpowiedź zawiera amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) – to są liczby, które pokazujesz kupującemu w kasie i które są drukowane na fakturze handlowej.

6. shipmentCreateWorkflow

Krok końcowy – tworzy encję Shipment, generuje etykietę przewoźnika i (opcjonalnie) fakturę handlową / listę pakowania.

W przypadku kont zweryfikowanych Japan Post to również tutaj Zonos wywołuje w Twoim imieniu Japan Post Label API (kod 52), wstrzykuje Twoje numery Later Pay, tworzy identyfikator deklaracji i łączy identyfikator deklaracji z numerem śledzenia zwracanym przez Japan Post.

Pola kluczowe:

W przypadku contentsType dwie najczęstsze wartości dla ruchu na kontach zweryfikowanych to ECOMMERCE_GOODS (sprzedaż konsumentowi, BtoC) i COMMERCIAL_GOODS (sprzedaż między firmami, BtoB). Ustawiają one pkgType, który Zonos przesyła w wywołaniu etykiety Japan Post, więc ten wybór zmienia to, co drukuje się na zgłoszeniu celnym – to nie jest tylko etykieta.

Podpole nonDelivery

Informuje Japan Post, co zrobić z paczką, jeśli nie można jej dostarczyć – odbiorca odmówił jej przyjęcia, została odrzucona na granicy albo nie można jej dostarczyć na podany adres.

option przyjmuje wyłącznie te cztery wartości. Nie istnieje wartość RETURN – użyj RETURN_AFTER_RETENTION lub RETURN_IMMEDIATELY, aby wybrać, kiedy paczka wraca.

API udostępnia oba warianty zwrotu niezależnie od siebie; opcja Zwrot w Dashboard obejmuje oba.

transportMethod przyjmuje AIR lub MOST_ECONOMICAL i określa, jak wraca zwracana paczka. Dotyczy to tylko dwóch opcji RETURN_* – Dashboard wyświetla odpowiadające pole Metoda zwrotu tylko wtedy, gdy wybrano Zwrot.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Selektor Jeśli nie można dostarczyć w oknie dialogowym Utwórz etykietę w Dashboard zapisuje to samo pole, więc etykieta utworzona w Dashboard i etykieta utworzona przez API zachowują się identycznie.

Podpole references

Te pola są drukowane na etykiecie przewoźnika i / lub fakturze handlowej. Użyj ich, aby przekazać numery PO, numery licencji i uwagi w formie wolnego tekstu, które musi zobaczyć odbiorca lub organ celny.

Odpowiedź

Interesujące pola zwracanego Shipment:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number to numer śledzenia Japan Post.

Obiekt label może zwrócić etykietę na dwa sposoby – zażądaj tego, który pasuje do Twojego przepływu pracy (lub obu):

Wybierz tylko pola, których potrzebujesz. Żądanie url utrzymuje odpowiedź w małym rozmiarze; żądanie labelImage zwraca pełną etykietę w treści odpowiedzi, dzięki czemu nie potrzebujesz drugiej rundy, aby ją pobrać. Powyższy przykład żąda pola url.

Poziomy usług Japan Post 

Przekaż jeden z tych kodów jako serviceLevelCode w shipmentRatingCreateWorkflow.

Kody poziomów usług używają kropek, nie podkreśleń. Możesz zobaczyć formę z podkreśleniem (japan_post_air_parcel) w komunikatach o błędach i wewnętrznych odniesieniach, ale nie jest to prawidłowe wejście.

Usługi lotnicze

Usługi powierzchniowe

Wybór między podobnymi usługami

Small packet a International Air Packet. Obie usługi są ograniczone do 2 kg. japan_post.air.packet to śledzona usługa Small packet firmy Japan Post. japan_post.air.small_packet to jej nieśledzony odpowiednik. Jeśli potrzebujesz śledzenia lekkiej paczki, użyj japan_post.air.packet.

Warianty rejestrowane. W przypadku listów i druków śledzenie jest dodawane przez zarejestrowaną (書留) wersję usługi. japan_post.air.printed_matter i japan_post.air.letter nie zawierają go samodzielnie.

Kody przestarzałe

japan_post.air.epacket_light oznaczał International e-Packet Light. Japan Post zmieniło nazwę tej usługi na International Air Packet 1 czerwca 2026 roku i rozszerzyło ją na wszystkie kraje i regiony. Sama usługa nie zmieniła się.

Stary kod wciąż działa, dzięki czemu istniejące integracje nie przestają funkcjonować, ale w nowych rozwiązaniach należy używać japan_post.air.packet.

Kody trybu transportu

japan_post.air, japan_post.surface, japan_post.economy_air i japan_post.custom również działają, ale określają tryb transportu lub rozwiązanie zastępcze, a nie konkretny produkt pocztowy. W przypadku standardowych przesyłek użyj jednego z powyższych kodów usług.

Zweryfikuj wysyłany kod

Nierozpoznany serviceLevelCode nie powoduje błędu. Żądanie zwraca HTTP 200 bez tablicy errors, serviceLevel wraca jako null, a koszt wysyłki wypada z sumy Landed cost – więc odpowiedź wygląda prawidłowo, mimo że kwoty są błędne.

Zawsze sprawdzaj, czy shipmentRatingCreateWorkflow.serviceLevel nie jest null, zanim zaczniesz polegać na sumach.

Aby w każdej chwili pobrać aktualną listę:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

To zapytanie przyjmuje ID przewoźnika. Przekazanie kodu przewoźnika japan_post zwraca pustą listę bez błędu.

Obsługa błędów 

• Błędy walidacji (brakujące wymagane pola, nieprawidłowe kody krajów itp.) wracają w standardowej tablicy GraphQL errors i przerywają resztę łańcucha.
• Błędy Japan Post (niepowodzenie generowania etykiety, nieprawidłowy adres itp.) pojawiają się jako błędy GraphQL w shipmentCreateWorkflow. Jeśli potrzebna jest ponowna próba, skontaktuj się z pomocą techniczną – zalecaną ścieżką jest ponowne przesłanie całej mutacji z poprawionymi danymi wejściowymi.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Ten błąd wskazuje całą zmienną, a nie pole, które faktycznie jest nieprawidłowe. Prawie zawsze oznacza to, że jedna z wartości enum wewnątrz tej zmiennej nie jest członkiem swojego enuma – najczęściej nonDelivery.option, contentsType lub serviceLevel.

To nie jest problem z typowaniem JSON. Cytowanie lub odcytowanie wartości logicznych i liczbowych niczego nie zmieni, ponieważ ładunek nigdy nie dociera tak daleko – enum jest odrzucany wcześniej.

Aby znaleźć błędne pole, sprawdź każde pole typu enum w zmiennej pod kątem jego akceptowanych wartości:

Pełna lista wartości enum dla każdego wejścia znajduje się na jego stronie typu w dokumentacji API.

Uprawnienia 

Każdy krok jest niezależnie zabezpieczony. Twój klucz API musi posiadać zakres zapisu dla każdej encji w łańcuchu (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Standardowa rola handlowca na koncie zweryfikowanym przyznaje wszystkie te uprawnienia.

Następne kroki 

• Dispatch zbiorczy (konsolidacja) – spakuj dzienne paczki w jeden poślizg odroczonej płatności Japan Post.