REST API ile başlangıç: anahtar, yetki ve ilk istek

Sepetya API-first kurulmuştur: mağaza paneli, vitrin ve dış entegrasyonlar aynı REST API'yi kullanır. Yani panelde yapabildiğiniz hemen her şeyi kendi yazılımınızdan da yapabilirsiniz; ERP'nize sipariş aktarabilir, muhasebe programınızdan stok güncelleyebilir ya da kendi iç panelinizde sipariş listesi gösterebilirsiniz.

Bu rehber ilk isteği göndermeye kadar olan yolu anlatır: anahtar oluşturma, kapsam seçme, yanıt biçimini okuma, hataları yorumlama ve sürüm politikası. Olaylardan haberdar olmak için webhook rehberimize bakın; ikisi birlikte kullanıldığında en verimli çalışır.

Önce karar verin: API mi, webhook mu?

İki araç birbirinin yerine değil, yanına geçer. Webhook "bir şey oldu" der, API "tam olarak ne olduğunu" söyler.

İhtiyaç	Araç
Yeni siparişten anında haberdar olmak	Webhook
Geçmiş siparişleri ya da tüm ürün listesini çekmek	API (sayfalayarak)
Stok, fiyat ya da sipariş durumu güncellemek	API
Panelde kimin neyi değiştirdiğini izlemek	Panel: Ayarlar › Denetim kaydı

Siparişlerin panel tarafındaki akışı için sipariş ve iade yönetimi sayfasına bakabilirsiniz.

API anahtarı oluşturun

Anahtarlar Ayarlar › API anahtarları sayfasındadır. "Anahtar oluştur" ile şunları belirlersiniz:

• Ad: entegrasyonun adı ("ERP entegrasyonu" gibi). Her entegrasyona ayrı anahtar verin; birini iptal ettiğinizde diğerleri çalışmaya devam eder.
• Kapsamlar: anahtarın neye erişeceği. Kapsamlar mağaza izinlerinin aynısıdır: ürün okuma, ürün yazma, stok, sipariş, sipariş iadesi, müşteri, kampanya, içerik, tema, SEO, alan adı, eklenti, kargo ve ayarlar. Yalnız ihtiyacınız olanı seçin; okuma yeten yerde yazma kapsamı vermeyin.
• Son kullanma: boş bırakılırsa süresizdir. Geçici bir iş (veri taşıma, denetim) için tarih koymak iyi bir alışkanlıktır.

Birkaç kural baştan bilinmelidir:

• Anahtar yalnız oluşturulduğu anda bir kez gösterilir. Sunucuda yalnız arama öneki ve SHA-256 özeti saklanır; kaybederseniz iptal edip yenisini oluşturursunuz.
• Veri değiştirebilen (yazma, silme, iade) bir kapsam seçtiğinizde işlem, hesabınızın e-postasına gelen altı haneli kodla onaylanır. Kod yalnız o anahtarın adını ve kapsamlarını onaylar.
• Anahtara, onu oluşturan kişinin sahip olmadığı bir izin verilemez. Personel yönetimi, faturalamada değişiklik, API anahtarı yönetimi, denetim kaydı ve mağaza silme kapsam olarak hiç verilemez: bunlar yalnız panelden, kişinin kendi oturumuyla yapılır.
• Anahtar yalnız kendi mağazasında geçerlidir. Başka bir mağazanın yolunu çağırmak 404 döner.
• API anahtarı oluşturmak paketinizde API erişimi özelliğinin açık olmasını gerektirir; kapalıysa istek 402 feature_unavailable ile döner.

Listede her anahtarın öneki, kapsam sayısı, son kullanım tarihi ve son kullanıldığı IP görünür. "İptal et" dediğiniz anda anahtar çalışmayı bırakır; anahtarın oluşturulması ve iptali denetim kaydına yazılır. Anahtarla yapılan değişiklikler de kayıtlarda "API anahtarı" olarak görünür, böylece bir fiyatı kimin değiştirdiği karışmaz.

İlk isteği gönderin

Her istek Authorization başlığıyla gider:

Authorization: Bearer api_live_xxxxxxxxxx_<gizli kısım>

