Tek bir sevkiyat oluşturun

CreateDeclarationShipment, altı *Workflow mutasyonunu tek bir GraphQL isteğinde birleştirir. Her adım, önceki adımların sağladığı verilere dayanır ve hepsi birlikte gönderilir, böylece tam bir sevkiyat tek bir gidiş-dönüşte oluşturulabilir:

partyCreateWorkflow            → çıkış + varış taraflarını tanımla
itemCreateWorkflow             → satır öğelerini tanımla
cartonsCreateWorkflow          → fiziksel ambalajlamayı tanımla
shipmentRatingCreateWorkflow   → taşıyıcı oran teklifini kaydet
landedCostCalculateWorkflow    → gümrük vergilerini, vergileri ve ücretleri hesapla
shipmentCreateWorkflow         → sevkiyat + etiket oluştur

Workflow mutasyonları zincirleme yapılmak üzere tasarlanmıştır: bir adımdan diğerine ID'leri iletmeniz gerekmez ve adım başına ayrı bir istek göndermeniz gerekmez. Tüm belgeyi gönderin, son Shipment'i geri alın.

Son adımdaki serviceLevel bir Japan Post hizmet seviyesi olduğunda (japan_post.*), Zonos sizin adınıza Japan Post Label API'sini (kod 52) çağırır ve Doğrulanmış Hesabınızın Later Pay Numaralarını kullanarak etiketi ve takip numarasını oluşturur, Declaration ID'yi oluşturur ve bunları bağlar — tümü bu son shipmentCreateWorkflow adımının içinde.

Neden tek bir mutasyon? Her adım bir öncekine bağlıdır (landed cost hesaplaması öğeler + tarafları gerektirir; etiket her şeyi gerektirir). Bunları tek bir GraphQL belgesinde birleştirmek, veri tutarlılığını korur ve beş ekstra gidiş-dönüşü önler.

Endpoint ve kimlik doğrulama 

Bu zincirdeki isteklerin tümü aynı endpoint'i kullanır. Başlıklara ne koyacağınız kurulumunuza bağlıdır — sekmenizi seçin.

URL:

https://api.zonos.com/graphql

Başlıklar:

credentialToken: {{YOUR_API_TOKEN}}

Örnek istek 

Kopyalayıp uyarlayabileceğiniz tam bir CreateDeclarationShipment isteği — mutasyon, değişkenleri ve yanıtı — ABD'ye DDP ile gönderilen tek bir Japan Post paketi için. Her girdi, aşağıdaki adım adım bölümünde ayrıntılı olarak açıklanmıştır.

Adım adım 

Aşağıdaki tablolarda Durum sütunu bu terimleri kullanır:

• Gerekli — bu alan olmadan istek başarısız olur.
• Etiket için gerekli — GraphQL şemasında isteğe bağlı, ancak geçerli bir Japan Post ABD etiketi üretmek için gerekli.
• Koşullu — başka bir alana bağlı olarak gerekli (satır içinde belirtilmiştir).
• Önerilen — isteğe bağlı, ancak doğru gümrük vergisi ve vergi hesaplamasını sağlar.
• İsteğe bağlı — gerekli değildir.

1. partyCreateWorkflow

Sevkiyatla ilgili tarafları oluşturur — en azından bir ORIGIN (sevkiyatın nereden gönderileceği) ve bir DESTINATION (alıcı / teslim alan).

Örnek yük:

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

Yanıt, oluşturulan Party ID'lerini ve çözümlenen adres alanlarını döndürür.

2. itemCreateWorkflow

Sevkiyatı oluşturan satır öğelerini oluşturur. Bunlar, ticari faturada görünecek ve landed cost hesaplamasını yönlendirecek SKU'lardır.

HS kodu, menşe ülkesi ve tutar, 5. adımdaki gümrük vergisi/vergi sonucunu en çok etkileyen üç alandır.

3. cartonsCreateWorkflow

Fiziksel paketleri oluşturur — öğeleri içine alacak kutular, polybag'lar veya mektuplar.

Her karton, 6. adımdaki taşıyıcı etikette bir parsel haline gelir. Birden fazla karton → her karton için ayrı bir takip numarasıyla çok parçalı bir sevkiyat.

