title: "Shopify API Entegrasyon Kılavuzu: 2026'da Özel Ticaret Çözümleri Oluşturma" açıklama: "Yönetici API'si, Storefront API'si, web kancaları, kimlik doğrulama, ücret sınırları ve özel uygulamalar oluşturmayı kapsayan Shopify API entegrasyonuna ilişkin kapsamlı kılavuz." tarih: "2026-03-05" yazar: "ECOSIRE Araştırma ve Geliştirme Ekibi" Etiketler: ["shopify", "api entegrasyonu", "graphql", "webhooks", "özel geliştirme"]

Shopify API Entegrasyon Kılavuzu: 2026'da Özel Ticaret Çözümleri Oluşturma

Shopify, dünya çapında dört milyondan fazla çevrimiçi mağazaya güç veriyor ve platformun gerçek potansiyeli, güçlü API paketi aracılığıyla ortaya çıkıyor. İster envanteri bir ERP sistemiyle senkronize ediyor olun, ister başsız bir vitrin oluşturuyor olun, ister Shopify App Store için genel bir uygulama oluşturuyor olun, API ortamını anlamak çok önemlidir. Bu kılavuz, ECOSIRE mühendislerinin müşteri projelerine uyguladığı kimlik doğrulama, hız limitleri, webhook mimarisi ve üretime hazır kalıpları kapsayan Shopify API entegrasyonuna ilişkin kapsamlı, teknik bir genel bakış sağlar.

Temel Çıkarımlar

Shopify dört ana API sunar (Yönetici, Vitrin, İş Ortağı ve Ödeme Uygulamaları) ve her biri farklı kimlik doğrulama modelleriyle farklı kullanım örnekleri sunar.
GraphQL stratejik yöndür. Shopify, REST uç noktalarını aşamalı olarak kullanımdan kaldırıyor; yeni özellikler yalnızca GraphQL'de mevcuttur. Entegrasyonunuzu buna göre planlayın.
**GDPR uyumluluğu ve harici sistemleri yoklama olmadan senkronize tutmak için Webhook mimarisi zorunludur.
**Oran sınırlaması, REST için sızdıran kova modelini ve GraphQL için maliyete dayalı puan sistemini izler. Her ikisi de kasıtlı yeniden deneme ve geri çekilme stratejileri gerektirir.
Her web kancasında ve OAuth geri aramasında HMAC doğrulaması tartışılamaz. İmza doğrulamanın atlanması, uygulamanızın sahte yüklere ve veri tahrifatına maruz kalmasına neden olur.

Shopify API Ortamı

Shopify, her biri belirli bir hedef kitle ve entegrasyon modeli için tasarlanmış birden fazla API sunar.

| API'si | Amaç | Yetkilendirme Modeli | Tipik Tüketici | |-----|---------|-----------|------| | Yönetici API'si | Tam mağaza yönetimi (ürünler, siparişler, müşteriler, yerine getirme) | OAuth 2.0 / Özel uygulama kimlik bilgileri | Arka ofis entegrasyonları, ERP bağlayıcıları, özel yönetici araçları | | Storefront API | Müşteriyle yüz yüze ticaret (sepet, ödeme, ürün sorguları) | Vitrin erişim belirteci (genel) | Başsız ön uçlar, mobil uygulamalar, satın alma düğmeleri | | İş Ortağı API'si | İş ortağı ekosisteminde uygulama ve mağaza yönetimi | İş Ortağı API jetonu | Acente gösterge tabloları, çok mağazalı aletler | | Ödeme Uygulamaları API'sı | Özel ödeme ağ geçidi entegrasyonu | Ödeme kapsamına sahip uygulama düzeyinde OAuth | Ödeme sağlayıcıları, alternatif ödeme yöntemleri |

Çoğu özel ticaret çözümü için Admin API ve Storefront API gereksinimlerin yüzde doksanını karşılar. Admin API, sunucu tarafı işlemleri için en güçlü yardımcınızdır; Storefront API ise ürün verilerine, sepet yönetimine veya ödeme başlatmaya ihtiyaç duyduğunuz her türlü müşteriye yönelik deneyimi destekler.

