Shopify Custom App Geliştirme: API Token Alma ve Entegrasyon Rehberi

Shopify custom app, yalnızca tek bir mağaza için geliştirilen, Shopify App Store'da yayımlanmayan ve mağaza yöneticisinin doğrudan kurduğu özel bir uygulamadır. ERP sistemleri, muhasebe yazılımları veya lojistik platformlarıyla yapılan birebir entegrasyonlarda tercih edilen bu yapı, standart public app geliştirmesinden farklı bir token alma ve yetkilendirme süreci gerektirir.

Bu rehber, hem kendi mağazanız için custom app geliştirmek isteyen geliştiricilere hem de Shopify'la entegre çalışacak bir SaaS veya kurumsal sistemi bağlamak isteyen teknik ekiplere yöneliktir.

Shopify Custom App Nedir?

Shopify custom app, belirli bir mağazanın özel ihtiyaçları için sıfırdan yazılmış, yalnızca o mağazaya yüklenen ve Shopify'ın public app altyapısını (App Store, OAuth yetkilendirme akışı) kullanmayan bir uygulama türüdür. Admin API veya Storefront API'ya programatik erişim sağlar.

Üç Shopify uygulama türünü birbirine karıştırmak çok yaygın bir hata. Hangi yapıyı, hangi senaryoda kullanmanız gerektiğini aşağıdaki tablo netleştiriyor:

Custom app'in ideal olduğu durumlar: ERP (SAP, Netsis, Logo) entegrasyonu, özel lojistik/kargo sistemi bağlantısı, dahili otomasyon iş akışları ve ticaret platformları arası veri senkronizasyonu.

Private App'ten Custom App'e: Shopify'ın 2023 Değişikliği

Shopify, Ocak 2023'te private app sistemini tamamen devre dışı bıraktı. Bu tarihten önce mağaza admini, API Key ve API Secret üreterek doğrudan erişim sağlayabiliyordu. Yeni sistemde bu yol kapandı.

Kritik Not: Eğer hâlâ eski private app credential'larını kullanan bir entegrasyonunuz varsa, Shopify bu bağlantıyı kalıcı olarak kesiyor. Custom app'e geçmek zorunlu.

Neden bu değişikliği yaptı? Güvenlik açısından eski private app sistemi, API key'lerin yönetilmesinde ciddi riskler taşıyordu: key rotasyonu yoktu, scope kontrolü gevşekti ve credential sızıntılarında tespit mekanizması bulunmuyordu. Yeni custom app sistemi HMAC doğrulama, scope sınırlandırma ve token izleme özellikleriyle bu açıkları kapattı.

Değişikliğin getirdiği teknik farklılıklar:

• Eski: API Key + API Secret ile doğrudan istek. Yeni: OAuth 2.0 ile alınan access_token
• Eski: X-Shopify-Access-Token header'ında API Password. Yeni: OAuth token aynı header'da
• Eski: Token zaman aşımı yok. Yeni: Offline token kalıcı, Online token 24 saat

Shopify Custom App Token Türleri

Shopify custom app geliştirmede iki farklı API yüzeyi ve buna bağlı iki farklı token türü var.

Kurumsal entegrasyonların büyük çoğunluğunda Admin API access token gerekir. Storefront API, müşteriye dönük yüz geliştirmelerinde (headless commerce, mobil uygulama) kullanılır ve Admin API'ya erişim sağlamaz.

Offline vs Online Token Farkı:

Offline token arka plan işlemleri, cronjob'lar ve sunucudan sunucuya entegrasyonlar için. Uygulama mağazadan kaldırılmadığı sürece geçerliliğini korur. Online token kullanıcı oturumu gerektiren akışlar için, 24 saat sonra sona erer.

İpucu: ERP veya muhasebe entegrasyonu yazıyorsanız her zaman offline token kullanın. Online token ile gece yarısı çalışan bir senkronizasyon işlemi, token'ın süresi dolduğunda sessizce başarısız olur.

Yeni Custom App Sistemi Neden Karmaşık?

Nodus Works olarak, hem 3rd party SaaS platformlarıyla hem de kurumsal ERP ekipleriyle çalışırken karşı ekipten en sık duyduğumuz sorun şu: "Shopify token'ı nasıl alacağız?"

