DOCS
Ana sayfaPosta sevk çözümleri Gönderici Araçları Doğrulanmış Hesaplar Katalog API'si

Katalog API'si

Doğrulanmış Hesap kataloğunuzu doğrudan kendi sisteminizden, programlı olarak oluşturun.

Katalog API'si, Doğrulanmış Hesap kataloğunuzu oluşturmanın üç yolundan biridir ve geliştirici kaynaklarına ve ürün verilerini zaten barındıran bir sisteme (ERP, WMS, PIM veya gönderim platformu) sahip göndericiler için uygun seçenektir. Bu sistem doğruluk kaynağı olarak kalır ve bir kanal entegrasyonundan senkronize etmek ya da bir CSV dosyası yüklemek yerine ürünleri doğrudan Zonos'a yazar. Desteklenen bir kanal üzerinden satış yapıyorsanız veya kod yazmamayı tercih ediyorsanız, bu iki seçenek aynı kataloğu daha az çabayla oluşturur.

API aracılığıyla oluşturulan öğeler, diğer tüm kaynaklardan gelen öğelerle tamamen aynı şekilde işlenir—bir öğe kataloğunuza girdikten sonra oraya nasıl geldiği Zonos için fark etmez. HS kodu sağlamadıysanız her öğe gümrük için sınıflandırılır, ABD Ortak Devlet Kurumu (PGA) gereklilikleri açısından taranır ve içinde yer aldığı gönderilerin gümrük vergilerini ve vergilerini hesaplamak için kullanılır.

Bu sürecin bir kısmı API'nin dışında kalır. PGA taraması bir öğeyi Dikkat gerekiyor olarak işaretlediğinde, bu işaretin arkasındaki uyumluluk anketinin Dashboard'da yanıtlanması ve onaylanması gerekir—bunun için bir API yoktur ve Zonos doldurabildiği her şeyi önceden doldurur; böylece işin büyük kısmı gözden geçirme ve onaylamadan ibaret olur. Bu entegrasyonu kuran kişi genellikle bu işaretleri çözen kişi değildir; bu nedenle kataloğunuz yüklendikten sonra kuruluşunuzdan birinin bunları Dashboard'da ele almasını planlayın. İşaretlenen öğelerin gönderilmesi engellenmez, ancak göndermeden önce bunları çözmek, bir gönderinin ABD sınırında bekletilmesini önler.

Nasıl çalışır 

  1. Gönderdiğiniz her ürün için bir katalog öğesi oluşturun.

  2. Her öğenin, posta taşıyıcınızın ileteceği bir tanımlayıcı içerdiğinden emin olun.

  3. Gönderi verileriniz Zonos'a ulaştığında her satır ilgili katalog öğenizle eşleştirilir ve o öğenin ürün verileri hesaplamaya uygulanır.

Katalog öğeleri oluşturma 

catalogItemCreate bir liste kabul eder; böylece tek bir istekte çok sayıda ürün gönderebilirsiniz.

1mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
2 catalogItemCreate(input: $input) {
3 id
4 itemKey
5 name
6 productId
7 sku
8 hsCode
9 customsDescription
10 countryOfOrigin
11 }
12}

Aynı ürünü iki kez gönderme

SKU'su veya ürün kimliği zaten mevcut olan bir ürün gönderirseniz Zonos ikinci bir ürün eklemek yerine o ürünü günceller. Yeniden denemeler ve tekrarlanan çalıştırmalar güvenlidir.

Bunun öbür yüzü ise aynı SKU'yu veya ürün kimliğini paylaşan iki farklı ürünün tek bir ürün olarak birleştirilmesidir. Toplu yüklemeden önce verilerinizi yinelenen kayıtlar açısından kontrol edin.

Alanlar

Alan↕Zorunlu↕Açıklama↕
skuEvet*Ürün için benzersiz tanımlayıcınız. *Her ürünün bir SKU'ya, bir ürün kimliğine veya her ikisine de ihtiyacı vardır.
productIdEvet*Platformunuzun ürün için kullandığı tanımlayıcı. *Her ürünün bir SKU'ya, bir ürün kimliğine veya her ikisine de ihtiyacı vardır.
nameEvetÜrün adı.
customsDescriptionÖnerilirGümrük beyannamesi için ürünün ne olduğunu sade bir dille belirtir. “Summer Vibes Tee” değil, “Pamuklu tişört” kullanın.
countryOfOriginÖnerilirÜrünün üretildiği yerin 2 harfli ISO kodu. Gümrük vergisini doğru hesaplamak için gereklidir.
measurementsÖnerilirFiyatlandırma ve gümrük beyanı için kullanılan ağırlık ve boyutlar.
hsCodeHayırEvrensel 6 haneli HS kodu. Bunu belirtmezseniz Zonos ürünü adına ve açıklamasına göre sınıflandırır.
amountHayırSayı olarak ürün fiyatı.
currencyCodeHayırFiyat para biriminin 3 harfli ISO kodu. amount belirttiğinizde zorunludur.
itemTypeHayırPHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE veya PARTIAL_ITEM. Fiziksel olmayan öğelerin ticari mal olarak beyan edilmesini önler.
provinceOfOriginHayırÜrünün menşei olan eyalet veya il. Bazı varış ülkeleri tarafından zorunlu tutulur.
productCompositionHayır{material, percentage} listesi. Bu olmadan tekstil ürünleri 6 hanenin ötesinde sınıflandırılamaz.
catalogItemUrlHayırSitenizdeki ürün sayfasının bağlantısı. Sınıflandırma doğruluğunu artırır.
imageUrlHayırÜrün görseli için herkese açık bir URL. Sınıflandırma doğruluğunu artırır.