Özel bir Shopify entegrasyonu oluşturup oluşturmayacağınızı değerlendiriyorsanız ekibimiz projenin kapsamını belirlemenize yardımcı olabilir. Shopify uygulama geliştirme hizmetlerimiz hakkında daha fazla bilgi edinin.

GraphQL ve REST

Shopify, Admin API için hem GraphQL hem de REST uç noktalarını korur ancak gidişat açıktır: GraphQL gelecektir. 2023'ten beri tüm yeni Admin API özellikleri GraphQL'e özeldir.

Karşılaştırma

| Boyut | DİNLENME | GraphQL | |-----------|------|-----------| | Veri getiriliyor | Sabit yanıt şekli; aşırı getirme ortak | Tam olarak ihtiyacınız olan alanları isteyin | | İç içe geçmiş kaynaklar | Çoklu gidiş-dönüş talepleri | İç içe seçimlerle tek sorgu | | Hız sınırlama | 40 istek/saniye (sızdıran kova) | 1.000 maliyet puanı/saniye (sorgu başına hesaplanır) | | Sayfalandırma | Bağlantı başlığı tabanlı imleç sayfalandırması | pageInfo ile geçiş stili imleç sayfalandırması | | Toplu işlemler | Mevcut değil | bulkOperationRunQuery aracılığıyla yerel toplu sorgulama ve mutasyon desteği | | Yeni özellikler | Dondurulmuş; yeni uç nokta yok | Tüm yeni yetenekler ilk önce buraya geliyor | | Web kancaları | Desteklenen | webhookSubscriptionCreate mutasyonu aracılığıyla abonelik tabanlı web kancaları |

Hangisi Ne Zaman Kullanılmalı

Basit, tek kaynaklı bir işleminiz olduğunda (örneğin, tek bir sipariş durumunu kontrol ederken) REST kullanın ve mevcut kod tabanınız zaten REST istemci altyapısına sahip. Diğer her şey için GraphQL kullanın, özellikle de iç içe geçmiş verilere (satır öğeleri, ürünler ve sipariş karşılama durumu ile tek çağrıda sipariş verme), toplu dışa aktarmalara veya meta nesneler ve işlevler gibi daha yeni platform özelliklerine erişime ihtiyaç duyduğunuzda.

Geçiş Yolu

Entegrasyonunuz şu anda REST'e dayanıyorsa öncelikle yüksek hacimli uç noktaları taşımaya öncelik verin. Toplu veri aktarımları, ürün kataloğu sorguları ve sipariş listesi işlemleri, GraphQL'e taşındığında en büyük performans kazanımlarını sağlar. Shopify'ın bulkOperationRunQuery mutasyonu, milyonlarca kaydı eşzamansız olarak dışa aktarabilir ve aksi takdirde yüzlerce sayfalandırılmış REST çağrısı gerektirecek olanların yerine geçebilir.

Kimlik Doğrulama ve Yetkilendirme

Shopify supports multiple authentication flows depending on the app type and deployment model.

OAuth 2.0 (Genel ve Özel Uygulamalar)

Satıcılar tarafından yüklenen Shopify uygulamalarına yönelik standart akış:

Satıcı, yüklemeyi Shopify App Store'dan veya doğrudan yükleme bağlantısından başlatır.
Uygulamanız client_id, istenen scopes ve redirect_uri ile https://{shop}.myshopify.com/admin/oauth/authorize adresine yönlendirme yapıyor.
İşyeri talep edilen kapsamları onaylar.
Shopify, geçici bir code ile geri yönlendirme yapar.
Sunucunuz, kodu POST /admin/oauth/access_token aracılığıyla kalıcı bir access_token ile değiştirir.

Erişim Kapsamları

Gerekli minimum kapsamları isteyin. Shopify'ın herkese açık uygulamalara yönelik kapsam isteklerini incelemesi ve aşırı kapsam istekleri, yaygın bir ret nedenidir.

| Kapsam | Erişim | |-------|--------| | KOD0 / KOD1 | Ürün kataloğu | | KOD0 / KOD1 | Sipariş yönetimi | | KOD0 / KOD1 | Müşteri kayıtları | | KOD0 / KOD1 | Envanter seviyeleri ve yerleri | | KOD0 / KOD1 | Yerine getirme ve takip |

