Wysyłka zbiorcza (konsolidacja)

W tym dokumencie opisujemy trzyetapowy proces tworzenia zbiorczej wysyłki z opóźnioną zapłatą Japan Post za pośrednictwem API Zonos GraphQL: otworzenie konsolidacji, dołączenie n przesyłek, a następnie zamknięcie, aby otrzymać arkusz wysyłkowy Japan Post (dokument manifestu).

Kiedy używać tego przepływu 

Program opóźnionej zapłaty Japan Post (後納) pozwala handlowcowi rozliczyć swoją dzienną opłatę wysyłkową w jednej transakcji na koniec dnia, zamiast płacić za każdą paczkę oddzielnie. Handlowiec przyniósł wszystkie paczki z tego dnia na pocztę wraz z jednym arkuszem wysyłkowym (差出票) obejmującym do 250 przesyłek. Opłaty pocztowe są rozliczane na wstępnie zarejestrowany numer Later Pay handlowca.

Jeśli wysyłasz poszczególne etykiety Japan Post i płacisz za paczkę przy oknie, nie musisz używać tego przepływu — bezpośrednio wywołaj przepływ dla pojedynczej przesyłki bez konsolidacji.

Przegląd 

1. shipmentConsolidationCreate            → otwarcie partii (zwraca ID konsolidacji)
2. Dołączenie przesyłek × n               → utworzenie każdej przesyłki + etykiety, dołączonej do partii
3. shipmentConsolidationUpdate(CLOSED)    → zamknięcie partii (zwraca arkusz wysyłkowy)

Istnieją dwa sposoby dołączenia przesyłek do partii — wybierz ten, który pasuje do Twojej integracji (lub mieszaj):

• Dołączenie w momencie tworzenia etykiety — przekaż ID konsolidacji z kroku 1 do każdego wywołania shipmentCreateWorkflow za pośrednictwem pola shipmentConsolidationId.
• Dołączenie istniejących przesyłek według ID — przekaż shipmentIds na shipmentConsolidationCreate (w celu zainicjowania partii) lub na shipmentConsolidationUpdate (w celu dodania do otwartej partii). Każda przesyłka musi już mieć etykietę Japan Post.

W każdym przypadku każda etykieta jest tworzona z wbudowanym numerem Later Pay, dzięki czemu Japan Post zaakceptuje ją w arkuszu wysyłkowym, gdy krok 3 zamknie partię.

Dlaczego oddzielne wywołania zamiast jednej mutacji? Kroki 2.1, 2.2, ..., 2.n odbywają się w ciągu dnia handlowca — etykiety są drukowane, a paczki są zamykane w miarę napływu zamówień. Partia nie może być pojedynczą podróżą w dół, tak jak przepływ dla pojedynczej przesyłki: istnieje wielogodzinna przerwa między otwarciem konsolidacji a jej zamknięciem.

Wymagania wstępne 

Zanim ten przepływ zadziała dla danego Zweryfikowanego Konta:

• Twoje konto musi mieć numer opóźnionej zapłaty Japan Post Later Pay Number (後納お客様番号) zapisany — wartość w formacie ze łącznikami, np. 1111111111-222222-3333333333-444444. Przekaż go na shipmentConsolidationCreate za pośrednictwem accountNumber (Krok 1).
• Twój klucz API musi mieć SHIPMENT_WRITE oraz standardowe uprawnienia wymagane przez przepływ dla każdej przesyłki.

Punkt końcowy i uwierzytelnianie 

Wszystkie trzy kroki poniżej to operacje GraphQL wysyłane do tego samego punktu końcowego. To, 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 

Przykład do skopiowania i dostosowania otwierania konsolidacji — mutacja, jej zmienne i odpowiedź. To jest wywołanie specyficzne dla partii, które rozpoczyna przepływ; dołączenie przesyłek (Krok 2) ponownie wykorzystuje przykład dla pojedynczej przesyłki, a zamknięcie partii (Krok 3) zwraca dokument manifestu. Każde pole jest opisane w krokach poniżej.