Mağaza kimliğini panel adresinden alırsınız: panelde mağazanızda gezerken adres /stores/<mağaza kimliği>/… biçimindedir. İlk olarak anahtarın gerçekten ne yapabildiğini sorun:

curl -H "Authorization: Bearer $API_KEY" \
  https://api.ornek.com/api/v1/stores/$STORE_ID/me

Yanıt, anahtarın kapsamlarını ve rolünü söyler. Ardından sipariş listesi çekmek şöyle görünür:

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.ornek.com/api/v1/stores/$STORE_ID/orders?paymentStatus=paid&limit=50"

API adresi platformun kendi alan adıdır; kurulumunuzdaki adresi geliştirici sayfasında bulabilirsiniz. Tarayıcıda çalışan bir ön yüze API anahtarı koymayın: anahtar mağaza genelinde geçerlidir ve tarayıcıya konan her şey okunabilir. İstekleri kendi sunucunuzdan yapın.

Bir yazma örneği: stok güncelleme

Okumalar kolaydır; ilk yazma isteği insanı biraz gerginleştirir. En sık kullanılan yazma işlemi stok güncellemedir ve iki yolu vardır: sayımı olduğu gibi yazmak ya da fark (delta) uygulamak. Depodan gelen "3 adet çıktı, 10 adet girdi" bilgisini aktarıyorsanız fark daha güvenlidir, çünkü aradan geçen siparişleri ezmez:

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"variantId":"…varyant kimliği…","delta":-3}],"note":"Depo sayımı"}' \
  https://api.ornek.com/api/v1/stores/$STORE_ID/inventory/adjust

Bu istek inventory.write kapsamını ister. Tek çağrıda en fazla 500 satır gönderilir, delta sıfır olamaz ve yazdığınız not stok hareketlerine düşer; böylece panelde "bu değişiklik nereden geldi?" sorusu cevaplı kalır. Birden çok deponuz varsa satıra locationId ekleyin. Her yazma isteğini önce tek bir kayıtla deneyin, panelden sonucu gözle doğrulayın, sonra toplu çalıştırın.

Yanıt biçimi: data, meta ve hata

Başarılı yanıtlar data alanı taşır; listelerde ayrıca meta gelir:

{
  "data": [ … ],
  "meta": { "page": 1, "limit": 20, "total": 134, "totalPages": 7 }
}

Oluşturma 201, silme 204 döner. Sayfalama ?page=1&limit=20 ile yapılır; limit en fazla 100'dür. Listelerde arama (search), sıralama (sort) ve kayıt türüne özgü süzgeçler bulunur; hangisinin nerede olduğu OpenAPI belgesinde yazılıdır.

Hatalar tek bir biçimdedir:

{
  "error": {
    "code": "validation_error",
    "message": "Girdiğiniz bilgileri kontrol edin.",
    "details": [{ "field": "price", "message": "Fiyat sıfırdan büyük olmalı." }],
    "requestId": "01a0…"
  }
}

requestId her yanıtta bulunur; bir hatayı destek ekibine bildirirken bu kimliği verin, kaydı doğrudan bulunur.

HTTP	Ne demek?	Ne yapmalı?
401 unauthorized	Anahtar yok, yanlış, süresi dolmuş ya da iptal edilmiş	Başlığı ve anahtarın durumunu kontrol edin
402 feature_unavailable / limit_exceeded	Paket özelliği kapalı ya da bir sınır doldu	Paket kapsamını kontrol edin
403 forbidden	Anahtarın o kapsamı yok	Gereken kapsamla yeni anahtar oluşturun
404 not_found / store_not_found	Kayıt yok ya da başka mağazanın kaydı	Kimlikleri ve mağazayı kontrol edin
409 conflict	Çakışma (ör. aynı stok kodu, tükenen stok)	Yanıttaki koda göre davranın
422 validation_error	Gövde geçersiz	details içindeki alan hatalarını gösterin
429 rate_limited	Hız sınırı aşıldı	retry-after kadar bekleyip yeniden deneyin
503 store_unavailable	Mağaza duraklatılmış ya da askıda	Panelden mağaza durumuna bakın

Para, tarih ve dil

