ikas API rehberi: API anahtarı, ikas CLI ve webhook'lar

Bu yazıyı iki kişi için yazdık. Birincisi, geliştiricisine ne isteyeceğini netleştirmek isteyen mağaza sahibi. İkincisi, ikas ekosistemine ilk kez bakan geliştirici. Her somut bilgiyi ikas'ın kendi dokümanlarından doğruladık ve kaynağını yanına koyduk.

ikas API anahtarı (Client ID ve Secret) nasıl alınır?

ikas'ta "API anahtarı" denince kastedilen, panelde oluşturduğun özel uygulamanın Client ID ve Client Secret bilgileridir. Muhasebe, kargo ya da pazaryeri entegratörlerinin senden istediği bilgi de budur. Bu adımı mağaza sahibi kendisi yapabilir; ikas destek makalesi yolu şöyle tarif ediyor:

1. Panelde Uygulamalar > Uygulamalarım alanına gidersin.
2. Özel Uygulamalara Git butonuna, ardından Özel Uygulama Ekle butonuna tıklarsın.
3. Uygulama adı ve bildirim e-postası girersin.
4. Uygulama tipini seçersin. Standart Uygulama GraphQL API üzerinden çalışan klasik entegrasyondur, MCP İstemcisi ise yapay zeka entegrasyonları içindir.
5. İzinleri işaretlersin. Ürünler, Siparişler, Müşteriler, Kampanyalar, Envanter ve Online Mağaza grupları için ayrı ayrı görüntüleme ya da düzenleme yetkisi verirsin.
6. Uygulamanın dış kanallardan sipariş oluşturup oluşturamayacağını belirleyen satış kanalı ayarını yaparsın.
7. Kaydettiğinde Client ID ve Secret üretilir.
8. Entegratöre yalnız ihtiyaç duyduğu izinleri ver; örneğin siparişleri yalnız okuyup fatura kesen bir program için siparişleri okuma izni yeterlidir.

Secret bilgisini bir kez görürsün, o yüzden güvenli bir yere kaydetmen gerekir. Sonrasındaki akış tamamen geliştirici tarafında: bu bilgilerle önce bir erişim token'ı alınır, sonra sorgular GraphQL adresine gönderilir.

Buradaki en sık hatayı söyleyelim: secret'ı tarayıcıda çalışan bir koda koymak. O bilgi mağazanın kapısının anahtarıdır ve yalnızca sunucu tarafında durmalıdır.

ikas API'ye ilk istek: token ve GraphQL adresi

Client ID ve Secret ile önce bir erişim token'ı alınır, sonra her istek bu token'la GraphQL adresine gönderilir. Token alma adresi ile API adresi farklıdır:

Dönen token, ikas'ın kimlik doğrulama dokümanına göre 14.400 saniye, yani dört saat geçerlidir; süre dolunca yenisi alınır. Uzun çalışan entegrasyonlarda token yenilemenin otomatik olması gerekir.

Sorguları kod yazmadan denemek için ikas'ın GraphQL Playground sayfasını ve Postman dokümantasyonunu kullanabilirsin. Geliştiricine iş vermeden önce burada tek bir ürün sorgusu çalıştırmak, veri modelinin ihtiyacını karşılayıp karşılamadığını görmenin en hızlı yolu. Biz de her projeye önce bu adımla başlıyoruz, çünkü veri modelinde eksik gördüğün bir alan projenin kapsamını baştan değiştirir.

ikas API nedir, hangi parçalardan oluşur?

ikas API'yi tek bir şey sanmak yaygın bir hata. Pratikte birkaç ayrı parça var ve her biri farklı bir işi çözüyor. ikas geliştirici dokümanı bu parçaları şöyle ayırıyor.