Shopify'ın yeni custom app sistemi, makul sebeplerle güvenli olacak şekilde tasarlandı ancak bu tasarım beraberinde ciddi bir kurulum karmaşıklığı getirdi. Özellikle Shopify ekosistemiyle ilk kez çalışan bir backend veya entegrasyon ekibi için süreç belirsiz.

Karmaşıklığın kaynakları:

1. İki farklı token alma yolu. Custom app, hem Shopify admin panelinden direkt olarak hem de Partner Dashboard üzerinden OAuth akışıyla kurulabilir. İkisi farklı token alma prosedürleri gerektirir. Hangi yolu kullanacağınızı bilmeden başlarsanız yarım kalmış kurulumla saatlerce uğraşabilirsiniz.

2. Partner Dashboard konfigürasyonu. OAuth yolunu tercih ediyorsanız Partner Dashboard'da uygulama oluşturmanız, callback URL'leri tanımlamanız ve scope'ları belirtmeniz gerekiyor. Bu adımların herhangi birinde bir hata, invalid_client veya redirect_uri_mismatch hatalarına yol açıyor.

3. Scope yönetimi. İstenen scope'lar hem .env veya konfigürasyon dosyasında hem de Partner Dashboard'da birebir eşleşmeli. Küçük bir farklılık tokeni geçersiz kılıyor.

4. HMAC doğrulama. Shopify, callback'te dönen parametreleri kendi ürettiği imzayla doğrulamanızı bekliyor. Bu adımı atlamak güvenlik açığı yaratır; bunu uygulamamak ise production'da hata verir.

Shopify Admin API Token Alma: İki Yöntem

Yöntem 1: Mağaza Admin Panelinden Direkt Token

Bu yöntem, yalnızca kendi mağazanız için token alıyorsanız ve mağazaya admin erişiminiz varsa geçerlidir.

Adımlar:

1. Shopify admin'e giriş yapın → Ayarlar → Uygulamalar ve satış kanalları
2. Uygulamaları yönet sayfasına gidin → Uygulama geliştir seçeneğini tıklayın
3. Uygulama oluştur → uygulama adı girin → oluştur
4. API kimlik bilgileri sekmesine geçin
5. Gerekli Admin API scope'larını seçin (ör. read_orders, write_products)
6. Uygulamayı kur → Onay verin
7. Admin API erişim tokeni tek seferlik gösterilir hemen kaydedin

‍

Uyarı: Shopify bu token'ı yalnızca bir kez görüntülüyor. Sayfayı kapattıktan sonra token'a bir daha erişemezsiniz; yeni token almak için uygulamayı kaldırıp yeniden kurmanız gerekir.

Bu yöntemin kısıtı: tek bir mağaza için çalışır. Birden fazla mağazaya aynı entegrasyonu bağlayacaksanız OAuth akışına geçmeniz gerekir.

Yöntem 2: Partner Dashboard ve OAuth 2.0 Akışı

SaaS ürünleri, ajanslar ve multi-store entegrasyonlar için bu yol kullanılır. Partner Dashboard üzerinden oluşturulan uygulama, farklı mağazalara OAuth flow ile kurulabilir.

Teknik akış:

1. Kullanıcı → Partner Dashboard app sayfasına yönlendirilir

2. Mağaza domain'i ile /auth endpoint'i çağrılır

3. Shopify OAuth yetkilendirme sayfası açılır

4. Kullanıcı onay verir → Shopify, code ile callback URL'ye yönlendirir

5. Sunucu HMAC'i doğrular

6. code + client_id + client_secret ile token endpoint'i çağrılır

7. access_token döner → veritabanında saklanır

‍

Bu akışı sıfırdan uygulamak, özellikle HMAC doğrulama ve scope yönetimi konularında hata payı yüksek bir süreç.

Shopify App Token Generator: Açık Kaynak Çözümümüz

Nodus Works olarak, entegrasyon projelerinde defalarca karşılaştığımız bu problemi çözmek için lightweight bir araç geliştirdik ve açık kaynak olarak yayımladık:

github.com/nodusworkscom/shopify-app-token-generator

Bu araç, OAuth 2.0 akışını yerel ortamda çalıştırır ve kalıcı bir Admin API access token üretir. Tam OAuth implementasyonu yazmak zorunda kalmadan birkaç dakika içinde geçerli bir token elde edersiniz.

Ne işe yarıyor?