4. shipmentRatingCreateWorkflow

Oran teklifini kaydeder — satıcının alıcıya kargo için talep ettiği tutar.

Bu, alıcının ödeme sırasında teklif edilen kargo ücretidir. Gümrük vergileri ve vergilerin doğru CIF değeri üzerinden hesaplanması için bu tutar, gümrük vergisi/vergi hesaplamasına "kargo" alt toplamı olarak dahil edilir.

5. landedCostCalculateWorkflow

Hedef ülke için gümrük vergisi, vergi ve ücret hesaplamasını çalıştırır. Önceki adımlardaki öğeleri, tarafları ve kargo maliyetini kullanır.

Yanıt, amountSubtotals alanını içerir (duties, taxes, fees, shipping, landedCostTotal) — bunlar, ödeme sırasında alıcıya gösterdiğiniz ve ticari faturada basılan sayılardır.

6. shipmentCreateWorkflow

Son adım — Shipment varlığını oluşturur, taşıyıcı etiketi ve isteğe bağlı olarak ticari fatura / paketleme fişini üretir.

Japan Post Doğrulanmış Hesapları için bu adım, aynı zamanda Zonos'un sizin adınıza Japan Post Label API'sini (kod 52) çağırdığı, Later Pay Numaralarınızı enjekte ettiği, Declaration ID'yi oluşturduğu ve bu Declaration ID'yi Japan Post'un döndürdüğü takip numarasına bağladığı adımdır.

Önemli alanlar:

contentsType için, Doğrulanmış Hesap trafiğinde en yaygın kullanılan iki değer ECOMMERCE_GOODS (bir tüketiciye satılan, BtoC) ve COMMERCIAL_GOODS (işletmeler arası satılan, BtoB) değerleridir. Bu değerler, Zonos'un Japan Post etiket çağrısında gönderdiği pkgType alanını belirler; dolayısıyla seçiminiz gümrük beyannamesinde neyin basılacağını değiştirir — bu sadece bir etiket meselesi değildir.

nonDelivery alt girdisi

Paket teslim edilemezse — alıcı tarafından kabul edilmezse, sınırda reddedilirse veya belirtilen adrese teslim edilemezse — Japan Post'un ne yapacağını belirtir.

option tam olarak şu dört değeri kabul eder. RETURN değeri yoktur — paketin ne zaman geri döneceğini seçmek için RETURN_AFTER_RETENTION veya RETURN_IMMEDIATELY kullanın.

API, her iki return türünü ayrı ayrı sunar; Dashboard'daki Return seçeneği ikisini de kapsar.

transportMethod, AIR veya MOST_ECONOMICAL değerlerini kabul eder ve geri döndürülen bir paketin nasıl taşınacağını belirler. Yalnızca iki RETURN_* seçeneği için geçerlidir — Dashboard, ilgili Return method alanını yalnızca Return seçildiğinde gösterir.

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

Dashboard'daki Create label iletişim kutusundaki If undeliverable seçici de aynı alanı yazar, böylece Dashboard'da oluşturulan bir etiket ile API üzerinden oluşturulan bir etiket aynı şekilde davranır.

references alt girdisi

Bu alanlar taşıyıcı etiketine ve/veya ticari faturaya basılır. Alıcının veya gümrük otoritesinin görmesi gereken PO numaralarını, lisans numaralarını ve serbest metin açıklamalarını yüzeye çıkarmak için bunları kullanın.

Yanıt

Döndürülen Shipment'daki ilginç alanlar:

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

trackingDetails.number Japan Post takip numarasıdır.

label nesnesi etiketi iki şekilde döndürebilir — iş akışınıza uyan şeyi isteyin (veya her ikisini):

Yalnızca gerekli alanları seçin. url istemek yanıtı küçük tutar; labelImage istemek tam etiketi satır içinde döndürür, böylece almak için ikinci bir gidiş-dönüş gerekmez. Yukarıdaki örnek url alanını talep etmektedir.

Japan Post hizmet seviyeleri 

Bu kodlardan birini shipmentRatingCreateWorkflow içinde serviceLevelCode olarak iletin.

Hizmet seviyesi kodları alt çizgi değil nokta kullanır. Hata mesajlarında ve iç referanslarda alt çizgili biçimi (japan_post_air_parcel) görebilirsiniz, ancak bu geçerli bir girdi değildir.