Oturum Belirteçleri (Gömülü Uygulamalar)

Shopify Admin'e gömülü uygulamalar için oturum jetonları çerezlerin yerini alır. Shopify App Bridge kitaplığı, arka ucunuzun uygulamanızın API sırrını kullanarak doğruladığı bir JWT yayınlar. Bu, üçüncü taraf tanımlama bilgisi sorunlarını ortadan kaldırır ve yerleşik deneyimler için kimlik doğrulama akışını basitleştirir.

API Anahtarı Kimlik Doğrulaması (Özel/Özel Uygulamalar)

OAuth gerektirmeyen tek mağaza entegrasyonları için doğrudan Shopify Yöneticisi'nde oluşturulan özel uygulamalar, yönlendirme akışı olmadan bir erişim jetonu sağlar. Bu, dahili araçlar ve özel entegrasyonlar için en basit yoldur.

Web Kancası Mimarisi

Değişiklikler için API'lerin yoklanması israftır ve yavaştır. Shopify web kancaları, etkinlikleri neredeyse gerçek zamanlı olarak uygulamanıza aktarır.

Olay Odaklı Entegrasyon

Entegrasyonunuzun önemsediği etkinlikler için web kancalarını kaydedin. Ortak abonelikler şunları içerir:

orders/create, orders/updated, orders/paid -- Yerine getirme iş akışlarını, ERP senkronizasyonunu veya bildirim ardışık düzenlerini tetikleyin.
products/update, products/delete -- Harici katalogları veya arama dizinlerini güncel tutun.
inventory_levels/update -- Kanallar ve depolar arasında stoğu senkronize edin.
app/uninstalled -- Satıcı verilerini temizleyin ve saklanan kimlik bilgilerini iptal edin.

Zorunlu GDPR Web Kancaları

Shopify, tüm uygulamaların GDPR ile ilgili üç web kancasını işlemesini gerektirir:

customers/data_request -- Belirli bir müşteri için depolanan tüm verilerle yanıt verin.
customers/redact -- Belirli bir müşteri için depolanan tüm verileri silin.
shop/redact -- Uygulamanızı kaldıran bir mağazaya ait depolanan tüm verileri silin.

Bu uç noktaların uygulanmaması, uygulamanızın Shopify App Store tarafından onaylanmasını engelleyecektir.

Teslimat Garantileri ve Bağımsızlık

Shopify en az bir kez teslimatı garanti eder. Web kancası işleyiciniz bağımsız olmalıdır; aynı web kancası yükünü iki kez işlemek aynı sonucu üretmelidir. Tekilleştirme anahtarı olarak X-Shopify-Webhook-Id başlığını kullanın. İşlenen webhook kimliklerini saklayın ve kopyaları atlayın.

Uç noktanız 2xx olmayan bir durum kodu döndürürse Shopify, aboneliği kaldırmadan önce 48 saate kadar üstel geri çekilmeyle yeniden dener.

Hız Sınırları ve Azaltma

Hız sınırlarını anlamak, kritik işlemler sırasında entegrasyonunuzun kısıtlanmasını önler.

REST: Sızdıran Kova

REST Yönetici API'si, 40 istek kapasitesine ve saniyede 2 istek sızıntı oranına sahip bir sızdıran paket algoritması kullanır. Her yanıt X-Shopify-Shop-Api-Call-Limit (ör. 32/40) içerir, böylece kova dolum seviyesini gerçek zamanlı olarak izleyebilirsiniz.

GraphQL: Maliyete Dayalı Azaltma

GraphQL sorguları, sorgu karmaşıklığına bağlı olarak "maliyet puanları" tüketir. Maksimum 2.000 kova ile saniyede 1.000 puan alırsınız. Her yanıt, currentlyAvailable, maximumAvailable ve restoreRate alanlarını içeren bir throttleStatus uzantısı içerir. Basit bir tek nesne sorgusu 1-2 puana mal olabilir; iç içe bağlantıları olan 250 öğe talep eden sayfalandırılmış bir liste sorgusu 500'den fazla puana mal olabilir.

Stratejileri Yeniden Deneyin

Bir 429 Too Many Requests (REST) veya THROTTLED hatası (GraphQL) aldığınızda titreşimle üstel geri çekilme uygulayın. Önerilen bir model:

Gaz tepkisi geldiğinde base_delay * 2^attempt + random_jitter bekleyin.
500 ms'lik temel gecikmeyle başlayın.
Maksimum yeniden deneme gecikmesini 30 saniyede sınırlayın.
Art arda 5 arızadan sonra hatayı kaydedin ve operasyon ekibinizi uyarın.

Toplu veri işlemleri için, sayfalandırılmış sorgular yerine her zaman GraphQL toplu işlemlerini tercih edin. Shopify'ın altyapısı üzerinde eşzamansız olarak çalışırlar ve aynı oran sınırlarına tabi değildirler.

Ortak Entegrasyon Modelleri

ERP Senkronizasyonu

En yaygın kurumsal entegrasyon, Shopify'ı çift yönlü veri akışı için Odoo gibi bir ERP sistemine bağlar. Shopify'da oluşturulan siparişler, yerine getirilmesi için ERP'ye yayılır ve ERP'deki envanter güncellemeleri, neredeyse gerçek zamanlı olarak Shopify'a geri yansıtılır.

ECOSIRE tam olarak bu modelde uzmanlaşmıştır. Odoo entegrasyon hizmetlerimiz Shopify için sipariş senkronizasyonu, envanter yönetimi, müşteri veri eşleme ve finansal mutabakat işlemlerini gerçekleştiren önceden oluşturulmuş bağlayıcılar içerir.

Envanter Yönetimi

Çok konumlu envanter dikkatli bir düzenleme gerektirir. Stok seviyelerini güncellemek için inventorySetQuantities GraphQL mutasyonunu (kullanımdan kaldırılan REST envanter ayarlama uç noktalarının yerine) kullanın. Subscribe to inventory_levels/update webhooks to detect changes made through other channels or directly in the Shopify Admin.

Sipariş Yönlendirme

Birden fazla deposu veya sipariş karşılama ortağı olan satıcılar için envanter kullanılabilirliğini, gönderim yakınlığını ve gönderim maliyetini değerlendiren sipariş yönlendirme mantığını uygulayın. Shopify'ın Sipariş Gönderimi API'si, sipariş karşılama sorumluluğunu belirli konumlara veya üçüncü taraf hizmetlerine atamak için gerekli temelleri sağlar.

Müşteri Veri Senkronizasyonu

Müşteri kayıtlarının Shopify ile harici CRM veya pazarlama platformları arasında senkronize edilmesi, birleştirme çakışmalarının, izin durumunun ve veri formatı farklılıklarının ele alınmasını gerektirir. Tetikleyici olarak customers/update web kancasını kullanın ve bir çatışma çözümleme stratejisi uygulayın (örneğin, zaman damgası karşılaştırmasıyla son yazılanlar kazanır veya doğruluk kaynağı ataması).

Özel Shopify Uygulamaları Oluşturma

Genel ve Özel Uygulamalar

| Özellik | Herkese Açık Uygulama | Özel Uygulama | |-----------|---------------|------------| | Dağıtım | Shopify Uygulama Mağazası | Tek mağaza veya Shopify Plus organizasyonu | | İnceleme süreci | Zorunlu Shopify incelemesi | Yok | | OAuth akışı | Gerekli | İsteğe bağlı (doğrudan belirteç) | | Faturalandırma | Shopify Faturalandırma API'sı | Doğrudan faturalandırma | | GDPR web kancaları | Gerekli | Gerekli |

Uygulama Uzantıları

Shopify'ın yalnızca uzantılardan oluşan uygulama mimarisi (2024'te tanıtıldı ve artık standart), doğrudan Shopify Yöneticisi, ödeme ve vitrin içinde oluşturulan kullanıcı arayüzü uzantılarının oluşturulmasını teşvik ediyor. Uzantılar, Shopify'ın kullanıcı arayüzü bileşen kitaplığıyla oluşturulur ve uygulamanızın bir parçası olarak dağıtılır.

Anahtar uzatma yüzeyleri şunları içerir:

Shopify Yöneticisi içindeki özel iş akışları için Yönetici eylemi ve engelleme uzantıları.
Ödeme sırasında özel alanlar, ek satışlar veya bağlılık programı entegrasyonları eklemek için Ödeme kullanıcı arayüzü uzantıları.
Sıvı kod değişiklikleri olmadan Online Mağaza temalarına uygulama işlevselliği eklemek için Tema uygulama uzantıları.
Shopify'ın altyapısında yürütülen sunucu tarafı mantığına (indirimler, kargo ücretleri, ödeme özelleştirme) yönelik işlev uzantıları.

Shopify CLI

Shopify CLI (@shopify/cli), uygulama iskelesi, yerel geliştirme ve dağıtım için standart geliştirme aracıdır. Çalışırken yeniden yükleme, otomatik ngrok tünelleme ve OAuth'un otomatik olarak işlenmesiyle yerel bir geliştirme sunucusunu başlatmak için shopify app dev komutunu çalıştırın. Remix'i (varsayılan uygulama çerçevesi), Node.js, PHP ve Ruby arka uçlarını destekler.

Shopify geliştirmeye başlayan ekipler için mağaza kurulum hizmetlerimiz geliştirme ortamı yapılandırmasını ve mimari planlamayı içerir.

Test Etme ve Hata Ayıklama

Shopify CLI ile Yerel Kalkınma

shopify app dev uygulamanızı yerel olarak başlatır ve güvenli bir tünel oluşturur. OAuth yönlendirmesini otomatik olarak yönetir, böylece manuel ngrok yapılandırmasına gerek kalmadan tüm yükleme akışını bir geliştirme mağazasına karşı test edebilirsiniz.

Web Kancası Testi

Test webhook verilerini yerel uç noktanıza göndermek için shopify app webhook trigger kullanın. Bu, gerçek işlemler oluşturmadan GDPR web kancalarını ve uç durumları (ör. kısmen yerine getirilen siparişler, geri ödemeler) test etmek için çok değerlidir.

Geliştirme Mağazaları

Shopify İş Ortağı hesabınız aracılığıyla sınırsız geliştirme mağazaları oluşturun. Bu mağazaların test amacıyla tüm Shopify özelliklerine (Plus özellikleri dahil) erişimi vardır. Shopify CLI'nin shopify populate komutlarını veya Faker tabanlı tohum komut dosyalarını kullanarak test verilerini doldurun.

GraphQL Gezgini

Shopify Admin GraphQL Explorer (Admin API belgelerinden erişilebilir), sorguları gerçek bir mağazaya karşı etkileşimli olarak oluşturmanıza ve test etmenize olanak tanır. Sorguları kodda uygulamadan önce prototip oluşturmak için bunu kullanın.

Günlüğe Kaydetme ve Gözlemlenebilirlik

Üretimde, hatalar veya beklenmeyen durum kodları döndüren tüm API yanıtlarını günlüğe kaydedin. Her yanıttaki oran sınırı başlıklarını takip edin ve bunları izleme sisteminizde ölçüm olarak gösterin. Entegrasyonunuzun optimizasyona ihtiyaç duyduğunu gösteren sürekli kısıtlama için uyarılar ayarlayın.

En İyi Güvenlik Uygulamaları

HMAC Doğrulaması

Shopify'daki her webhook yükü bir X-Shopify-Hmac-SHA256 başlığı içerir. Uygulamanızın API sırrını kullanarak ham istek gövdesinin HMAC-SHA256'sını hesaplayın ve bunu zamanlama açısından güvenli bir karşılaştırma işlevi kullanarak başlık değeriyle karşılaştırın. Geliştirme aşamasında bile bu adımı asla atlamayın.

OAuth Geri Arama Doğrulaması

OAuth geri aramalarında hmac sorgu parametresini doğrulayın. Sorgu dizesini yeniden oluşturun (hmac parametresi hariç), HMAC'yi hesaplayın ve karşılaştırın. Ayrıca CSRF saldırılarını önlemek için state parametresinin OAuth akışının başlangıcında oluşturduğunuz nonce ile eşleştiğini doğrulayın.

API Kimlik Bilgisi Rotasyonu

API kimlik bilgilerini düzenli aralıklarla döndürün. Özel uygulamalar için Shopify Yöneticisi aracılığıyla erişim jetonlarını yeniden oluşturun. OAuth'lu genel uygulamalar için erişim belirteçleri kalıcıdır ancak kapsamı sınırlıdır; bir belirtecin ele geçirildiğinden şüpheleniyorsanız uygulamayı kaldırıp yeniden yükleyerek bunu iptal edin.

