Batch dispatch (konsolidasyon)

Bu belge, Zonos GraphQL API aracılığıyla Japan Post ertelenmiş ödeme dispatch batch oluşturmak için üç aşamalı akışı açıklamaktadır: bir konsolidasyonu açın, buna n sevkiyatı ekleyin, ardından Japan Post sevkiyat fişini (manifest belge) almak için kapatın.

Bu akışı ne zaman kullanmalı 

Japan Post ertelenmiş ödeme programı (後納), bir satıcının günlük sevkiyat faturasını tezgahta parça parça ödeme yerine günün sonunda tek bir işlemde ödemesine olanak tanır. Satıcı, o günün tüm paketlerini posta ofisine getirerek, 250'ye kadar sevkiyatı kapsayan tek bir sevkiyat fişi (差出票) ile birlikte getirir. Navlun, satıcının önceden kayıtlı Later Pay Numarasına faturalanır.

Bireysel Japan Post etiketleri gönderiyor ve tezgahta parça parça ödüyorsanız, bu akışa ihtiyacınız yoktur — konsolidasyon olmadan tek sevkiyat zincirini doğrudan çağırın.

Genel Bakış 

1. shipmentConsolidationCreate            → batch'i açın (konsolidasyon ID'sini döndürür)
2. Sevkiyatları ekleyin × n                   → her sevkiyat + etiketi oluşturun, batch'e eklenmiş olarak
3. shipmentConsolidationUpdate(CLOSED)    → batch'i kapatın (sevkiyat fişini döndürür)

Batch'e sevkiyatları eklemek için iki yol vardır — entegrasyonunuza uygun olanı seçin (veya bunları karıştırın):

• Etiketi oluştururken ekle — adım 1'deki konsolidasyon ID'sini her shipmentCreateWorkflow çağrısına shipmentConsolidationId alanı aracılığıyla iletin.
• Mevcut sevkiyatları ID'ye göre ekle — shipmentConsolidationCreate (batch'i tohumlamak için) veya shipmentConsolidationUpdate (açık batch'e eklemek için) üzerine shipmentIds iletin. Her sevkiyatın zaten Japan Post etiketi olması gerekir.

Her iki şekilde de, her etiket Later Pay Numaranız gömülü olarak oluşturulur, böylece Japan Post adım 3 batch'i kapattığında bunu sevkiyat fişine kabul eder.

Neden bir mutasyon yerine ayrı çağrılar? Adımlar 2.1, 2.2, ..., 2.n satıcının günü boyunca gerçekleşir — etiketler basılır ve paketler siparişler geldikçe mühürlenir. Batch, tek sevkiyat zinciri gibi tek bir gidiş dönüş olamaz: konsolidasyonu açmak ile kapatmak arasında çok saatlik bir boşluk vardır.

Ön Koşullar 

Bu akış belirli bir Verified Account için çalışmadan önce:

• Hesabınız Japan Post ertelenmiş ödeme Later Pay Numarasına sahip olmalıdır (後納お客様番号) — 1111111111-222222-3333333333-444444 gibi tire biçimlendirilmiş bir değer. Bunu adım 1'de shipmentConsolidationCreate üzerine accountNumber aracılığıyla iletin.
• API anahtarınız SHIPMENT_WRITE artı sevkiyat başına iş akışının ihtiyaç duyduğu standart kapsamlara sahip olmalıdır.

Uç nokta ve kimlik doğrulama 

Aşağıdaki üç adımın tümü aynı uç noktaya gönderilen GraphQL işlemleridir. Başlıklara ne koyduğunuz, kurulumunuza bağlıdır — sekmelerinizi seçin.

URL:

https://api.zonos.com/graphql

Başlıklar:

credentialToken: {{YOUR_API_TOKEN}}

Örnek istek 

Konsolidasyon açmanın bir kopyala ve uyarla örneği — mutasyon, değişkenleri ve yanıtı. Bu, akışı başlatan batch'e özgü çağrıdır; sevkiyatları ekleme (Adım 2) tek sevkiyat örneğini yeniden kullanır ve batch'i kapatma (Adım 3) manifest belgesini döndürür. Her alan aşağıdaki adımlarda detaylandırılmıştır.

Adım 1: shipmentConsolidationCreate 

Konsolidasyonu açar. Taşıyıcı kodu batch'i Japan Post'a kilitler; tüm üye sevkiyatlar Japan Post service seviyeleri kullanmalıdır. Zaten etiketli sevkiyatlarınız varsa, batch'i ID'leri aracılığıyla shipmentIds ile başlatın — aksi takdirde boş oluşturun ve adım 2'de sevkiyatları ekleyin.

Mutasyon:

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
    }
  }
}

