Shopify Özel API ve App Entegrasyonu: Teknik Altyapı Rehberi

Shopify Özel API Entegrasyonu Nedir? Shopify özel API entegrasyonu, mağazanın standart uygulama mağazasında karşılığı olmayan bir iş sürecini Admin API, Storefront API veya webhook altyapısı üzerinden özel yazılmış bir uygulamayla otomatikleştirme yöntemidir.

Shopify, mağaza verisine dışarıdan erişimi tek bir kapıdan değil, amaca göre ayrılmış birden fazla API katmanından sunar (Shopify.dev, 2025). Admin API sipariş, ürün ve stok gibi arka ofis verisine erişirken, Storefront API müşteri arayüzü tarafında özel alışveriş deneyimleri kurmak için tasarlanmıştır. Bu ayrım, “özel entegrasyon” denilince akla gelen tek bir teknolojiyi değil, ihtiyaca göre seçilen bir API kombinasyonunu işaret eder.

Bir ERP sistemiyle stok senkronize etmek, bir pazaryerinden gelen siparişleri otomatik işlemek veya headless (ayrışık) bir vitrin kurmak her biri farklı API katmanı ve farklı kimlik doğrulama (authentication) yöntemi gerektirir. Bu rehber, hangi API’nin hangi problemi çözdüğünü net çizgilerle ayırır ve her alt konunun derinlemesine işlendiği kaynaklara yönlendirir.

Shopify API Türleri Nelerdir?

Shopify üç ana API ailesi sunar: Admin API mağaza yönetim verisine, Storefront API müşteri arayüzü verisine, Partner API ise uygulama geliştiricilerin çoklu mağaza yönetimine erişir. Bir entegrasyon projesinin ilk adımı, hangi verinin hangi API’den okunacağını netleştirmektir.

Admin API; ürün, sipariş, müşteri, stok ve ödeme verisine erişim sağlar ve bir uygulamanın mağaza sahibi adına işlem yapabilmesi için OAuth ile yetkilendirilir. Storefront API ise herkese açık ürün kataloğu ve sepet verisine erişir; müşteri kimliğine ihtiyaç duymadan çalışabilir ve genelde headless vitrin projelerinde tercih edilir.

Quotable: Admin API mağaza sahibinin arka ofis verisini yönetir, Storefront API ise müşterinin gördüğü alışveriş deneyimini besler ikisi aynı amaca hizmet etmez.

Peki bu ayrım pratikte ne anlama geliyor? Bir mobil uygulama sadece ürün listelemek istiyorsa Storefront API yeterlidir; ama sipariş oluşturup stok düşürmesi gerekiyorsa Admin API’ye ve OAuth yetkilendirmesine ihtiyaç duyar.

Bu tablodaki auth farkı sadece teknik bir detay değildir Admin API erişimi mağaza sahibinin onayına ve kapsam (scope) tanımına bağlıyken, Storefront API çoğu durumda geliştiriciye doğrudan bir public token ile verilir.

Admin API ile GraphQL Admin API Arasındaki Fark Nedir?

Shopify, Admin API’yi hem REST hem GraphQL protokolüyle sunar; GraphQL Admin API, Ekim 2024 itibarıyla yeni uygulamalar için önerilen birincil yöntemdir (Shopify.dev, 2025). REST Admin API halen desteklenir ancak Shopify yeni özellik geliştirmesini GraphQL tarafında yoğunlaştırır.

REST Admin API her kaynak için ayrı endpoint ve sabit istek/yanıt yapısı sunarken, GraphQL Admin API tek bir endpoint üzerinden istenilen alanları seçerek sorgulama imkanı verir. Bu fark, özellikle çoklu kaynak birleştiren (ürün + stok + sipariş) entegrasyonlarda istek sayısını doğrudan etkiler.

İpucu: Yeni bir custom app geliştiriliyorsa GraphQL Admin API ile başlanmalı. REST üzerinden yazılmış eski bir entegrasyon varsa, Shopify’ın REST API kullanım kısıtlamalarını genişletmemesi nedeniyle orta vadede GraphQL’e geçiş planı yapılmalı.

