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.
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.
Ü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.
productId
Evet*
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.
manufacturerProductId
Yalnızca AB
Standart Olmayan Üretici Ürün Tanımlayıcısı (NS-PID). Değeri 150 EUR veya daha az olan AB'ye yönelik B2C gönderilerinde zorunludur.
gtin
Yalnızca AB
Standart Üretici Ürün Tanımlayıcısı (S-PID), yalnızca rakamlar. Ürünün bir barkodu varsa, değeri 150 EUR veya daha az olan AB'ye yönelik B2C gönderilerinde zorunludur.
name
Evet
Ürün adı.
customsDescription
Önerilir
Gü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
Önerilir
Fiyatlandırma ve gümrük beyanı için kullanılan ağırlık ve boyutlar.
hsCode
Hayır
Evrensel 6 haneli HS kodu. Bunu belirtmezseniz Zonos ürünü adına ve açıklamasına göre sınıflandırır.
amount
Hayır
Sayı olarak ürün fiyatı.
currencyCode
Hayır
Fiyat para biriminin 3 harfli ISO kodu. amount belirttiğinizde zorunludur.
itemType
Hayır
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE veya PARTIAL_ITEM. Fiziksel olmayan öğelerin ticari mal olarak beyan edilmesini önler.
provinceOfOrigin
Hayır
Ürünün menşei olan eyalet veya il. Bazı varış ülkeleri tarafından zorunlu tutulur.
productComposition
Hayır
{material, percentage} listesi. Bu olmadan tekstil ürünleri 6 hanenin ötesinde sınıflandırılamaz.
catalogItemUrl
Hayır
Sitenizdeki ürün sayfasının bağlantısı. Sınıflandırma doğruluğunu artırır.
imageUrl
Hayır
Ürün görseli için herkese açık bir URL. Sınıflandırma doğruluğunu artırır.
AB ürün tanımlayıcıları (PID) ekleme
Doğrulanmış Hesabınızla AB'ye gönderim yapıyorsanız AB, 1 Kasım 2026'dan itibaren değeri 150 EUR veya daha az olan işletmeden tüketiciye (B2C) gönderilerde ürün tanımlayıcıları (PID) zorunlu tutar. Bunları katalog öğelerinizde saklayın. Çoğu Doğrulanmış Hesap için gönderi verilerini Zonos'a posta idareniz gönderir; Zonos gönderideki her öğeyi kataloğunuzla eşleştirir ve kaydettiğiniz tanımlayıcıları uygular. Böylece gönderim sırasında ek bir şey göndermeniz gerekmez.
Tanımlayıcı↕
Nedir↕
API alanı↕
Zorunlu mu?↕
Satıcı Ürün Tanımlayıcısı (M-PID)
SKU'nuz veya ürün kodunuz
sku
Her zaman
Standart Olmayan Üretici Ürün Tanımlayıcısı (NS-PID)
Üreticinin model veya parça numarası. Ürünü kendiniz üretiyorsanız kendi model veya parça numaranızı kullanın.
manufacturerProductId
Her zaman
Standart Üretici Ürün Tanımlayıcısı (S-PID)
Barkod (UPC, EAN veya ISBN)
gtin
Yalnızca ürünün barkodu varsa
Yeni ürünler için tanımlayıcıları catalogItemCreate ile gönderin. Kataloğunuzda zaten bulunan ürünler için bunları aynı alanları kabul eden catalogItemUpdate ile gönderin. Zonos'un ikisini birbirine bağlayabilmesi için her öğenin sku değerini başka her yerde kullandığınız SKU ile eşleştirin.
gtin değerini tire veya boşluk olmadan yalnızca rakamlarla gönderin. UPC, EAN, JAN ve 13 haneli ISBN değerlerinin tümü bu tek alana girer. 10 haneli bir ISBN'niz varsa bunun yerine 13 haneli sürümünü gönderin.
Bir ürünün barkodu yoksa boş bir dize göndermek, SKU'nuzu yeniden kullanmak veya alanı N/A gibi yer tutucu bir metinle doldurmak yerine gtin alanını hiç göndermeyin.
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önderi verilerinde tanımlayıcıyı nasıl biçimlendireceğiniz posta idarenize bağlıdır, çünkü her posta idaresi gönderileri kataloğunuzla farklı şekilde eşleştirir. Tüm posta idareleri sayfasına gidin ve posta idarenizi seçin. Sayfası, o posta idaresi için eşleştirmenin nasıl çalıştığını ve tam olarak ne göndermeniz gerektiğini gösterir.
Öğ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:
Posta idarenizin eşleştirmede kullandığı tanımlayıcı gönderi verilerinde yer almıyorsa.
Tanımlayıcı kataloğunuzdaki hiçbir şeyle tam olarak 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.
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.
1queryCatalogItem($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.
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
Gönderdiğiniz her ürün için bir katalog öğesi oluşturun.
Her öğenin, posta taşıyıcınızın ileteceği bir tanımlayıcı içerdiğinden emin olun.
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
catalogItemCreatebir liste kabul eder; böylece tek bir istekte çok sayıda ürün gönderebilirsiniz.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}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
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamountbelirttiğinizde zorunludur.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEveyaPARTIAL_ITEM. Fiziksel olmayan öğelerin ticari mal olarak beyan edilmesini önler.provinceOfOriginproductComposition{material, percentage}listesi. Bu olmadan tekstil ürünleri 6 hanenin ötesinde sınıflandırılamaz.catalogItemUrlimageUrlAB ürün tanımlayıcıları (PID) ekleme
Doğrulanmış Hesabınızla AB'ye gönderim yapıyorsanız AB, 1 Kasım 2026'dan itibaren değeri 150 EUR veya daha az olan işletmeden tüketiciye (B2C) gönderilerde ürün tanımlayıcıları (PID) zorunlu tutar. Bunları katalog öğelerinizde saklayın. Çoğu Doğrulanmış Hesap için gönderi verilerini Zonos'a posta idareniz gönderir; Zonos gönderideki her öğeyi kataloğunuzla eşleştirir ve kaydettiğiniz tanımlayıcıları uygular. Böylece gönderim sırasında ek bir şey göndermeniz gerekmez.
skumanufacturerProductIdgtinYeni ürünler için tanımlayıcıları
catalogItemCreateile gönderin. Kataloğunuzda zaten bulunan ürünler için bunları aynı alanları kabul edencatalogItemUpdateile gönderin. Zonos'un ikisini birbirine bağlayabilmesi için her öğeninskudeğerini başka her yerde kullandığınız SKU ile eşleştirin.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}gtindeğerini tire veya boşluk olmadan yalnızca rakamlarla gönderin. UPC, EAN, JAN ve 13 haneli ISBN değerlerinin tümü bu tek alana girer. 10 haneli bir ISBN'niz varsa bunun yerine 13 haneli sürümünü gönderin.Bir ürünün barkodu yoksa boş bir dize göndermek, SKU'nuzu yeniden kullanmak veya alanı
N/Agibi yer tutucu bir metinle doldurmak yerinegtinalanını hiç göndermeyin.Landed Cost API'sini kendiniz çağırıyorsanız bu tanımlayıcıları landed cost isteğinize de ekleyebilirsiniz. Çoğu Doğrulanmış Hesap bunu yapmaz, çünkü gönderi verilerini Zonos'a gönderen taraf posta idaresidir.
Yönetmeliğin neleri zorunlu tuttuğu için AB ürün tanımlayıcıları kılavuzuna bakın.
Öğ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önderi verilerinde tanımlayıcıyı nasıl biçimlendireceğiniz posta idarenize bağlıdır, çünkü her posta idaresi gönderileri kataloğunuzla farklı şekilde eşleştirir. Tüm posta idareleri sayfasına gidin ve posta idarenizi seçin. Sayfası, o posta idaresi için eşleştirmenin nasıl çalıştığını ve tam olarak ne göndermeniz gerektiğini gösterir.
Öğenin
customsDescriptionalanı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:
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.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Öğelerinizi geri okuma
catalogItemsorgusuid,productIdveyaskukabul eder. Zonos'un bir ürün için hangi verileri tuttuğunu doğrulamak için bunu kullanın.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Katalog öğelerini silme
catalogItemDelete, SKU'larınızı veya ürün kimliklerinizi değil, Zonos katalog öğesi kimliklerini alır. ÖncecatalogItemsorgusuyla kimliği belirleyin.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}İlgili
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Bu sayfa faydalı mıydı?