Geliştirici API'si, MCP, GitHub ve tetikleyici simülasyonu

Tetikleyicilerinizi inceleyebilir, bunları etkinleştirebilir veya devre dışı bırakabilir, olay geçmişini okuyabilir ve kendi kodunuzdan ya da bir yapay zeka asistanından bir tetikleyiciyi simüle edebilirsiniz. Workflow Trigger Extensions, bir REST API’si ve bir MCP sunucusu sunar; ayrıca bir GitHub deposuna bağlanabilir, böylece özel tetikleyici kodunuz sürüm kontrolü altında tutulur. Bu üç öğenin tümü, Geliştirici sayfasında yönetilir.

Bir tetikleyicinin simülasyonu

Shopify Flow iş akışını test etmek, genellikle mağazanızda gerçek bir işlem gerçekleştirmeyi gerektirir: bir ürünü düzenlemek, sipariş vermek, bir oylama sonucunu beklemek gibi. Simülasyon ise bu bekleme süresini ortadan kaldırır: bir tetikleyici seçin, onu bir kaynağa yönlendirin; tetikleyici, sanki gerçek olay az önce gerçekleşmiş gibi devreye girer.

Bunu çalıştırmanın iki yolu:

• Uygulamada, Etkinlik Geçmişi'nden herhangi bir etkinliği açın ve tekrar Simüle Et seçeneğini seçin. Bu, o etkinliği tam olarak yeniden tetikler.
• API veya MCP üzerinden, bir kaynak kimliği veya geçmiş bir olay kullanılarak.

Simülasyon, kasıtlı olarak gerçeğe sadık kalır. Kısayol niteliğinde bir veri yükü oluşturmaz; gerçek bir Shopify webhook’unun izlediği aynı iş akışını takip eder; dolayısıyla iş akışınızın aldığı veriler, üretim ortamında alacağı verilerle tam olarak aynıdır.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'

Bir deneme çalıştırması, tetikleyiciyi doğrular, konuyu çözer ve yükü gösterir; ancak hiçbir şey tetiklemez. Gerçek bir tetikleme yapmak için dryRun ifadesini kaldırın. Ayrıca, yeni bir olay oluşturmak yerine {"fromHistoryId":"456"} değerini aktararak geçmişteki bir olayı yeniden tetikleyebilirsiniz.

Webhook yerine yoklama yoluyla tetiklenen tetikleyiciler simüle edilemez; bu tetikleyiciler, tetikleyici listesinde simulatable: false değerini gösterir.

API anahtarları

Geliştirici sayfasında bir anahtar oluşturun ve erişim düzeyini seçin:

• Yalnızca okuma - tetikleyicileri ve durumlarını görüntüleme, olay geçmişini, istatistikleri ve izinleri okuma.
• Okuma ve yazma - ayrıca tetikleyicileri açıp kapatma.
• Okuma, yazma ve yürütme - ayrıca tetikleyicileri simüle etme ve özel tetikleyici kodunu test etme.

Anahtarın tam metni, oluşturulduğunda bir kez gösterilir. Anahtarlar karma olarak saklanır ve herhangi bir zamanda iptal edilebilir. Bunu bir Bearer belirteci olarak gönderin:

Authorization: Bearer ftk_your_key_here

Simülasyon, yukarıda belirtilen nedenden ötürü kendi seviyesinin arkasında yer alır: Otomasyonlarınızı gerçek ortamda çalıştırır; bu nedenle, günlük okuma işlemleri için kullanılan bir anahtar, bu otomasyonları tetikleyemez.

REST API

Yöntem	Yol	Seviye	Amaç
AL	/api/v1	yok	API endeksi - API'nin çalışır durumda olduğunu gösterir
AL	/api/v1/me	oku	Yetkilendirmeyi kontrol edin ve anahtarınızın seviyesini görün
AL	/api/v1/triggers	oku	Mağazanız için her bir tetikleyicinin durumu
AL	/api/v1/triggers/:handle	oku	Bir tetikleyiciyi ayrıntılı olarak inceleme
PUT	/api/v1/triggers/:handle	yaz	Bir tetikleyiciyi açın veya kapatın
PUT	/api/v1/triggers	yaz	Tek bir çağrı ile birden fazla cihazı açın veya kapatın
YAYIN	/api/v1/triggers/:handle/simulate	yürütmek	Bir tetikleyiciyi simüle et
AL	/api/v1/triggers/custom	oku	Kendi özel tetikleyicileriniz ve bunlara ait kodlar
AL	/api/v1/triggers/custom/:handle/test	oku	Özel bir tetikleyici için yakalanan örnek olay
YAYIN	/api/v1/triggers/custom/:handle/test	yürütmek	Kaydetmeden veya tetiklemeden özel tetikleyici kodunu çalıştır
AL	/api/v1/history	oku	Tetikleyici olayları listele
AL	/api/v1/history/:id	oku	Bir olayı, içerdiği verilerle birlikte al
AL	/api/v1/stats	oku	Toplamlar, başarı oranı, durum dağılımı
AL	/api/v1/permissions	oku	Hangi veri izinlerini verdiniz ve her birinin hangi işlevleri etkinleştirdiği