Krok 1: shipmentConsolidationCreate 

Otwiera konsolidację. Kod przewoźnika blokuje partię na Japan Post; wszystkie przesyłki członkowskie muszą używać poziomów usług Japan Post. Jeśli masz już oznaczone przesyłki, zainicjuj partię ich identyfikatorami za pośrednictwem shipmentIds — w przeciwnym razie utwórz ją pustą i dołącz przesyłki w kroku 2.

Mutacja:

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

Odpowiedź:

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

Zapamiętaj id (np. shco_01HJK...) — będzie potrzebny na wszystko poniżej. status to OPEN aż do kroku 3.

Krok 2: Dołączenie przesyłek 

Dla każdej paczki, którą musisz wysłać dzisiaj, uruchom pełny łańcuch przepływu dla pojedynczej przesyłki, aby utworzyć przesyłkę i jej etykietę. Następnie dołącz przesyłkę do partii, korzystając z jednej z poniższych metod.

Opcja A: Dołączenie w momencie tworzenia etykiety

Przekaż ID konsolidacji na finalnym kroku shipmentCreateWorkflow łańcucha. Wszystkie poprzednie mutacje w łańcuchu są identyczne z przepływem dla pojedynczej przesyłki.

Odpowiednie pola na shipmentCreateWorkflow:

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

Opcja B: Dołączenie istniejących przesyłek według ID

Jeśli Twoje przesyłki są już utworzone i oznaczone, dodaj je do otwartej partii za pośrednictwem shipmentIds na shipmentConsolidationUpdate:

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

Pomiń status w wejściu, gdy nadal dodajesz przesyłki — partia pozostanie OPEN. Każda przesyłka musi używać poziom usług Japan Post i mieć etykietę (numer śledzenia) zanim partia zostanie zamknięta w Kroku 3.

Co oznacza dołączenie dla etykiety

Niezależnie od wybranej opcji, gdy przesyłka Japan Post jest częścią konsolidacji:

• Przesyłka ma numer śledzenia, jak zwykle.
• Plik PDF etykiety wysyłkowej nie zawiera kopii dla klienta/poczty. Te kopie są odłożone do Kroku 3, gdzie są łączone w dokument arkusza wysyłkowego dla całej partii.
• Przesyłka jest powiązana z konsolidacją; możesz ponownie wyszukać ją za pośrednictwem shipmentConsolidation(id: ...), aby zobaczyć jej członków.

Powtórz ten krok dla każdej paczki w dziennej partii. Do 250 przesyłek na konsolidację; próba zamknięcia większej partii nie powiedzie się z wyraźnym komunikatem błędu walidacji, zanim zostanie wykonane jakiekolwiek wywołanie Japan Post.

Możesz również zweryfikować zawartość partii przed zamknięciem:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

Każda przesyłka powinna tutaj pokazać numer śledzenia. Jeśli tego nie robi, jej etykieta nigdy nie została utworzona — rozwiąż to zanim zamkniesz. status to OPEN aż do zamknięcia konsolidacji w Kroku 3.

Krok 3: shipmentConsolidationUpdate(status: CLOSED) 

Zamyka partię. To jest wywołanie, które prosi Japan Post o wygenerowanie arkusza wysyłkowego z opóźnioną zapłatą obejmującego każdy numer śledzenia członka i dołącza wynikowy plik PDF do konsolidacji.

Operacja GraphQL nosi nazwę CloseConsolidation, aby opisać jej cel — zamknięcie partii. Uruchamia mutację shipmentConsolidationUpdate z status: CLOSED.

Mutacja:

mutation CloseConsolidation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

Na żądaniu CLOSED:

1. Konsolidacja jest weryfikowana: ≤250 przesyłek, i każdy członek musi mieć numer śledzenia. Jeśli przesyłka nie ma numeru śledzenia (jej etykieta nigdy nie została utworzona), wywołanie jest odrzucane.
2. Japan Post jest proszony o wygenerowanie arkusza wysyłkowego z opóźnioną zapłatą obejmującego każdy numer śledzenia członka.
3. Status krótko przechodzi do MANIFEST_CREATED, podczas gdy pobranie arkusza PDF jest w toku, a następnie do CLOSED, gdy dokument został dołączony.
4. PDF arkusza wysyłkowego (jeden plik zawierający arkusz plus kopie dla każdego członka) jest dołączony do konsolidacji jako CustomsDocument z documentType: MANIFEST_DOCUMENT.

Odpowiedź:

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

Pobieranie dokumentów

Arkusz wysyłkowy jest dołączony bezpośrednio do konsolidacji jako CustomsDocument z documentType: MANIFEST_DOCUMENT — weź fileUrl z odpowiedzi zamknięcia powyżej lub wyszukaj ją w dowolnym momencie później:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

Wydrukuj plik PDF z fileUrl. Zawiera:

• Strona 1: Arkusz wysyłkowy z opóźnioną zapłatą — przekaż to na pocztę.
• Strony 2+: Kopie dla klienta/poczty dla każdej paczki — jedna przyczepiona do każdej paczki, druga przechowywana przez pocztę.

Po wydrukowaniu przynieś paczki + arkusz wysyłkowy + kopie na pocztę w jednym wejściu. Japan Post rozlicza Twój numer Later Pay na koniec okresu rozliczeniowego.

Złożenie razem 

Reprezentatywny dzień handlowca wysyłającego 50 paczek Japan Post wygląda następująco:

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    paczka 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    paczka 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    paczka 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print PDF

Wolisz zbierać na koniec dnia? Utwórz etykiety dnia bez ID konsolidacji, a następnie otwórz konsolidację raz ze wszystkimi wartościami shipmentIds (lub dodaj je w partiach za pośrednictwem shipmentConsolidationUpdate) i zamknij ją w tym samym lub następnym wywołaniu.

Jeśli wysyłasz między wiele jednostek biznesowych / kont rozliczeniowych, uruchom oddzielną konsolidację na konto — przekaż inny accountNumber na każdym shipmentConsolidationCreate i rozsyłaj przesyłki odpowiednio. Wysyłasz więcej niż 250 paczek w dzień? Otwórz drugą konsolidację.

Obsługa błędów 

Błędy walidacji (przechwycone przed każdym wywołaniem Japan Post)

• accountNumber zniekształcony — odrzucony w Kroku 1 (shipmentConsolidationCreate) zanim konsolidacja zostanie nawet zapisana. Komunikat błędu identyfikuje problematyczny segment.
• >250 przesyłek — odrzucone w Kroku 3, przed wywołaniem Japan Post.
• Przesyłka członkowska bez numeru śledzenia — odrzucone w Kroku 3. Oznacza, że wcześniej utworzenie etykiety bezgłośnie nie powiodło się; zbadaj przesyłkę poprzez shipment(id: ...) { trackingDetails }.
• Brak numeru opóźnionej zapłaty ustawionego na konsolidacji — odrzucone w Kroku 3. Przekaż accountNumber na shipmentConsolidationCreate lub zapisz domyślny numer konta na swoim koncie operatora Japan Post.

Błędy API Japan Post

Jeśli Japan Post odrzuci żądanie arkusza wysyłkowego, mutacja zamknięcia zawiera kod błędu operatora i komunikat jako błąd GraphQL. Najczęstsze:

Ponowne próby

Jeśli wywołanie zamknięcia nie powiedzie się po zaakceptowaniu żądania arkusza wysyłkowego przez Japan Post (tj. podczas pobierania pliku PDF), ponowne próbowanie shipmentConsolidationUpdate(status: CLOSED) jest bezpieczne — platforma pominę wywołanie operatora i ponownie spróbuje pobrać i dołączyć dokument.

Jeśli zamknięcie nie powiedzie się przed zaakceptowaniem żądania przez Japan Post (błąd walidacji, E0xx, timeout sieci), żaden stan nie zmienił się — napraw przyczynę główną i ponów próbę.