Kapsam Minimizasyonu

Request only the access scopes your app actually needs. read yeterli olduğunda write erişimi istemekten kaçının. Shopify'ın uygulama inceleme ekibi kapsam isteklerini inceler ve kapsamı aşırı olan uygulamalar reddedilir veya ek inceleme döngüleriyle karşı karşıya kalır.

Veri İşleme

Ham kredi kartı verilerini asla saklamayın. Shopify, ödeme için PCI uyumluluğunu yönetir ve entegrasyonunuzun hiçbir zaman ödeme kartı numaralarına doğrudan erişime ihtiyacı olmamalıdır. Müşteri PII'sı için, kullanımda olmayan verileri şifreleyin, erişim kontrollerini uygulayın ve GDPR veri silme taleplerini derhal yerine getirin.

Sıkça Sorulan Sorular

Yönetici API'si ile Vitrin API'si arasındaki fark nedir?

Admin API, mağaza verilerine (ürünler, siparişler, müşteriler, sipariş karşılama) tam arka ofis erişimi sağlar ve belirli kapsamlarla kimliği doğrulanmış erişim gerektirir. Storefront API, müşteriye yönelik deneyimler için tasarlanmıştır ve istemci tarafı koduna güvenli bir şekilde eklenebilecek genel erişim belirtecini kullanarak sınırlı, okuma ağırlıklı bir veri kümesini (ürünler, koleksiyonlar, alışveriş sepeti, ödeme) kullanıma sunar.

Hem REST hem de GraphQL'i aynı entegrasyonda kullanabilir miyim?

Evet. Birçok üretim entegrasyonu, özellikle geçiş sırasında her ikisini de kullanır. However, be aware that REST and GraphQL rate limits are tracked separately, and some operations (like bulk exports) are only available via GraphQL. Uzun vadeli sürdürülebilirlik için GraphQL'i birleştirmeyi planlayın.

Shopify API sürümlendirmesini nasıl hallederim?

Shopify üç ayda bir yeni bir API sürümü yayınlar (ör. 2026-01, 2026-04). Her sürüm yaklaşık 12 ay boyunca desteklenir. Entegrasyonunuzu API URL'sindeki belirli bir sürüme (ör. /admin/api/2026-01/graphql.json) sabitleyin ve eski sürümler kullanımdan kaldırılmadan önce yeni sürümleri benimsemek için üç ayda bir yapılan incelemeler planlayın.

Webhook uç noktam çökerse ne olur?

Shopify, başarısız webhook teslimatlarını 48 saate kadar üstel geri çekilmeyle yeniden dener. Tüm yeniden denemeler başarısız olursa webhook aboneliği otomatik olarak kaldırılır. Uygulamanız, webhook aboneliklerinin etkin olduğunu düzenli aralıklarla doğrulamalı ve kaldırılanları yeniden kaydetmelidir. Kayıtlı web kancalarını beklenen aboneliklerle karşılaştıran bir durum denetimi uygulayın.

API erişimi için Shopify Plus planına ihtiyacım var mı?

Hayır. Tüm Shopify planları (Temel dahil) API erişimi sağlar. Ancak SSO için Çoklu Geçiş API'si, bazı ödeme özelleştirme özellikleri ve daha yüksek API ücret limitleri gibi belirli özellikler Shopify Plus'a özeldir.

ECOSIRE ile Shopify Entegrasyonunuzu Oluşturun

İster hafif bir web kancası entegrasyonuna, tam bir ERP bağlayıcıya veya Shopify App Store için özel bir genel uygulamaya ihtiyacınız olsun, ECOSIRE'ın mühendislik ekibi üretim düzeyinde çözümler sunma uzmanlığına sahiptir. Perakende, üretim ve toptan dağıtım da dahil olmak üzere sektörler genelinde Shopify entegrasyonlarını oluşturduk ve sürdürdük.

Shopify entegrasyon gereksinimlerinizi görüşmek ve ayrıntılı bir teknik teklif almak için ECOSIRE ile iletişime geçin.