Geliştirici API'si ve MCP

Sayfayı kopyala

Webhook'ları REST API ile kendi kodunuzdan veya MCP ile yapay zeka asistanından yönetin. Shopify Flow için okuma, yazma ve çalıştırma API anahtarları.

Uygulamada yönettiğiniz her şeyi, kendi kodunuzdan veya bir yapay zeka asistanından da yönetebilirsiniz. Workflow Webhooks, iki arayüz sunar: bir REST API ve bir MCP sunucusu. Her ikisi de Geliştirici sayfasında yer almaktadır.

API anahtarları

Her iki arayüz de bir API anahtarıyla kimlik doğrulaması yapar. Geliştirici sayfasında, API anahtarları bölümünden bir anahtar oluşturun ve erişim düzeyini seçin:

Yalnızca okuma - webhook'ları listeleme, çağrı geçmişini ve istatistikleri okuma.
Okuma ve yazma - ayrıca webhook oluşturma, güncelleme ve silme.
Oku, yaz ve çalıştır - ayrıca bir test çağrısı başlatabilir veya geçmişteki bir çağrıyı tekrar oynatabilirsin.

Anahtarın tam metni, oluşturulduğunda bir kez gösterilir. O anda kopyalayıp güvenli bir şekilde saklayın; daha sonra tekrar göremezsiniz. Anahtarlar karma olarak saklanır, asla düz metin halinde saklanmaz ve bir anahtarı istediğiniz zaman iptal edebilirsiniz.

Her istekte anahtarı Bearer belirteci olarak gönderin:

text

Authorization: Bearer fwk_your_key_here

Neden “yürütme” ayrı bir seviye?

Bir webhook’u tetiklemek, Shopify Flow iş akışlarınızı gerçekten çalıştırır ve bu iş akışları mağazanızda değişikliklere yol açabilir - siparişlere etiket eklemek, e-posta göndermek, stokları güncellemek gibi. Bunu kendi seviyesinde tutmak, günlük işler için bir komut dosyasına veya yapay zeka asistanına verdiğiniz bir anahtarın, otomasyonlarınızı yanlışlıkla tetikleyemeyeceği anlamına gelir. Varsayılan olarak okuma anahtarları verin ve yalnızca gerçekten ihtiyaç duyduğunuz durumlarda yürütme anahtarı oluşturun.

Ana URL

API ve MCP sunucusu, özel bir ana bilgisayar adından sunulmaktadır:

text

https://shopify.workflow-webhooks.app

Dolayısıyla REST API, https://shopify.workflow-webhooks.app/api/v1 adresinde, MCP sunucusu ise https://shopify.workflow-webhooks.app/api/mcp adresinde yer almaktadır. Geliştirici sayfasında her ikisi de bir kopyala düğmesiyle gösterilmektedir.

Bu ana bilgisayar adı yalnızca /api adresine hizmet verir; gömülü yönetici kullanıcı arayüzü ise Shopify’de kayıtlı kendi URL’sinde kalır. Bunları ayrı tutmak, bir komut dosyasına, CI işine veya AI istemcisine yapıştırdığınız adresin sabit olmasını ve uygulamanın gömülme durumuyla ilgisiz kalmasını sağlar.

REST API

Temel URL, Geliştirici sayfasında gösterilmektedir. Başlıca uç noktalar:

Yöntem	Yol	Seviye	Amaç
AL	`/api/v1`	yok	API endeksi - API'nin çalışır durumda olduğunu doğrular
AL	`/api/v1/me`	oku	Yetkilendirmeyi kontrol edin ve anahtarınızın seviyesini görün
AL	`/api/v1/webhooks`	oku	Webhook'ları listele
YAYIN	`/api/v1/webhooks`	yaz	Bir webhook oluşturun
AL	`/api/v1/webhooks/:id`	oku	Bir webhook alın
PUT / PATCH	`/api/v1/webhooks/:id`	yaz	Bir webhook'u güncelle
SİL	`/api/v1/webhooks/:id`	yaz	Bir webhook'u silme
YAYIN	`/api/v1/webhooks/:id/test`	yürütmek	Bir test çağrısı gerçekleştirin
AL	`/api/v1/history`	oku	Liste çağrıları
AL	`/api/v1/history/:id`	oku	Bir çağrı ve buna ait yükünü al
YAYIN	`/api/v1/history/:id/replay`	yürütmek	Geçmişteki bir çağrıyı tekrar oynat
AL	`/api/v1/stats`	oku	Toplamlar, başarı oranı, günlük seriler
AL	`/api/v1/templates`	oku	Yerleşik webhook şablonları