Aracı çalıştırdığınızda localhost'ta küçük bir Express sunucusu başlıyor. Shopify'ın OAuth yetkilendirme sayfasına yönlendiriliyorsunuz; onay verdikten sonra callback URL'ye dönen code otomatik olarak yakalanıyor, HMAC doğrulaması yapılıyor ve access_token hem terminalde hem tarayıcıda gösteriliyor.

‍

Kurulum:

git clone https://github.com/nodusworkscom/shopify-app-token-generator.git

cd shopify-app-token-generator

npm install

cp .env.example .env

‍

.env dosyanızı doldurun:

‍

SHOPIFY_API_KEY=your_client_id

SHOPIFY_API_SECRET=your_client_secret

SHOP=your-store.myshopify.com

SCOPES=read_products,write_orders,read_customers

‍

npm start

‍

Tarayıcıda localhost:3000 adresine gidin → Shopify onay ekranında "Install app"a tıklayın → Token terminalde ve ekranda görüntülenir.

Ön koşullar:

• Node.js v16 veya üzeri
• Shopify Partner hesabı (ücretsiz)
• Shopify Partner Dashboard'da oluşturulmuş uygulama
• Callback URL olarak http://localhost:3000/callback tanımlı

Önemli: Partner Dashboard'daki uygulama ayarlarında base URL http://localhost:3000 ve redirect URL http://localhost:3000/callback olarak tanımlı olmalı. Aksi hâlde redirect_uri_mismatch hatası alırsınız.

‍

Birden fazla mağaza için: .env dosyasındaki SHOP değerini değiştirip her mağaza için süreci tekrarlayabilirsiniz. Üretilen her token o mağazaya özgüdür.

MIT lisanslı olan bu araç, Shopify entegrasyon projelerine başlamak için bir başlangıç noktası ve token üretim sürecini anlamak için pratik bir referans olarak kullanılabilir.

Custom App Güvenliği ve Best Practices

Token güvenliği, entegrasyonun en kritik boyutudur. Bir Admin API access token, mağazanızdaki siparişleri, müşterileri ve ürünleri yönetme yetkisi taşır.

Token saklama: Token'ı environment variable olarak saklayın, asla kaynak koda veya version control sistemine dahil etmeyin. .gitignore dosyanıza .env eklediğinizi doğrulayın. Production ortamında Vault, AWS Secrets Manager veya benzeri bir secret management aracı kullanın.

Minimum scope prensibi: Entegrasyonun ihtiyaç duyduğu scope'ların ötesine geçmeyin. Yalnızca sipariş okuyacak bir sistem için read_orders yeterlidir write_orders veya read_customers eklemeyin. Shopify, scope listesini sonradan daraltmanıza izin verse de genişletmek yeniden kurulum gerektirir.

HMAC doğrulama: OAuth callback'inde Shopify'ın gönderdiği HMAC imzasını doğrulamadan tokeni kabul etmeyin. Bu adımı atlayan implementasyonlar token çalma saldırılarına açık hale gelir. Token generator aracımız bu adımı otomatik olarak yapıyor.

Webhook güvenliği: Shopify webhook'larını da HMAC ile doğrulayın. X-Shopify-Hmac-Sha256 header'ını kontrol etmeden gelen webhook verilerini işlemeyin.

‍

Shopify entegrasyonlarında güvenlik ve teknik mimari konularında destek için Shopify entegrasyon çözümleri hizmetimize göz atabilirsiniz.

Yaygın Hatalar ve Çözümleri

invalid_client hatası: Client ID veya Client Secret yanlış girilmiş. Partner Dashboard'daki credentials ile .env dosyasını karşılaştırın.

redirect_uri_mismatch hatası: Callback URL, Partner Dashboard'da tanımlı redirect URL ile birebir eşleşmiyor. Trailing slash farkı bile hataya yol açar: http://localhost:3000/callback ile http://localhost:3000/callback/ farklı kabul edilir.

invalid_scope hatası: İstenen scope'lardan biri geçersiz veya yanlış yazılmış. Shopify'ın resmi scope dokümantasyonunu referans alın.

Token tek seferlik gösterim: Admin panelinden alınan token kaydedilmediyse uygulamayı kaldırıp yeniden kurmak gerekir. Partner Dashboard OAuth yoluyla alınan token tekrar OAuth akışı çalıştırılarak yenilenebilir.