Yanıt:

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

ID'yi (örn. shco_01HJK...) tutun — aşağıda her şey için kullanacaksınız. status, adım 3'e kadar OPEN'dır.

Adım 2: Sevkiyatları ekle 

Bugün göndermek için gereken her paket için tam zincirli tek sevkiyat iş akışını çalıştırarak sevkiyatı ve etiketini oluşturun. Ardından aşağıdaki yöntemlerden birini kullanarak sevkiyatı batch'e ekleyin.

Seçenek A: Etiketi oluştururken ekle

Zincirin son shipmentCreateWorkflow adımında konsolidasyon ID'sini iletin. Zincirdeki tüm önceki mutasyonlar tek sevkiyat iş akışı ile aynıdır.

shipmentCreateWorkflow üzerindeki ilgili alanlar:

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

Seçenek B: Mevcut sevkiyatları ID'ye göre ekle

Sevkiyatlarınız zaten oluşturulmuş ve etiketlenmişse, bunları shipmentConsolidationUpdate üzerinde shipmentIds ile açık batch'e ekleyin:

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

Hala sevkiyat eklerken girdiden status bırakın — batch OPEN kalır. Her sevkiyat adım 3'te batch kapatılmadan önce Japan Post service seviyesini kullanmalı ve etiketine (tracking numarasına) sahip olmalıdır.

Eklemenin etikete anlamı

Hangi seçeneği kullanırsanız kullanın, bir Japan Post sevkiyatı konsolidasyonun parçası olduğunda:

• Sevkiyatın her zamanki gibi bir tracking numarası vardır.
• Sevkiyat etiketi PDF müşteri/posta ofisi makbuz kopyalarını içermez. Bu makbuzlar Adım 3'e kaydırılır; burada tüm batch için sevkiyat fişi belgesinde birleştirilir.
• Sevkiyat konsolidasyona ilişkilidir; üyeleri görmek için shipmentConsolidation(id: ...) aracılığıyla yeniden sorgulayabilirsiniz.

Günün batch'indeki her paket için bu adımı tekrarlayın. Konsolidasyon başına maksimum 250 sevkiyat; daha büyük bir batch'i kapatmaya çalışmak, herhangi bir Japan Post çağrısından önce açık bir doğrulama hatasıyla başarısız olur.

Kapatmadan önce batch'in içeriğini de doğrulayabilirsiniz:

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

Her sevkiyat burada bir tracking numarası göstermelidir. Biri yoksa, etiketi asla oluşturulmamış demektir — kapatmadan önce bunu çözün. status, Adım 3'te konsolidasyon kapatılıncaya kadar OPEN'dır.

Adım 3: shipmentConsolidationUpdate(status: CLOSED) 

Batch'i kapatır. Bu, Japan Post'tan her üyenin tracking numarasını kapsayan ertelenmiş ödeme sevkiyat fişini oluşturmasını isteyen ve sonuçta elde edilen PDF'yi konsolidasyona ekleyen çağrıdır.

GraphQL işlemi, niyetini açıklamak için CloseConsolidation olarak adlandırılmıştır: batch'i kapatmak. status: CLOSED ile shipmentConsolidationUpdate mutasyonunu çalıştırır.

Mutasyon:

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

Bir CLOSED isteğinde:

1. Konsolidasyon doğrulanır: ≤250 sevkiyat ve her üyenin bir tracking numarası olması gerekir. Bir sevkiyat tracking numarası eksikse (etiketi asla oluşturulmamışsa), çağrı reddedilir.
2. Japan Post'tan her üyenin tracking numarasını kaplayan ertelenmiş ödeme sevkiyat fişi oluşturması istenir.
3. Durum kısaca, slip PDF alınırken MANIFEST_CREATED'a geçer, ardından belge eklendiğinde CLOSED'a geçer.
4. Sevkiyat fişi PDF'si (slip artı her üyenin müşteri/posta ofisi makbuzlarını içeren bir dosya) konsolidasyona documentType: MANIFEST_DOCUMENT olan bir CustomsDocument olarak eklenir.

Yanıt:

{
  "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"
        }
      ]
    }
  }
}

Belgeleri alma

Sevkiyat fişi doğrudan konsolidasyona documentType: MANIFEST_DOCUMENT olan bir CustomsDocument olarak eklenir — yukarıdaki kapatma yanıtından fileUrl'yi alın veya daha sonra dilediğiniz zaman sorgulayın:

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