• Admin API: Ürün, sipariş, müşteri, envanter ve kampanya verisini okuyup yazdığın GraphQL arayüzü. Tek bir adrese istek atarsın, hangi alanları istediğini sen belirlersin. Teknik sorgu yapısı ikas Admin API dokümantasyonunda açıklanıyor.
• Webhook'lar: Mağazada bir olay olduğunda ikas senin sunucuna haber verir. Sipariş oluştu, stok değişti gibi durumları sürekli sorgulamak zorunda kalmazsın.
• Uygulama aksiyonları: ikas panelinin içine kendi butonunu koyarsın. Kullanıcı panelden çıkmadan senin uygulamanı çalıştırır.
• Storefront olayları: Vitrinde olan biteni dinleyen JavaScript olay sistemi. Sayfa görüntüleme, sepete ekleme gibi hareketleri üçüncü parti araçlara taşımak için kullanılır.
• Tema geliştirme: Vitrinin kendisi. Burada ikas Studio Kod modunda Preact ya da Next.js tabanlı tema altyapısında React tarafındasın, Admin API tarafında değil.
• MCP sunucusu: Yapay zeka araçlarının Admin API'yi doğrudan kullanmasını sağlayan yeni katman. Cursor ya da Claude Code gibi araçlarla şema üzerinden sorgu yazabiliyorsun.

GraphQL kısmını teknik olmayan biri için şöyle anlatıyoruz. Klasik API'lerde her veri için ayrı adres vardır ve o adres sana ne verirse onu alırsın. GraphQL'de tek adres vardır ve istediğin alanları sipariş verir gibi tek tek yazarsın. Sonucu şu olur: gereksiz veri taşımazsın, entegrasyon daha az istekle daha hızlı çalışır.

Son dönemde eklenen MCP katmanı da işi değiştiriyor. ikas MCP dokümanına göre sunucu, müşteri, ürün, sipariş ve kampanya tarafında hazır sorgu ve işlem araçları sunuyor. Geliştirici bunu kod editörüne bağlayıp şema üzerinden sorgu yazabiliyor. Mağaza sahibi açısından anlamı şu: aynı entegrasyon artık daha kısa sürede kurulabiliyor, çünkü geliştirici dokümanı tek tek okumak yerine şemayı doğrudan sorguluyor.

Özel uygulama ile Admin uygulaması arasındaki fark nedir?

Bu ayrımı baştan doğru yapmazsan iki hafta sonra baştan yazmak zorunda kalırsın. İkisinin de kullandığı veri aynı, ayrıldıkları yer kimin için çalıştıkları.

Mağaza sahibi tarafından bakarsan cümle şu: kendi işin için bir entegrasyon istiyorsan özel uygulama yeter, ondan ötesi gereksiz maliyettir.

ikas CLI nedir, nasıl kurulur?

ikas CLI, ikas'ın resmi komut satırı aracıdır. Partner hesabıyla uygulama projesi başlatmak, geliştirme sunucusunu test mağazasına bağlamak ve ikas Studio Kod modunda tema bileşeni geliştirmek için kullanılır. npm ile npm i -g ikas komutuyla kurulur; ikas'ın CLI dokümanı Node.js 16 ve üzerini istiyor, güncel bir sürüm kullanmak en güvenlisi.

ikas app init ile gelen başlangıç projesi Next.js App Router, OAuth 2.0 akışı, GraphQL istemcisi, Prisma ile SQLite, Tailwind CSS ve TypeScript içeriyor. Tek mağazaya özel, arayüzsüz bir entegrasyon kuracaksan CLI'ya gerek yok; özel uygulamanın Client ID ve Secret'ı yeterli. Kod modunda tema geliştirme adımlarını ikas özel tema nasıl yapılır yazısında anlattık.

Test mağazası, tünel ve ortam değişkenleri

Özel uygulama ile yalnızca tek mağazaya çalışan arka plan entegrasyonu kurulacaksa geliştirme doğrudan sunucu tarafındaki API bağlantısıyla ilerleyebilir. ikas paneli içinde çalışan bir Admin uygulaması geliştirilecekse süreç daha kapsamlıdır. Resmi Admin uygulaması geliştirme dokümanı test mağazası seçimi, yerel geliştirme ortamı, proje yapısı, OAuth akışı, API endpoint'leri ve environment variable kullanımını aynı geliştirme sürecinin parçaları olarak ele alıyor.