HMAC doğrulama başarısız: Client Secret yanlış veya query string parametreleri değiştirilmiş. Token generator aracı doğrulamayı otomatik yapıyor; manuel implementasyonda parametre sıralamasına dikkat edin.

Shopify entegrasyon projelerinde ERP bağlantıları ve sistem entegrasyonları hakkında daha fazla bilgi için Shopify ERP entegrasyonu rehberimizi ve Shopify entegrasyon yazımızı inceleyebilirsiniz. Muhasebe sistemi entegrasyonu için ise Shopify fatura ve muhasebe entegrasyonu içeriğimize bakın.

Sıkça Sorulan Sorular

Shopify custom app ile private app arasındaki fark nedir? Private app, Shopify'ın 2023'te kaldırdığı eski bir yapıdır. Custom app, private app'in yerini alan ve daha güvenli bir token yönetimi sunan yeni sistemdir. Mevcut private app credential'larınız artık çalışmıyor; custom app'e geçiş zorunlu.

Custom app token'ı süresiz mi geçerli? Offline access token, uygulama mağazadan kaldırılmadığı sürece kalıcı olarak geçerli kalır. Online token ise 24 saat sonra sona erer. Arka plan entegrasyonları için offline token kullanmanız gerekir.

Shopify custom app ücretsiz mi geliştirilebilir? Shopify Partner hesabı ücretsizdir. Custom app geliştirme için ek ücret yoktur; ancak entegre ettiğiniz mağaza aktif bir Shopify planına sahip olmalıdır. Geliştirme sırasında ücretsiz development store kullanabilirsiniz.

Bir custom app ile kaç mağazaya bağlanabilirim? Admin panelinden oluşturulan custom app yalnızca tek bir mağazaya özgüdür. Birden fazla mağazaya bağlanmak için Partner Dashboard üzerinden OAuth akışı kullanan bir yapı kurmanız gerekir; bu durumda her mağaza için ayrı bir access token üretilir.

Shopify GraphQL Admin API ile REST API arasında seçim nasıl yapılır? Shopify, GraphQL Admin API'ını aktif olarak geliştiriyor ve REST API'yı kademeli olarak kullanımdan kaldırıyor. Yeni entegrasyonlarınızı GraphQL üzerine kurmanızı öneririz. GraphQL, veri over-fetching sorununu çözer ve daha esnek sorgulama imkânı sunar.

OAuth akışı olmadan token alabilir miyim? Evet. Shopify admin paneli üzerinden oluşturulan custom app, OAuth akışı gerektirmeden direkt token üretir. Bu yöntem yalnızca kendi mağazanız için geçerlidir; başka mağazalara kurulum için OAuth zorunludur.

Shopify webhook'larını custom app üzerinden nasıl dinlerim? Custom app token'ını aldıktan sonra Admin API aracılığıyla webhook subscription oluşturabilirsiniz. Bir endpoint tanımlayıp Shopify'ın o endpoint'e POST gönderimini dinlersiniz. Her webhook isteğini X-Shopify-Hmac-Sha256 header'ını doğrulayarak işleyin.

Token generator aracı production ortamında kullanılabilir mi? Araç, token üretmek için tasarlanmıştır bir kez geçerli token aldıktan sonra araca ihtiyacınız kalmaz. Üretilen token production API isteklerinde kullanılabilir. Araç; öğrenme, hızlı token üretimi ve entegrasyon testleri için idealdir.

Sonuç

Shopify custom app geliştirme, özellikle yeni token sistemiyle birlikte gereksiz yere karmaşık bir hal almış durumda. Hangi token türünü, hangi yöntemle alacağınızı bilmeden başlamak saatler kaybettirebilir.

Admin panelinden direkt token alma tek mağaza entegrasyonları için yeterli. Birden fazla mağazayı destekleyecek veya 3rd party bir sistemi entegre edecekseniz OAuth 2.0 akışı kaçınılmaz.

Geliştirdiğimiz açık kaynak araç shopify-app-token-generator, bu sürecin en zor adımını HMAC doğrulamalı OAuth akışını birkaç dakikaya indiriyor.

Shopify entegrasyon projeniz için teknik danışmanlık, mimari tasarım veya geliştirme desteği arıyorsanız Shopify teknik destek ve bakım hizmetimizden yararlanabilir ya da doğrudan bizimle iletişime geçebilirsiniz.