• Para her zaman küçük birimde tamsayıdır: priceMinor: 12990, 129,90 demektir ve yanında currencyCode gelir. Kuruşu kayan noktalı sayıyla hesaplamayın.
• Tarihler ISO 8601 ve UTC'dir. Mağazanın saat dilimi mağaza kaydındadır; raporları mağaza saatine çevirirken onu kullanın.
• Çok dilli alanlar (ürün adı, açıklama, kategori) dil koduyla birlikte gelir ve yazılır. Dillerin listesi mağaza ayarlarındadır; yoksa bir dili ekleyene kadar o dile yazamazsınız.

Hız sınırı

İstekler API anahtarı başına (anahtarsız uç noktalarda IP başına) dakikalık bir sınırla sayılır. Sınır aşılırsa yanıt 429 rate_limited olur ve retry-after başlığında kaç saniye beklemeniz gerektiği yazar. Mağazanızın paketindeki dakikalık API istek sınırını fiyatlandırma sayfasındaki karşılaştırma tablosunda görebilirsiniz. Giriş, kayıt ve form gönderimi gibi uç noktaların daha sıkı kendi sınırları vardır.

• Toplu işleri gece gibi sakin saatlere alın ve istekleri eşit aralıklara yayın.
• 429 aldığınızda hemen tekrar denemeyin; retry-after kadar bekleyip artan aralıklarla deneyin.
• Değişmeyen veriyi (kategori ağacı, kargo bölgeleri) kendi tarafınızda önbellekleyin; her istekte yeniden çekmeyin.
• Liste çekerken limit değerini büyük tutup sayfa sayısını azaltın ve yalnız gereken süzgeçle çağırın.

Belge, sürümleme ve uyumluluk

Tam ve her zaman güncel referans, koddaki şemalardan üretilen OpenAPI 3.1 belgesidir: GET /api/v1/openapi.json. Kurulumunuzda açıksa /api/docs adresinde denenebilir bir arayüz de bulunur. Belgeden kendi dilinize istemci üretebilirsiniz; alan adları, zorunlu alanlar ve enum değerleri oradan okunur.

Sürüm politikası basittir: /api/v1 içinde yalnız geriye uyumlu eklemeler yapılır (yeni uç nokta, isteğe bağlı alan, yeni enum değeri). Kırıcı bir değişiklik gerekirse yeni bir ana sürüm (/api/v2) açılır, v1 çalışmaya devam eder. Bu yüzden istemcinizi şöyle yazın:

• Tanımadığınız alanları yok sayın, hata vermeyin.
• Enum değerlerini kapalı liste gibi ele almayın; beklenmeyen bir değer gelirse kaydı atlamak yerine "bilinmeyen" olarak işleyin.
• Yeni alanları kullanmaya başlamadan önce OpenAPI belgesinin yeni sürümüyle karşılaştırın.

Platform tarafındaki değişiklikleri nasıl takip edeceğinizi güncellemeler yazımızda anlattık.

Entegrasyon kontrol listesi

• Her entegrasyon için ayrı, adı belli bir API anahtarı oluşturuldu.
• Kapsamlar en az yetki ilkesine göre seçildi; okuma yeten yerde yazma verilmedi.
• Anahtar ortam değişkeninde tutuluyor; koda, günlüklere ve tarayıcıya yazılmıyor.
• Mağaza kimliği yapılandırmadan okunuyor, isteklere elle yazılmıyor.
• Listeler sayfalanarak çekiliyor; meta.totalPages dikkate alınıyor.
• Hatalar error.code alanına göre işleniyor; requestId günlüğe yazılıyor.
• 429 için bekleyip yeniden deneme mantığı var.
• Para birimi küçük birim tamsayı olarak işleniyor; tarihler UTC'den mağaza saatine çevriliyor.
• Anında haber gerektiren akışlar webhook'a bağlandı, toplu okumalar API'de kaldı.
• Anahtar yenileme ve iptal prosedürü (kim, nasıl, nereden) yazılı.

Kendi entegrasyonunuzu deneme süresi boyunca denemek için ücretsiz başlayın. Verinizi ilk kez taşıyacaksanız CSV ile toplu veri aktarma rehberine de bakın.