Rate limit farkı, yüksek hacimli mağazalarda API çağrı stratejisini doğrudan belirler; bu konu tek başına ayrı bir teknik problem alanıdır ve Shopify API rate limit ile stok senkronizasyon hatalarını ele alan rehberde detaylı işlenir.

Webhook Nedir ve Bir Entegrasyonda Ne İşe Yarar?

Webhook, Shopify mağazasında bir olay gerçekleştiğinde (yeni sipariş, stok güncellemesi, ürün değişikliği) mağazanın harici bir sunucuya otomatik olarak HTTP isteği göndermesini sağlayan bildirim mekanizmasıdır. Sürekli API’yi sorgulamak (polling) yerine, olay gerçekleştiği anda bilgi akışı tetiklenir.

Bir ERP sisteminin her 5 dakikada bir “yeni sipariş var mı?” diye Admin API’ye sorgu atması hem rate limit’i tüketir hem de gecikme yaratır. Webhook bu modeli tersine çevirir: sipariş oluşturulduğu saniye Shopify, tanımlı endpoint’e orders/create bildirimini gönderir.

Quotable: Webhook, API’yi sorgulamak yerine Shopify’ın olayı haber vermesini sağlar; bu fark yüksek hacimli mağazalarda saatlik binlerce gereksiz API çağrısını ortadan kaldırır.

Webhook kurulumu, konu adı sabit topic listesi (orders/create, products/update, fulfillments/create gibi), HMAC imza doğrulama ve başarısız teslimat durumunda yeniden deneme (retry) mekanizması gibi kendine özgü teknik detaylar içerir. Bu adımların tamamı Shopify webhook kurulumu rehberinde adım adım anlatılır.

İpucu: Sipariş ve stok senkronizasyonu yapan her entegrasyonda polling yerine webhook tercih edilmeli. Shopify Help Center, webhook’un mağaza performansı üzerinde polling’e göre çok daha düşük yük yarattığını belirtir (Shopify Help Center, 2025).

Custom App Ne Zaman Gereklidir?

Custom app, Shopify App Store’daki hazır bir uygulamanın karşılamadığı özel bir iş kuralı veya sistem entegrasyonu olduğunda, mağazaya özel yazılan ve sadece o mağazada çalışan uygulama türüdür. Standart bir app’in desteklemediği alan (custom field), özel bir ERP protokolü veya benzersiz bir fiyatlandırma mantığı custom app gerektiren tipik senaryolardır.

Shopify, custom app’leri iki kategoriye ayırır: mağaza yöneticisinin doğrudan Admin panelinden oluşturduğu “custom app” ve Partner hesabı üzerinden geliştirilip dağıtılan “public/private app” (Shopify.dev, 2025). Tek mağaza için özel bir entegrasyon yapılacaksa Admin panelinden oluşturulan custom app yeterli olur; birden fazla mağazaya dağıtılacak bir çözüm için Partner hesabı gerekir.

Bir örnek vermek gerekirse, yerel bir kargo firmasının Shopify App Store’da hazır entegrasyonu yoksa ve firmanın kendi API’si üzerinden kargo etiketi oluşturulması gerekiyorsa, bu ihtiyaç sadece custom app ile karşılanabilir; hazır bir çözüm mevcut değildir.

Kritik Not: Custom app geliştirme kararı verilmeden önce Shopify App Store’da benzer bir çözüm olup olmadığı mutlaka araştırılmalı. Sıfırdan geliştirilen bir entegrasyonun bakım yükü, hazır bir app’in abonelik ücretinden çoğu zaman daha yüksektir.

Custom app geliştirme kararının en somut göstergesi, ihtiyacın üç veya daha fazla farklı sistemi (Shopify + ERP + pazaryeri gibi) aynı anda konuşturması gereken senaryolardır. Tek sistemli entegrasyonlarda hazır app’ler genelde yeterli kalır, ancak çoklu sistem senkronizasyonunda hazır app’lerin esneklik sınırı hızla aşılır.