Hava hizmetleri

Yüzey hizmetleri

Benzer hizmetler arasında seçim yapma

Küçük paket ile International Air Packet karşılaştırması. Her ikisi de 2 kg ile sınırlıdır. japan_post.air.packet, Japan Post'un takip edilebilir küçük paket hizmetidir. japan_post.air.small_packet ise takip edilemeyen eşdeğeridir. Hafif bir pakette takip özelliğine ihtiyacınız varsa japan_post.air.packet kullanın.

Kayıtlı varyantlar. Mektuplar ve basılı materyaller için takip, hizmetin kayıtlı (書留) sürümüyle eklenir. japan_post.air.printed_matter ve japan_post.air.letter, bunu kendi başlarına içermez.

Kullanımdan kaldırılan kodlar

japan_post.air.epacket_light, International e-Packet Light hizmetiydi. Japan Post, hizmetin adını 1 Haziran 2026'da International Air Packet olarak değiştirdi ve tüm ülke ve bölgeleri kapsayacak şekilde genişletti. Hizmetin kendisi değişmedi.

Eski kod hâlâ çözümlenir, böylece mevcut entegrasyonlar çalışmaya devam eder, ancak yeni işler için japan_post.air.packet kullanın.

Taşıma modu kodları

japan_post.air, japan_post.surface, japan_post.economy_air ve japan_post.custom da çözümlenir, ancak bunlar belirli bir posta ürünü değil, bir taşıma modunu veya bir yedek seçeneği tanımlar. Normal sevkiyatlar için yukarıdaki hizmet kodlarından birini kullanın.

Gönderdiğiniz kodu doğrulayın

Tanınmayan bir serviceLevelCode hata vermez. İstek, errors dizisi olmadan HTTP 200 döndürür, serviceLevel null olarak gelir ve kargo tutarı landed cost toplamından düşer — böylece yanıt doğru görünür ama tutarlar yanlıştır.

Toplamlara güvenmeden önce her zaman shipmentRatingCreateWorkflow.serviceLevel'in null olmadığını doğrulayın.

Güncel listeyi istediğiniz zaman almak için:

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

Bu sorgu, taşıyıcı ID'sini alır. Taşıyıcı kodu japan_post'u geçirmek, hatasız boş bir liste döndürür.

Hata işleme 

• Doğrulama hataları (eksik gerekli alanlar, geçersiz ülke kodları, vb.) standart GraphQL errors dizisinde geri gelir ve zincirin geri kalanını durdurur.
• Japan Post hataları (etiket üretim hatası, geçersiz adres, vb.) shipmentCreateWorkflow üzerinde GraphQL hataları olarak yüzeye çıkar. Yeniden deneme gerekiyorsa, desteğe başvurun — önerilen yol, tam mutasyonu düzeltilmiş girdilerle yeniden göndermektir.

VALIDATION_INVALID_TYPE_VARIABLE

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

Bu hata değişkenin tamamını adlandırır, gerçekte hatalı olan alanı değil. Neredeyse her zaman, bu değişkenin içindeki bir enum değerinin kendi enum'unun bir üyesi olmadığı anlamına gelir — en sık nonDelivery.option, contentsType veya serviceLevel alanlarında.

Bu bir JSON tip sorunu değildir. Booleanlarınızı veya sayılarınızı tırnak içine alıp almamanız bir şey değiştirmez, çünkü payload hiçbir zaman o noktaya ulaşmaz — enum önce reddedilir.

Hatalı alanı bulmak için, değişken içindeki her enum değerli alanı kabul edilen değerlerine göre kontrol edin:

Herhangi bir girdi için enum üyelerinin tam listesi, API referansındaki tür sayfasında yer alır.

İzinler 

Her adımın güvenliği bağımsız olarak sağlanır. API anahtarınız, zincirdeki her varlık için yazma kapsamını (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE) tutmalıdır. Doğrulanmış Hesaptaki standart satıcı rolü tümünü verir.

Sonraki adımlar 

• Batch dispatch (birleştirme) — günün paketlerini bir Japan Post ertelenmiş ödeme gönderim kaydına paketleyin.