API nedir? Pazaryeri satıcısı için teknik olmayan anlatım

API: mağazanızın arka kapısı

Pazaryeri panelini bir mağazanın ön kapısı gibi düşünün: siz girersiniz, ekranlara tıklarsınız, stok değiştirirsiniz. API (Application Programming Interface) aynı mağazanın arka kapısıdır: insanlar değil yazılımlar girer, aynı işleri (stok güncelle, siparişleri listele, soruyu cevapla) tıklamadan, komutla yapar. Pazaryeri bu kapının hangi komutları kabul ettiğini bir belgeyle duyurur; örneğin Trendyol'un entegrasyon dokümanı ürün, stok, sipariş ve soru işlemlerini ayrı başlıklarda listeler.

Sizin için anlamı: entegrasyon yazılımı pazaryerinin kurallarına göre bu arka kapıdan girer; panelde elle yapabildiğiniz çoğu şeyi otomatik yapabilir, panelde olmayan bir şeyi genellikle yapamaz.

API anahtarı: arka kapının anahtarı

Arka kapıdan kimin girdiğini pazaryeri bilmek ister. API anahtarı (ve bazı platformlarda satıcı kimliği, gizli anahtar) sizi tanımlayan şifredir. Mağaza panelinden üretilir, entegrasyon yazılımına girilir; yazılım her istekte bu anahtarı gösterir. Anahtar çalınırsa mağazanız adına işlem yapılabilir; bu yüzden anahtarı e-postayla göndermeyin, yalnızca güvendiğiniz yazılıma girin ve şüphe durumunda panelden yenileyin.

Her platformda anahtarın adı ve alındığı yer farklıdır. WooCommerce'de "tüketici anahtarı ve gizli anahtar" ikilisi (WooCommerce REST API dokümanı), pazaryerlerinde genellikle satıcı kimliği ve API anahtarı. Adımlar için pazaryeri API anahtarı nedir ve WooCommerce REST API bağlantısı rehberleri.

OAuth: anahtar vermeden izin vermek

Bazı platformlar (Etsy, Shopify) şifre vermenizi istemez; bunun yerine "bu uygulamanın mağazama erişmesine izin veriyorum" düğmesine tıklarsınız. Buna OAuth denir. Platform, uygulamaya süreli ve sınırlı bir "jeton" verir; siz istediğiniz an izni panelden iptal edebilirsiniz. Etsy'nin kimlik doğrulama dokümanı bu akışı OAuth 2.0 standardıyla tanımlar.

Sizin için anlamı: OAuth'lu bağlantılarda "anahtar kopyala-yapıştır" yoktur, bir onay ekranı vardır; jetonun süresi dolduğunda yeniden onay istenebilir. Bu, hata değil güvenlik tasarımıdır. Etsy API ve OAuth yazısı ayrıntıyı verir.

İstek sınırı (rate limit): kapıdan dakikada kaç kişi geçer?

Pazaryeri, arka kapıdan dakikada sınırsız istek gelmesine izin vermez; her satıcı için bir sınır koyar (örneğin dakikada belirli sayıda istek). Entegrasyon yazılımı bu sınırı aşarsa pazaryeri geçici olarak "bekle" der. İyi yazılımlar istekleri sıraya koyar ve sınır içinde kalır; bu yüzden binlerce ürünün stok güncellemesi anında değil, dakikalar içinde tamamlanır.

Sizin için anlamı: "stok güncelledim ama pazaryerinde 2 dakika sonra göründü" normaldir. Saatler sürüyorsa ya sınır sürekli aşılıyor ya da hata vardır; senkronizasyon yöneticisi ekranı bu durumu gösterir.

Webhook: pazaryerinin size haber vermesi

Normalde entegrasyon yazılımı pazaryerine düzenli olarak "yeni sipariş var mı?" diye sorar. Webhook ise tersidir: olay olduğunda (sipariş geldi, iade açıldı) pazaryeri sizin yazılımınıza anında haber gönderir. Shopify ve WooCommerce webhook'u yaygın kullanır; pazaryerlerinin bir kısmı yalnızca sorgu yöntemini destekler. Sizin için anlamı: webhook destekli kanallarda sipariş tepkisi saniyeler içindedir, diğerlerinde sorgu aralığına bağlıdır.