Geliştirme sırasında gerçek müşterilerin kullandığı mağazada deneme yapmak yerine test mağazası kullanmak daha kontrollüdür. Uygulamanın panel içindeki ekranları, yetkilendirme akışı ve GraphQL sorguları burada denenir. Yerel bilgisayarda çalışan uygulamanın ikas tarafından erişilebilir olması gerektiğinde dokümantasyondaki tünel yaklaşımı kullanılabilir. Böylece geliştirme tamamlanmadan canlı ortamı değiştirmek gerekmez.

Environment variable tarafında Client ID, Secret, veritabanı bağlantısı ve benzeri hassas bilgiler kaynak kodun içine yazılmamalıdır. Uygulama farklı ortamlarda çalıştırıldığında bu bilgiler ortam değişkenleri üzerinden verilmelidir. Kaynak kod teslimi yapılmadığı projelerde de çalışan uygulama ve entegrasyon teslim edilir; geliştirme altyapısının kaynak kodu ayrıca teslim edilmez.

OAuth ve güvenlik

Tek mağazaya kurulan özel uygulamada uygulama kimliği ve secret belirli mağaza için oluşturulur. Çok mağazalı Admin uygulamasında ise her mağazanın uygulamaya kendi erişim iznini vermesi gerekir. Bu nedenle authorization code tabanlı OAuth akışı kullanılır. Yetkilendirme yöntemlerinin teknik ayrıntıları ikas yetkilendirme dokümantasyonunda açıklanıyor.

Güvenlik tarafında temel kural, mağaza erişim bilgilerini tarayıcıya göndermemektir. OAuth dönüşleri, token saklama, webhook doğrulama ve API çağrıları sunucu tarafında yönetilmelidir. Her mağazanın erişim bilgisi diğer mağazalardan ayrılmalı ve yalnız gerekli kapsamlarla çalışmalıdır. Admin uygulaması geliştirirken başlangıç projesindeki güvenlik yapısını değiştirmeden önce resmi geliştirme mimarisini incelemek gerekir.

ikas API hangi verilere erişir, izinler nasıl çalışır?

ikas, erişimi izin (scope) adı verilen yetkilerle ayırıyor. ikas'ın geliştirici dokümanında beş okuma ve altı yazma izni tanımlı:

• Ürünler: okuma ve yazma (ürün, varyant, fiyat)
• Siparişler: okuma ve yazma (sipariş, paket, kargo durumu)
• Müşteriler: okuma ve yazma
• Kampanyalar: okuma ve yazma
• Envanter: okuma ve yazma (stok seviyeleri)
• Vitrin (Storefront): yalnız yazma izni

Mağaza sahibi olarak buradan çıkaracağın kural basit. Bir uygulama neden yazma yetkisi istiyorsa onu sorabilirsin. Sadece rapor üreten bir araç için yazma yetkisi gerekmez. Biz geliştirirken de en az yetki ilkesini uyguluyoruz, çünkü fazla yetki hata anında daha büyük zarar demek.

Uygulamalar sadece veri okuyup yazmakla kalmıyor. Vitrine JavaScript eklemek için ayrı bir mutation var, uygulama aksiyonlarıyla da panele buton konulabiliyor. ikas aksiyon dokümanına göre aksiyonlar ürün düzenleme sayfasına, sipariş sayfasına ve sipariş listesindeki toplu işlemler menüsüne yerleştirilebiliyor.

Webhook'lar ve API limitleri: sistem nerede kırılır?

Webhook olayları

Webhook, entegrasyonun kalbidir. Sipariş geldiğinde bunu öğrenmek için ikas'a saniye başı sormak yerine, ikas'ın sana haber vermesini sağlarsın. ikas SDK dokümanında listelenen olaylar şunlar:

• store/order/created ve store/order/updated
• store/product/created ve store/product/updated
• store/customer/created, store/customer/updated ve store/customer/statusUpdated
• store/stock/created ve store/stock/updated

