Utwórz pojedynczą przesyłkę

CreateDeclarationShipment łańcuchuje razem sześć mutacji *Workflow w jedno żądanie GraphQL. Każdy krok opiera się na danych, które dostarczyły poprzednie kroki, i wszystkie są przesyłane razem, aby można było utworzyć pełną przesyłkę w jednej rundzie:

partyCreateWorkflow            → opisz źródłowe i docelowe strony
itemCreateWorkflow             → opisz pozycje linii
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 przesyłać identyfikatorów z jednego kroku do następnego, a nie musisz wysyłać osobnego żądania na krok. Prześlij cały dokument, otrzymaj ostateczny Shipment.

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

Dlaczego jedna mutacja? Każdy krok zależy od poprzedniego (koszt przesłania wymaga elementów + stron; etykieta wymaga wszystkiego). Pakowanie ich w jeden dokument 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 rozbite 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 ważnej etykiety Japan Post 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 (skąd wysyłka wysyła) i DESTINATION (kupujący / adresat).

Przykładowe ładowanie:

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

Odpowiedź zwraca utworzone identyfikatory Party i rozwiązane pola adresu.

2. itemCreateWorkflow

Tworzy pozycje linii, które tworzą przesyłkę. Są to jednostki SKU, które pojawią się na fakturze handlowej i będą napędzać obliczenie kosztu przesłania.

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ć artykuły.

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, którą kupujący otrzymał w kasie. Wpływa na obliczenie kosztu przesłania jako „wysyłka" podsumy, aby cła i podatki były obliczane względem prawidłowej wartości CIF.

5. landedCostCalculateWorkflow

Uruchamia obliczenie ceł, podatków i opłat dla kraju docelowego. Używa artykułów, stron i kosztu 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 terminalowy – tworzy encję Shipment, generuje etykietę przewoźnika i (opcjonalnie) fakturę handlową / podsumowanie paczki.

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

Pola kluczowe:

references sub-input

Te pola są drukowane na etykiecie przewoźnika i / lub fakturze handlowej. Użyj ich do wyświetlenia numerów PO, numerów licencji i uwag w dowolnym tekście, które adresat lub władze celne muszą widzieć.

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 – poproś, która pasuje do Twojego przepływu pracy (lub obie):

Wybierz tylko pola, których potrzebujesz. Żądanie url utrzymuje odpowiedź małą; żądanie labelImage zwraca pełną etykietę w tekście, aby nie potrzebować drugiej rundy do pobrania. Przykład powyżej żądań url.

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 przerwają resztę łańcucha.
• Błędy Japan Post (nieudana generacja etykiety, nieprawidłowy adres, itp.) pojawiają się jako błędy GraphQL na shipmentCreateWorkflow. Jeśli wymagane jest ponowienie, skontaktuj się z pomocą – zalecaną ścieżką jest przesłanie pełnej mutacji z poprawnym wejściem.

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 kupca na koncie zweryfikowanym przyznaje wszystkie te.

Następne kroki 

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