Sandbox, versiyon ve "deprecated": değişen kapılar

Sandbox (test ortamı) gerçek mağazanızı etkilemeden denemelerin yapıldığı kopyadır; entegrasyon geliştiricileri kullanır, satıcının genellikle görmesi gerekmez. Versiyon, API'nin sürümüdür: platformlar yeni sürüm çıkarır ve eski sürümü belirli bir tarihten sonra kapatır ("deprecated" = kullanımdan kaldırılıyor). Shopify'ın GraphQL Admin API'si gibi arayüzler düzenli sürümlerle yayımlanır; inventorySetQuantities gibi işlemler sürüm belgesinde ayrı sayfalarla açıklanır.

Sizin için anlamı: entegrasyon sağlayıcınızın bu sürüm değişikliklerini takip etmesi gerekir. Bir kanal "artık çalışmıyor" dediğinde çoğu zaman neden budur; E-Ticaret Haberleri kategorisinde bu tür değişiklikleri takip ediyoruz.

Satıcının bilmesi yeterli olanlar

Bu yazıdaki terimlerin kısa sözlüğü:

• API anahtarı şifredir; güvenle saklayın, gerektiğinde yenileyin.
• OAuth onay ekranı normaldir; iznin süresi dolabilir.
• Senkronun dakikalar sürmesi istek sınırından kaynaklanır; saatler sürmesi hatadır.
• Bir kanal aniden çalışmıyorsa önce anahtar/izin, sonra API sürümü kontrol edilir.

Bu dört kuralı bilen satıcı, entegrasyonun büyük bölümünü kendisi yönetebilir. Gerisi için pazaryeri entegrasyonu nedir yazısı ve Saystok'un ilk kurulum rehberi yeterlidir.

Bir stok güncellemesi arka planda nasıl ilerler?

Somut bir örnekle akışı izleyelim. Pazaryeri A'da bir ürün satıldı. Entegrasyon yazılımı, A'nın API'sine "yeni siparişler" sorgusu atar (veya webhook ile haber alır), siparişi okur ve merkezi stoktan 1 düşer. Sonra sırayla B, C ve WooCommerce mağazanızın API'lerine "bu ürünün stoku artık 9" komutunu gönderir. Her platform komutu kabul edip "tamam" döner ya da bir hata kodu verir: anahtar geçersiz, ürün bulunamadı, istek sınırı aşıldı.

Hata dönen kanal için yazılım yeniden dener; tekrar başarısız olursa günlüğe yazar ve sizi uyarır. Bu yüzden senkron günlüğü (hangi kanala, ne zaman, ne gönderildi, cevap ne oldu) entegrasyonun en değerli ekranıdır; sorun çıktığında ilk bakılacak yer orasıdır (senkronizasyon yöneticisi).

• Sipariş okundu → merkezi stok düştü.
• Her kanala yeni adet gönderildi → "tamam" veya hata.
• Hata → yeniden deneme → günlük + uyarı.

Platform farkları: aynı iş, farklı kapılar

Her platformun API'si aynı işi biraz farklı yapar. Shopify stoku lokasyon ve stok kalemi bazında tutar; stok yazmak için ürün değil, lokasyondaki stok kalemi hedeflenir (inventorySetQuantities). WooCommerce'de stok ürün veya varyasyon nesnesinin alanıdır. Pazaryerlerinde ise genellikle barkod veya stok kodu ile toplu stok-fiyat güncellemesi yapılır ve sonuç bir "parti" olarak daha sonra sorgulanır; yani güncelleme anında değil, parti işlendikten sonra görünür.

Satıcı için bu farkların tek sonucu vardır: "stoku güncelledim" ile "pazaryerinde göründü" arasındaki süre platforma göre değişir ve bu normaldir. Hangi platformda neyin nasıl çalıştığını merak ederseniz Shopify stok yapısı ve WooCommerce REST API yazılarına bakın.