Kurulum için GET /api/v1/triggers komutu oldukça kullanışlıdır: Her bir tetikleyici için gerekli izinleri, bu izinlerin verilip verilmediğini, tetikleyicinin açık olup olmadığını ve uygulamanın hangi bölümünden yönetilebileceğini gösterir.

Tetikleyicileri açma ve kapatma

PATCH yerine PUT kullanılır, çünkü bu çağrı idempotenttir - zaman aşımından sonra tekrar gerçekleştirilmesi durumunda hiçbir işlemin iki kez uygulanması söz konusu olmaz; bu durum, API’yi bir asistanın yönettiği durumlarda önemlidir.

curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

"Enabling" işlevi hiçbir zaman bir izin vermez. Tetikleyicinin, sizin henüz vermediğiniz bir izne ihtiyacı varsa, çağrı yine de başarılı olur ve tam olarak neyin eksik olduğunu ve izni nereden vermeniz gerektiğini size bildirir:

{
  "enabled": true,
  "scopeGranted": false,
  "missingScopeLabels": ["Order Data Access"],
  "permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
  "warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}

Bu bağlantı, İzinler sayfasını açar ve sayfa doğrudan ihtiyacınız olan karta kaydırılmış olarak görüntülenir.

Veri senkronizasyonunu da başlatmak için "sync": true ekleyin; böylece tetikleyici, yalnızca bundan sonra oluşturulacak kayıtlar üzerinde değil, halihazırda mevcut olan kayıtlar üzerinde de çalışır.

Birden fazla tetikleyiciyi aynı anda değiştirmek için, PUT /api/v1/triggers komutu hem açık bir listeyi hem de tüm kategoriyi kabul eder:

{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }

GitHub'a bağlan

Geliştirici sayfasında, Bağlantılar sekmesi, Özel tetikleyiciler kodunuz için bir GitHub deposu bağlamanıza olanak tanır. Değişiklikler bir çekme isteğinde incelemeye açılır; kimin neyi değiştirdiğini görebilir ve artık çalışmayan bir dönüştürmeyi geri alabilirsiniz.

"Bağlan" seçeneği, seçtiğiniz hesaba GitHub Uygulamamızı yükler. Uygulamanın hangi depolara erişebileceğini siz belirlersiniz ve bu erişim iznini GitHub üzerinden istediğiniz zaman iptal edebilirsiniz. Bir depo seçtiğinizde, mevcut tüm özel tetikleyicileriniz anında bu depoya yazılır; böylece uygulama zamanla doldurulmak yerine başlangıçtan itibaren uyumlu hale gelir.

Ne yapıyorsunuz?	Ne olur?
Uygulamada bir tetikleyici oluşturun, düzenleyin veya kopyalayın	Dosya, deponuza kaydedildi
Uygulamada bir tetikleyiciyi silme	Dosya, deponuzdan kaldırıldı
Bağlı dalda bir değişikliği kaydet	Uygulamada tetikleyicinin kodu güncellendi

Her tetikleyici, kendi tanıtıcısının adını taşıyan tek bir dosyadır ve bu dosya, düzenleyicide gördüğünüz modülü tam olarak içerir - etrafında hiçbir ek unsur bulunmaz. Dolayısıyla, bu dosyayı kendi düzenleyicinizde açabilir, çalıştırabilir ve diğer JavaScript dosyaları gibi lint kontrolünden geçirebilirsiniz; ardından, commit yapmadan önce yukarıdaki /test uç noktasını kullanarak dosyayı gerçek bir yakalanmış olay üzerinde çalıştırabilirsiniz.

Daha önceki bir sürüme dönmek

Bir değişikliği geri almak için Git bilmenize gerek yoktur. Bir depo bağlandığında, tetikleyici düzenleyicisi, o dosyanın tarihi ve yazarıyla birlikte önceki tüm sürümlerini listeleyen bir Sürüm açılır menüsü gösterir. Birini seçtiğinizde, bu sürüm düzenleniciye kaydedilmemiş bir değişiklik olarak yüklenir; böylece önce onu okuyabilirsiniz - kaydetme işlemi, onu yeni bir commit olarak geri yükler.

Değiştirme veya bağlantıyı kesme

Depoyu değiştir seçeneği, kuruluma herhangi bir değişiklik yapmadan sizi seçiciye geri döndürür. Bağlantıyı kes seçeneği, kurulumu buradan kaldırmanın yanı sıra GitHub’daki kurulumun da iptal edilmesini sağlar; yani adından da anlaşıldığı gibi çalışır. İzinleri yönet seçeneği, GitHub’daki kurulum ayarlarını açar; burada depolar ekleyebilir veya kaldırabilirsiniz.

Özel tetikleyici kodunun test edilmesi

Özel tetikleyici kodunuzu bir depoda saklıyor ve kendi düzenleyicinizde düzenliyorsanız, bu kodu önce uygulamaya kaydetmeden yakalanan örnek olay üzerinde çalıştırabilirsiniz.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"

Uygulamanın “Test” düğmesinde gösterilen bilgileri alırsınız: komutun çalışıp çalışmayacağı, çıktı nesnesi, ctx.log satırlarınız ve çalışma süresi.

Hiçbir işlem gerçekleştirilmez ve hiçbir şey kaydedilmez - hiçbir iş akışı çalıştırılmaz, hiçbir olay kaydedilmez, hiçbir kota kullanılmaz ve depolanan kod üzerinde herhangi bir değişiklik yapılmaz. Bir dosya izleyicisi aracılığıyla her kaydetme işleminde güvenle çalıştırılabilir. Tam iş akışı için bkz. Özel tetikleyiciler.

MCP sunucusu

Geliştirici sayfasındaki MCP sekmesi, sunucu URL’sini ve Claude, Cursor, VS Code, Gemini CLI ve diğerleri için kopyalanmaya hazır bir bağlantı komutunu gösterir. Araçlar, REST uç noktalarını yansıtır ve araç seti, anahtarınızın seviyesini yansıtır; salt okunur bir anahtar, yazma veya yürütme araçlarını hiç görmez.

Araç	Seviye	Ne işe yarar?
list_triggers	oku	Her tetikleyici ve durumu
list_custom_triggers	oku	Kendi özel tetikleyicileriniz ve bunlara ait kodlar
get_custom_trigger_sample	oku	Özel bir tetikleyicinin karşılaştırma yaptığı yakalanan olay
list_history	oku	Son dönemde meydana gelen tetikleyici olaylar
get_event	oku	Yükünü de içeren bir olay
get_stats	oku	Toplam istatistikler
get_permissions	oku	Verilen izinler ve bu izinlerin sağladığı olanaklar
get_trigger	yaz	Bir tetikleyiciyi ayrıntılı olarak inceleme
set_trigger	yaz	Bir tetikleyiciyi açın veya kapatın
set_triggers_bulk	yaz	Birkaç tanesini aynı anda açın veya kapatın
simulate_trigger	yürütmek	İstenildiğinde bir tetikleyiciyi çalıştır
test_custom_trigger	yürütmek	Kaydetmeden veya tetiklemeden özel tetikleyici kodunu çalıştır

Bir asistanı gerçekten kullanışlı kılan şey şudur: Siz sohbetten ayrılmanıza gerek kalmadan mevcut öğeleri listeleyebilir, bir tetikleyicinin neye ihtiyaç duyduğunu açıklayabilir, onu etkinleştirebilir, bir test olayı başlatabilir, sonucu geri okuyabilir ve özel tetikleyiciler için kodu yeniden yazıp test edebilir.

Verileriniz nasıl korunuyor?

Olay verileri, kişisel veriler gizlenmiş şekilde döndürülür: e-posta adresleri, telefon numaraları, kart numaraları ve kişi adlarının yer aldığı alanlar *** olarak gösterilir. Verilerin kullanışlılığını korumak amacıyla Shopify kaynak kimlikleri ve işletme alanları olduğu gibi bırakılır.

Gizleme işlemi alan adları ve değer kalıpları üzerinde çalışır; bu nedenle dikkatli bir işlemdir ancak bir garanti değildir - serbest metin alanındaki kişisel veriler yine de ortaya çıkabilir. Hata mesajları da sunucudan gönderilmeden önce iç tanılama ayrıntılarından arındırılır.

GitHub bağlantısı, sızdırılabilecek hiçbir kimlik bilgisini saklamaz: yalnızca kurulum kimliği tutulur ve depoya erişim, talep üzerine oluşturulan ve bir saat içinde geçerliliğini yitiren bir jeton kullanılarak sağlanır.

Sonraki adımlar

• Özel tetikleyiciler - Birkaç satır JavaScript koduyla kendi tetikleyicinizi oluşturun.
• Planlar ve kullanım - Neyin bir olay olarak kabul edildiği ve kotanın nasıl işlediği.
• Workflow Trigger Extensions’e Giriş - tetikleyicilerin nasıl çalıştığı ve nasıl etkinleştirileceği.

Hız sınırları

REST API ve MCP sunucusu, her API anahtarı başına tek bir bütçeyi paylaşır.

• Anahtar başına 60 saniyede 300 istek, sabit bir zaman aralığı olarak.
• Yürütme düzeyindeki çağrılar, saat başına 60 adetlik ikinci ve daha kısıtlı bir kota ile sınırlandırılır. Her iki kotayı da tüketirler; dolayısıyla yoğun bir yürütme dalgası, paylaşılan kotadan da pay alır. Bu uygulama için bu, bir tetikleyicinin simülasyonunu yapmak ve özel tetikleyici kodunu çalıştırmak anlamına gelir; her ikisi de iş akışlarınızı gerçekten tetikler.
• Her planda durum aynıdır. Planınızın sayaçları API çağrılarını değil, olayları tetikler; bu nedenle, plana yükseltme yapmanız bu rakamları artırmaz.
• İşlem sırasında HTTP 429 hatası döndü. Bekle ve yeniden dene; ideal olarak üstel bekleme yöntemi kullan.
• Önbelleğimiz kısa bir süre kullanılamaz hale gelirse, sınırlayıcı entegrasyonunuzu engellemek yerine açık konumda kalır.

Shopify’dan gelen webhook’lar için hız sınırlaması uygulanmaz

Shopify’ın bize gönderdiği webhook’ları sınırlamıyoruz; bunlar geldiği gibi kabul edilip kuyruğa alınır. Üst sınır, planınızın 30 günlük olay kotasıdır.

Özel tetikleyiciler yazıyorsanız bilmeniz gereken bir şey var: Kodunuz, dinlediği konudaki her olay için çalışır ve her çalıştırma, null değerini döndürerek filtrelediğiniz olaylar da dahil olmak üzere, bir olay olarak sayılır. Bunun maliyeti, aynı olay için yerleşik tetikleyicinin maliyeti ile aynıdır.

Shopify

Bunlar, Shopify’ın API’leri için Shopify tarafından belirlenen sınırlamalardır, bizim sınırlamalarımız değildir. Bu sınırlamalar, bu uygulamanın (ve iş akışlarınızın) Shopify tarafında yapabilecekleri işlemler için geçerlidir; büyük bir mağazada, bizim sınırlarımız içinde olsanız bile bu sınırlamalara ulaşabilirsiniz.

• Shopify API’lerinin tamamında girdi dizilerinin üst sınırı 250 öğedir. Bu sınırı aşan bir dizi içeren istek reddedilir.
• Sayfalama, 25.000 nesneye kadar devam eder. Sayımlar 25.000'e kadar doğrudur; bu sayının üzerinde Shopify, "25.000'den fazla" anlamına gelen 25001 değerini döndürür. Daha fazla nesneye ulaşmanız gerekiyorsa, önce filtre uygulayın.
• GraphQL Yönetici API’si, saniye başına puan cinsinden hesaplanan sorgu maliyetine göre ölçülür ve üst sınır, mağazanın Shopify planına bağlıdır:

Shopify planı	Saniye başına puan
Standart	100
İleri Düzey	200
Ayrıca	1000
Kurumsal (Ticaret Bileşenleri)	2000

Storefront API’sinde kullanım sınırlaması yoktur.

Tüm ayrıntılar: Shopify API istek sınırları