Shopify API Entegrasyonunda Kimlik Doğrulama Nasıl Çalışır?

Shopify API’lerine erişim, uygulama türüne göre iki farklı kimlik doğrulama modeliyle çalışır: özel (custom) app’ler mağaza yöneticisinin ürettiği sabit bir Admin API access token kullanır, dağıtılan (public) app’ler ise OAuth 2.0 akışıyla her mağaza için ayrı yetkilendirme alır.

Custom app modelinde, mağaza sahibi Admin panelinden uygulamaya hangi kaynaklara erişebileceğini (scope) tek tek işaretler örneğin sadece read_orders ve write_inventory izni verilebilir, müşteri verisine erişim kapalı tutulabilir. Bu granüler izin yapısı, entegrasyonun sadece ihtiyacı olan veriye dokunmasını zorunlu kılar.

Quotable: Bir custom app’e verilen scope, o app’in erişebileceği verinin tavanını belirler; gereğinden geniş scope talebi güvenlik denetiminde ilk reddedilme nedenidir.

Public app modelinde OAuth akışı, mağaza sahibinin kurulum sırasında talep edilen scope listesini onaylamasıyla başlar ve Shopify bir access token üretip uygulamaya döner. Bu token, her API çağrısında X-Shopify-Access-Token header’ı ile gönderilir ve mağaza değiştiğinde yeniden üretilmesi gerekir.

Bu ayrım netleştiğinde, bir sonraki adım genelde hangi olayların hangi sıklıkla API’ye yük bindireceğini planlamaktır; özellikle stok ve sipariş senkronizasyonu yapan entegrasyonlarda bu planlama rate limit sorunlarını baştan önler.

Shopify Özel API Entegrasyonunda Hangi Riskler Göz Ardı Edilir?

En sık göz ardı edilen risk, API versiyonlama (versioning) takibinin yapılmamasıdır; Shopify API’lerini üç ayda bir yeni sürümle günceller ve eski sürümler yaklaşık 12 ay sonra devre dışı bırakılır (Shopify.dev, 2025). Sabit bir API sürümüne bağlı kalıp güncelleme takvimini izlemeyen entegrasyonlar, sürüm kaldırıldığında aniden çalışmaz hale gelir.

İkinci göz ardı edilen risk, hata yönetiminin (error handling) yalnızca “başarılı” senaryo üzerine kurulmasıdır. Bir stok güncelleme isteği rate limit nedeniyle reddedildiğinde, entegrasyon bu hatayı loglamıyorsa stok verisi sessizce eski kalır ve sorun günler sonra fark edilir.

Uzak Durulması Gereken Risk: API versiyon güncellemelerini takip etmeyen bir entegrasyon, Shopify’ın eski sürümü kapatmasıyla bir gecede durabilir. Her entegrasyonda API sürümünün takvimi ve geçiş planı belgelenmeli.

Üçüncü risk, tek bir API anahtarının birden fazla ortamda (test ve canlı) aynı anda kullanılmasıdır. Bir geliştiricinin test ortamında canlı mağaza token’ını kullanması, test sırasında gerçek müşteri verisinin değiştirilmesine yol açabilir bu hata özellikle çoklu geliştirici içeren ekiplerde tekrarlanır.

Headless Commerce Projelerinde API Mimarisi Nasıl Kurulur?

Headless commerce (ayrışık ticaret mimarisi), Shopify’ın checkout ve arka ofis altyapısını korurken, müşteri arayüzünü (vitrin) tamamen ayrı bir teknoloji ile kurma yöntemidir; bu mimaride Storefront API vitrin katmanını, Admin API ise arka ofis senkronizasyonunu üstlenir. İki API katmanı birbirinden bağımsız çalışır ama aynı mağaza verisine farklı açılardan erişir.

Bir markanın React veya Next.js ile özel bir vitrin kurup Shopify’ı sadece sipariş ve stok motoru olarak kullanması, headless mimarinin en yaygın uygulamasıdır. Bu senaryoda Storefront API ürün kataloğunu ve sepeti yönetirken, checkout adımı Shopify’ın kendi altyapısına devredilir Shopify Checkout Extensibility, checkout sayfasının tamamen özelleştirilmesine artık izin vermez, sadece belirli uzantı noktalarına (extension point) müdahaleye izin verir (Shopify.dev, 2025).