Aynı doküman iki önemli detay daha veriyor. Gelen isteğin gerçekten ikas'tan geldiğini doğrulamak için imza kontrolü yapılıyor. Senin sistemin 200 dışında bir yanıt dönerse ikas üç kez tekrar deniyor, sonra vazgeçiyor. Bu üçüncü denemeden sonra kaybolan sipariş bildirimi, pratikte en çok can yakan sessiz hatalardan biridir.

Bu yüzden ciddi entegrasyonlarda webhook'u tek başına bırakmıyoruz. Yanına günde birkaç kez çalışan bir karşılaştırma işi koyuyoruz. Bu iş, son saatlerdeki siparişleri API'den çekip kendi tarafında eksik olanı tamamlıyor. Böylece sunucun beş dakika kapalı kaldığında veri kaybı yaşamıyorsun. Mağaza sahibi olarak geliştiricine soracağın soru şu: webhook düşerse ne oluyor. Stok tarafındaki benzer veri akışını ikas stok takibi ve kritik stok uyarısı rehberinde uygulama senaryosu üzerinden görebilirsin.

Hız limitleri ve engelleme kuralları

ikas hız limiti dokümanı eşikleri açıkça veriyor:

Bunun günlük hayattaki karşılığı şu: 5.000 ürünü tek seferde güncellemeye kalkarsan sistem seni durdurur. Doğru yöntem, işleri kuyruğa alıp parça parça göndermek ve hata dönen istekleri tekrar denemektir. Bu detayı atlayan entegrasyonlar ilk kampanya gününde kilitlenir.

ikas Storefront API diye bir şey var mı?

Bu arama çok yapılıyor, o yüzden net konuşalım. ikas'ın resmi dokümanlarında "Storefront API" başlıklı ayrı bir bölüm bulamadık. npm'de ikas'ın yayımladığı @ikas/storefront-api adlı bir paket görürsün; paket açıklaması onu ikas'ın vitrin modellerini döndüren fonksiyonlar olarak tanımlıyor. Bu, Next.js tabanlı tema altyapısının kullandığı bir kütüphanedir, ayrıca belgelenmiş bir vitrin API'si değildir. Vitrin tarafındaki ihtiyaçlar üç ayrı yoldan çözülüyor.

• Tema geliştirme: Vitrin, ikas Studio Kod modunda Preact ile ya da Next.js tabanlı tema altyapısında React bileşenleriyle yazılıyor; her iki yolda da TypeScript kullanılıyor. Mağazanın yönetebileceği bölüm, bileşen ve alanları kodluyorsun. Bu tarafı ikas özel tema nasıl yapılır yazısında ayrıntılı anlattık.
• Storefront olayları: Vitrinde çalışan bir JavaScript dosyası yazıp kullanıcı hareketlerini dinliyorsun. Ölçümleme ve üçüncü parti araç entegrasyonları burada kuruluyor.
• Uygulamanın vitrine script eklemesi: Admin API'de vitrine JavaScript yerleştiren bir mutation var. App Store'daki uygulamaların vitrinde görünen parçaları çoğunlukla bu yoldan geliyor.

Yani vitrinde bir şey göstermek istiyorsan Admin API'ye değil, bu üç yola bakacaksın. Bu ayrımı baştan bilmek zaman kazandırır, çünkü vitrin tarafındaki bir ihtiyacı Admin API ile çözmeye çalışmak boşa emek olur. Teklif alırken de "bu iş tema tarafında mı, uygulama tarafında mı çözülecek" diye sorabilirsin; vitrin tarafındaki köklü değişiklikler çoğunlukla özel tema işidir.

Hazır uygulama mı, özel geliştirme mi?

Bu kararı yanlış vermek en pahalı hata. Aşağıdaki tabloyu müşterilerimizle konuşurken kullanıyoruz.