fileUrl'deki PDF'yi yazdırın. İçerir:

• Sayfa 1: Ertelenmiş ödeme sevkiyat fişi (後納差出票) — bunu posta ofisine verin. Batch'teki her sevkiyat, hangi service seviyesini kullandığından bağımsız olarak burada listelenir.
• Sayfalar 2+: Müşteri/posta ofisi makbuzları — biri her pakete zımbalanır, diğeri posta ofisinde tutulur. Bu sayfalar yalnızca EMS ve International Parcel sevkiyatları için oluşturulur, çünkü bunlar bir tracking numarasına bağlıdır.

Yazdırdıktan sonra paketler + sevkiyat fişi + makbuzları bir gezide posta ofisine getirin. Japan Post, fatura döneminin sonunda Later Pay Numaranızı faturalar.

Sayfa 1'de olup makbuz sayfası olmayan bir sevkiyat, eksik bir sevkiyat değildir. Small Packet (小形包装物), takip edilen bir Japan Post service'i değildir, bu yüzden sayfa 1'de listelenir ve 2+ sayfasında makbuz almaz. Beş paketlik bir batch, meşru bir şekilde tümünü listeleyen bir sayfa 1 ve yalnızca EMS ve Parcel olanlar için makbuz sayfaları üretebilir; yalnızca Small Packet'lerden oluşan bir batch ise bir sayfa 1 üretir ve başka hiçbir sayfa üretmez. Bu, beklenen Japan Post davranışıdır, başarısız bir etiket veya başarısız bir manifest çağrısı değildir. Service seviyesi başına ayrı bir konsolidasyon açmanıza gerek yoktur. Japan Post ile Ağustos 2026'da doğrulanmıştır.

Bir araya getirme 

50 Japan Post paketi gönderen bir satıcı için temsili bir gün şöyle görünür:

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

Günün sonunda batch'i yapmayı tercih mi ediyorsunuz? Konsolidasyon ID'si olmadan günün etiketlerini oluşturun, ardından konsolidasyonu bir kez tüm shipmentIds değerleri ile açın (veya bunları shipmentConsolidationUpdate aracılığıyla öbekler halinde ekleyin) ve aynı veya müteakip çağrıda kapatın.

Birden fazla iş birimi / fatura hesabında sevkiyat yapıyorsanız, her hesap için ayrı bir konsolidasyon çalıştırın — her shipmentConsolidationCreate üzerine farklı bir accountNumber iletin ve sevkiyatları buna göre yönlendirin. Bir günde 250'den fazla paket gönderiyor musunuz? İkinci bir konsolidasyon açın.

Hata işleme 

Doğrulama hataları (herhangi bir Japan Post çağrısından önce yakalanır)

• accountNumber hatalı biçimlendirilmiş — Adım 1'de (shipmentConsolidationCreate) reddedilir, konsolidasyon bile kaydedilmeden. Hata mesajı suçlu segmenti tanımlar.
• >250 sevkiyat — Adım 3'te, Japan Post çağrısından önce reddedilir.
• Üye sevkiyat tracking numarası eksik — Adım 3'te reddedilir. Daha önceki bir etiket oluşturma sessizce başarısız olmuş anlamına gelir; shipment(id: ...) { trackingDetails } aracılığıyla etkilenen sevkiyatı araştırın.
• Konsolidasyonda ertelenmiş ödeme numarası ayarlanmamış — Adım 3'te reddedilir. shipmentConsolidationCreate üzerine accountNumber iletin veya Japan Post taşıyıcı hesabınızda bir varsayılan hesap numarası kaydedin.

Japan Post API hataları

Japan Post sevkiyat fişi isteğini reddederse, kapatma mutasyonu taşıyıcının hata kodunu ve mesajını GraphQL hatası olarak yüzeyler. En yaygın:

Yeniden deneme

Kapatma çağrısı, Japan Post sevkiyat fişi isteğini kabul ettikten sonra (PDF alınması sırasında) başarısız olursa, shipmentConsolidationUpdate(status: CLOSED) yeniden denemesi güvenlidir — platform taşıyıcı çağrısını atlayacak ve belgeyi getirip eklemeyi yeniden deneyecektir.

Kapatma, Japan Post isteği kabul etmeden önce başarısız olursa (doğrulama hatası, E0xx, ağ zaman aşımı), durum değişmemiştir — kök nedeni düzeltin ve yeniden deneyin.