Quotable: Headless mimaride Shopify checkout sürecinin çekirdeği değiştirilemez; entegrasyon bu yüzden uzantı noktaları (extension points) üzerinden kurulmalıdır.

Headless projelerde en çok karşılaşılan yanlış varsayım, Storefront API’nin sipariş oluşturabileceği düşüncesidir. Storefront API sepet oluşturma ve checkout URL’i üretmeye kadar giden süreci yönetir, ancak siparişin kesinleşmesi Shopify’ın kendi checkout akışında gerçekleşir. Bu sınırı bilmeyen ekipler, projenin ortasında mimariyi yeniden kurmak zorunda kalır.

Headless kararı, çoğu mağaza için gereksiz bir karmaşıklık yaratır; klasik Shopify teması SEO ve performans açısından yeterli sonuç verdiğinde headless mimariye geçmek geliştirme süresini aylarla uzatabilir. Bu kararı yalnızca çoklu marka, çoklu platform (web + mobil uygulama + IoT ekran) gibi somut bir ihtiyaç varsa değerlendirmek gerekir.

Entegrasyon Devreye Alınmadan Önce Hangi Testler Yapılmalı?

Bir custom app veya API entegrasyonu canlı mağazaya bağlanmadan önce, sandbox ortamında (Shopify’ın development store’u) uçtan uca test edilmelidir; bu adım atlandığında hatalar gerçek sipariş verisi üzerinde ortaya çıkar. Shopify Partner hesabı, sınırsız sayıda development store oluşturmaya izin verir ve bu mağazalar gerçek ödeme almadan tüm API akışını simüle eder.

Test sürecinin ilk adımı, webhook ve API çağrılarının beklenen veri formatını doğru işleyip işlemediğini kontrol etmektir. İkinci adım, hata senaryolarının (rate limit reddi, geçersiz token, eksik zorunlu alan) uygulamayı çökertmeden yönetilip yönetilmediğini test etmektir. Üçüncü adım ise, yüksek hacim simülasyonu yaparak entegrasyonun kampanya dönemi gibi yoğun trafik altında nasıl davrandığını gözlemlemektir.

1. Development store üzerinde uygulamayı kurup temel senaryoları (sipariş oluşturma, stok güncelleme) test edin.
2. Kasıtlı olarak hatalı veri gönderip uygulamanın hata mesajını doğru loglayıp loglamadığını doğrulayın.
3. Webhook teslimatını Shopify Admin panelindeki “Notifications” günlüğünden takip ederek başarısız denemeleri inceleyin.
4. Rate limit sınırına yakın bir yük testiyle uygulamanın Retry-After header’ını doğru işlediğini kontrol edin.
5. Sandbox testleri tamamlandıktan sonra canlı mağazada düşük hacimli bir pilot dönem çalıştırın.

İpucu: Pilot dönemde entegrasyonun ürettiği tüm hataları ayrı bir log kanalında toplamak, canlıya tam geçiş öncesi sorunları erken yakalamanın en pratik yoludur.

Bu test disiplini, özellikle birden fazla dış sistemi aynı anda konuşturan entegrasyonlarda kritik hale gelir; çünkü hata kaynağı Shopify tarafında mı, ERP tarafında mı yoksa ağ katmanında mı olduğu ayırt edilmesi gereken bir problem haline gelir.

Shopify Flow ile Özel API Entegrasyonu Arasında Ne Zaman Seçim Yapılır?

Shopify Flow, kod yazmadan koşul-eylem (if-then) mantığıyla otomasyon kuran Shopify’ın kendi araçlarındandır ve basit senaryolarda özel API geliştirmesinin yerini alabilir. Stok belirli bir seviyenin altına düştüğünde etiketleme yapmak veya yüksek riskli bir siparişi otomatik etiketlemek gibi tek adımlı kurallar Flow ile dakikalar içinde kurulabilir.