Karar öncesi üç soruyu netleştirmeni öneriyoruz. Birincisi, bu süreç bir yıl sonra da aynı mı kalacak. İkincisi, entegrasyon durduğunda işin durur mu yoksa elle devam edebilir misin. Üçüncüsü, veri kimde duracak. Kritik bir akış kuruyorsan ve durduğunda işin duruyorsa, hazır uygulamadaki küçük bir eksikliği tolere etmek yerine özel geliştirme daha sağlıklı olur. Tersine, ayda birkaç kez kullanacağın bir rapor için özel uygulama yazdırmak gereksiz yüktür.

Somut örnek istersen yayındaki uygulama çalışmalarını inceleyebilirsin. Envanter, kampanya, ürün, vitrin ve sipariş gibi farklı alanlarda çalışan uygulamalar aynı Admin API üzerinde farklı veri ve iş akışlarını kullanabilir.

Uygulama ikas App Store'da nasıl yayınlanır?

Yalnızca kendi mağazan için geliştirme yapacaksan bu bölümü atlayabilirsin. Uygulamanı başka mağazalara açacaksan süreç yayınlama dokümanında tarif ediliyor. App Store tarafındaki genel yapı için ikas App Store rehberini de inceleyebilirsin.

Önce ön koşullar var. Partner hesabının doğrulanmış olması, uygulamanın bu hesapta kayıtlı olması, OAuth akışının çalışır durumda olması ve en az iki test mağazasında kurulumun tamamlanmış olması gerekiyor. Ardından beş adım geliyor: planları belirleme, bölgeleri seçme, uygulama detaylarını girme, mağaza içeriğini tamamlama ve yayınlama tercihini seçme.

Son adımdaki tercih önemli. Herkese açık yayında uygulaman ikas ekibi tarafından inceleniyor ve Uygulama Mağazası'nda listeleniyor. Gizli yayında inceleme olmuyor, uygulama yalnızca paylaştığın bağlantıyla kuruluyor. Tek bir müşteri için geliştirdiğin ama App Store altyapısını kullanmak istediğin işlerde gizli yayın pratik bir yol.

Ücretli uygulamalarda tahsilatı ikas yönetiyor. Mağaza uygulamayı Uygulama Mağazası üzerinden satın alıyor, sen de satın alımları webhook ve lisans sorgusuyla takip ediyorsun. Bu, kendi ödeme altyapını kurma yükünü ortadan kaldırıyor.

Planlar tarafında iki ayrıntıyı baştan bilmek işini kolaylaştırır. Plan dokümanına göre planlar TRY, EUR ve USD para birimlerinde aylık ya da yıllık olarak tanımlanıyor ve seçtiğin bölge, yalnızca o bölgeye uygun para birimindeki planlarla eşleşiyor. İkincisi, planlara isteğe bağlı deneme süresi ekleyebiliyorsun. Deneme süresini takip etmek senin tarafında kalıyor, çünkü mağazanın kurulum tarihini kendi sistemine yazıp süre bittiğinde erişimi kapatman gerekiyor.

Ne zaman yardım almalısın?

Panelden özel uygulama açmak ve izinleri seçmek teknik bilgi istemiyor, bunu kendin yapabilirsin. Token yönetimi, kuyruk kurgusu, webhook imza doğrulaması ve hata durumunda tekrar deneme mantığı ise geliştirici işi; bu kısımlar atlandığında entegrasyon ilk yoğun günde sessizce durur. Kendi mağazan için bir entegrasyon ya da App Store'a çıkacak bir uygulama düşünüyorsan ikas uygulama geliştirme sayfasına bakabilir, ikas partner sayfamızdan nasıl çalıştığımızı görebilirsin. Ne yapmak istediğini yazarsan uygun yolu birlikte netleştiririz, iletişim sayfasından ulaşabilirsin.

Kaynaklar

• ikas Builders geliştirici dokümantasyonu
• ikas uygulama geliştirme ve uygulama türleri
• ikas Admin API dokümantasyonu
• ikas Admin API yetkilendirme
• Özel uygulama token alma (Authentication)
• ikas Admin API izinleri (AppScopeEnum)
• ikas CLI dokümanı
• ikas Admin API hız limitleri
• ikas Admin uygulaması geliştirme süreci
• ikas özel uygulama oluşturma rehberi
• ikas geliştirici portalı