Anahtarınızın çalışıp çalışmadığını hızlıca kontrol etmek için:

bash

curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"

json

{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

MCP sunucusu

MCP sunucusu, bir yapay zeka asistanının (Claude, Cursor, VS Code, Gemini CLI ve diğerleri) sohbet sırasında webhook’larınızla etkileşime girmesini sağlar. Geliştirici sayfasında yer alan MCP sekmesinde, sunucu URL’si ve her istemci için kopyalanmaya hazır bir bağlantı komutu gösterilir; bu komutlara anahtarınız önceden eklenmiştir.

Bu araçlar, REST uç noktalarını yansıtmaktadır ve araç seti, anahtarınızın seviyesine göre şekillenir: Salt okunur bir anahtar, webhook’ları oluşturan, silen veya tetikleyen araçları bile göremez. Tüm kimlik doğrulama ve veri işleme işlemleri sunucu tarafında gerçekleştirilir.

Verileriniz nasıl korunuyor?

Bu API’yi bir otomasyon sistemine veya yapay zeka asistanına bağlamadan önce bilmeniz gereken iki husus vardır.

Webhook'unuzun kimlik doğrulama jetonu hiçbir şekilde okunamaz. Bir webhook'ta belirlediğiniz jeton veya imzalama gizli anahtarı, API veya MCP aracılığıyla hiçbir düzeyde geri okunamaz. Yanıtlar size yalnızca bir jetonun ayarlanıp ayarlanmadığını (hasToken) bildirir, değerini asla bildirmez. Yeni bir jeton ayarlayabilirsiniz; eski jetonu asla geri alamazsınız.

Yüklerdeki kişisel veriler maskelenmiştir. Webhook yükleri dış sistemlerden gelir ve genellikle müşteri bilgilerini içerir. Bir çağrı yükü sunucudan ayrılmadan önce, kişisel veriye benzeyen değerler *** ile değiştirilir: e-posta adresleri, telefon numaraları, kart numaraları ve bir kişinin adını taşıyan alanlar (customerName, shippingAddress ve benzeri). İstek başlıkları, uygulamanın geçmiş ekranında olduğu gibi temizlenir.

Bu maskeleme işlemi özenle yapılmış olsa da bir garanti değildir. Bu işlem, alan adları ve değer kalıpları üzerinde çalışır; dolayısıyla serbest metin alanlarında yer alan kişisel veriler - bir not, bir yorum, bir mesaj gövdesi gibi - yine de ortaya çıkabilir. API yanıtlarını potansiyel olarak müşteri verileri içerebilecek şekilde değerlendirin ve buna uygun şekilde saklayın.

Test ve tekrar işlemleri kotanızı tüketmez. API aracılığıyla gerçekleştirdiğiniz çağrılar test olarak kaydedilir; bu nedenle planınızın aylık kotasından düşülmez. Tekrar işlemleri de hesaba katılmaz, çünkü orijinal çağrı zaten hesaba katılmıştır.

Sonraki adımlar

Workflow Webhooks’a Giriş - webhook'ların ve yük eşlemesinin nasıl çalıştığı.

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 sıkı bir kota ile sınırlandırılır. Her iki kote de kullanılır; dolayısıyla yürütme işlemlerinde ani bir artış, paylaşılan kotadan da pay alır. Bu uygulama için bu, bir webhook’u test amaçlı çağırmak ve bir geçmiş girdisini yeniden oynatmak anlamına gelir; her ikisi de aslında Shopify Flow iş akışlarınızı çalıştırır.
Bu durum tüm planlarda aynıdır. Planınız API çağrılarını değil, işlev çağrılarını ölçer; bu nedenle planınızı yükseltmek 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.

Gelen webhook’lar için hız sınırlaması uygulanmaz

Bu konuyu netleştirmekte fayda var, çünkü bize en sık sorulan soru budur: Gelen webhook iletimlerini kısıtlamıyoruz. Kaynak sisteminiz ne kadar yoğun olursa olsun, webhook’ları geldikleri anda anında iletin - bizim tarafımızda saniye veya dakika başına herhangi bir sınırlama yoktur.

Tek sınır, planınızın **30 günlük çağrı **kotasıdır. Bu kota tükendiğinde, süre dolana veya planınızı yükseltinceye kadar yeni çağrılar işleme alınmaz. Bunun ötesinde geçerli olan sınırlar Shopify’a aittir: Shopify Flow’un kendi yürütme sınırları vardır ve bir tetikleyici yükünün boyutu en fazla 50 KB olabilir.

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ı