Öğelerinizi eşleştirilebilir hale getirin 

Zonos, tanımlayıcılarınızı şu sırayla kullanarak her gönderi satırını bir katalog öğesine bağlar: önce ürün kimliği, ardından SKU, sonra ad. Kullandığınız tanımlayıcıları kataloğunuz ile taşıyıcınıza gönderdiğiniz veriler arasında doğru ve tutarlı tutun.

Posta gönderileri ek bir kısıtlama getirir. Zonos, posta taşıyıcılarından sınırlı bir alan kümesi alır ve birçok hatta ürüne özgü bilgi taşıyan tek alan gümrük açıklamasıdır. Kataloğunuzun tamamında aynı olan bir açıklama tek başına hiçbir şeyi tanımlayamaz.

Taşıyıcınıza gönderdiğiniz gümrük açıklamasının sonuna ürün kimliğinizi veya SKU'nuzu ekleyin.

Men's bifold wallet, cowhide leather - 123456

Eklenen tanımlayıcı, ilgili katalog öğesindeki productId veya sku ile tam olarak eşleşmelidir.

Açıklama alanları kısadır. Örneğin Canada Post gönderimleri yaklaşık 49 karaktere izin verir; bu nedenle tanımlayıcılarınız uzunsa açıklayıcı kısmı kısaltın. Tanımlayıcı, metinden daha önemlidir.

Öğenin customsDescription alanını taşıyıcınıza gönderdiğiniz dizeyle aynı yapmak zorunlu değildir; ancak bir satır eşleşmediğinde ve nedenini bulmanız gerektiğinde iki tarafı doğrudan karşılaştırılabilir hale getirir.

Eşleştirme genellikle şu durumlarda başarısız olur:

  • Tanımlayıcı açıklamada yer almıyorsa.
  • Tanımlayıcı kataloğunuzdaki hiçbir productId veya sku ile eşleşmiyorsa.
  • Tanımlayıcı, taşıyıcının karakter sınırı nedeniyle kesiliyorsa.
  • Biçimlendirme gönderiden gönderiye değişiyorsa.

Bu davranış henüz kesinleşmemiştir ve kullanıma sunulmadan önce değişebilir.

Katalog öğelerini güncelleme 

catalogItemUpdate, oluşturma işlemiyle aynı girdi türünü kullanır. Yalnızca değiştirmek istediğiniz alanları gönderin.

1mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
2 catalogItemUpdate(input: $input) {
3 id
4 itemKey
5 hsCode
6 customsDescription
7 }
8}

Not: Gönderilmeyen alanlara dokunulmaz; bu da kısmi güncellemeleri güvenli kılar. null göndermek bir değeri temizlemez, yok sayılır. Bir değerin üzerine farklı bir değer yazabilirsiniz, ancak API aracılığıyla bir değeri boşaltamazsınız. Bir alanın temizlenmesi gerekiyorsa Zonos temsilcinizle iletişime geçin.

Öğelerinizi geri okuma 

catalogItem sorgusu id, productId veya sku kabul eder. Zonos'un bir ürün için hangi verileri tuttuğunu doğrulamak için bunu kullanın.

1query CatalogItem($sku: String!) {
2 catalogItem(sku: $sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11 }
12}

Katalog öğelerini silme 

catalogItemDelete, SKU'larınızı veya ürün kimliklerinizi değil, Zonos katalog öğesi kimliklerini alır. Önce catalogItem sorgusuyla kimliği belirleyin.

1mutation CatalogItemDelete($input: [ID!]!) {
2 catalogItemDelete(input: $input)
3}

İlgili 

GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate

Bu sayfa faydalı mıydı?

Destek alın·Hukuki belgeler·© 2026 Zonos
Bu sayfada:
  • Katalog API'si
  • Nasıl çalışır
  • Katalog öğeleri oluşturma
  • Öğelerinizi eşleştirilebilir hale getirin
  • Katalog öğelerini güncelleme
  • Öğelerinizi geri okuma
  • Katalog öğelerini silme
  • İlgili