Flow’un sınırı, üçüncü parti bir sisteme (ERP, muhasebe yazılımı, özel bir pazaryeri) veri göndermesi gerektiğinde ortaya çıkar; Flow yalnızca Shopify ekosistemi içindeki uygulamalarla ve sınırlı sayıda harici webhook eylemiyle çalışır. Karmaşık veri dönüşümü (örneğin ERP’nin beklediği XML formatına Shopify JSON verisini çevirmek) Flow’un yetenek sınırının dışındadır.

Kritik Not: Bir otomasyon ihtiyacı Shopify Flow’un hazır eylem listesiyle karşılanabiliyorsa, custom app geliştirmek gereksiz bir bakım yükü yaratır. Flow’un yetmediği nokta net biçimde tanımlanmadan API geliştirmeye başlamak, kapsamın gereksiz büyümesine yol açar.

Bir örnek vermek gerekirse, “sipariş tutarı 5.000 TL üzerindeyse siparişi manuel onay etiketiyle işaretle” kuralı Flow ile kod yazılmadan kurulur. Ama “sipariş oluştuğunda muhasebe yazılımına fatura kesme isteği gönder” ihtiyacı, muhasebe sisteminin kendine özgü API formatı nedeniyle çoğunlukla custom app veya hazır bir entegrasyon uygulaması gerektirir.

Sık Sorulan Sorular

Shopify özel API entegrasyonu için kod yazmak zorunlu mu? Evet, custom app veya API tabanlı entegrasyon, hazır bir Shopify App Store uygulamasının karşılamadığı ihtiyaç için yazılım geliştirme gerektirir. Basit senaryolarda no-code araçlar bazı API çağrılarını görsel arayüzle kurabilir, ancak karmaşık iş kuralları için kod yazımı kaçınılmazdır.

Admin API ile Storefront API’yi aynı projede birlikte kullanmak mümkün mü? Evet, birçok headless proje Storefront API’yi vitrin için, Admin API’yi ise sipariş ve stok işlemleri için aynı anda kullanır. İkisi farklı token ve scope ile çalıştığı için birbirini engellemez.

Shopify API entegrasyonu ne kadar sürede tamamlanır? Tek kaynaklı basit bir entegrasyon (örneğin sadece sipariş okuma) birkaç gün içinde tamamlanabilir. Çoklu sistem senkronizasyonu (ERP + pazaryeri + Shopify) gerektiren projeler birkaç haftaya kadar uzayabilir.

GraphQL Admin API’ye geçmek zorunlu mu? Şu an için hayır, REST Admin API desteklenmeye devam ediyor. Ancak Shopify yeni özellikleri öncelikli olarak GraphQL tarafında yayınladığı için uzun vadeli projelerde GraphQL tercih edilmeli.

Shopify API rate limit’e takılırsam ne olur? İstek reddedilir ve Shopify 429 durum kodu ile Retry-After header’ı döner. Bu durumun teknik detayları ve çözüm yöntemleri ayrı bir rehberde ele alınır.

Bir Shopify uygulaması birden fazla mağazada nasıl çalışır? Partner hesabı üzerinden geliştirilen public app, her mağaza kurulumunda ayrı bir OAuth yetkilendirmesi alır ve her mağaza için ayrı access token üretir. Tek bir kod tabanı, farklı token’larla birden fazla mağazaya hizmet verebilir.

Sonraki Adım

Bu rehber, Shopify’ın API katmanlarını ve custom app kararını genel hatlarıyla çizdi. Bir sonraki adım, hangi API’yi kullanacağına karar verdikten sonra veri akışını gerçek zamanlı tutacak webhook mekanizmasını kurmaktır bu adımlar Shopify webhook kurulumu rehberinde ayrıntılı işlenir. Yüksek hacimli mağazalarda ise API çağrı stratejisi planlanırken Shopify API rate limit ve stok senkronizasyon hataları rehberi, karşılaşılabilecek darboğazları önceden gösterir.