REST API kılavuzu

Tüm yollar https://shopify.workflow-transactional-email.app adresine göre belirlenir. İndeks hariç tüm uç noktalarda Authorization: Bearer fak_... başlığı gereklidir - bkz. Kimlik Doğrulama ve API Anahtarları.

Yanıtlar JSON biçimindedir. Hatalar baştan sona aynı yapıya sahiptir:

{ "error": "Invalid or missing API key" }

İndeks ve kimlik

Yöntem	Yol	Seviye	Amaç
AL	/api/v1	yok	API endeksi. API’nin çalışır durumda olduğunu doğrular ve mevcut sürümü bildirir
AL	/api/v1/me	oku	Bir anahtarın çalışıp çalışmadığını kontrol edin ve erişim düzeyini inceleyin

Dizin bir anahtara ihtiyaç duymadığından, bir izleme aracını bu dizine yönlendirmek güvenli bir durum kontrolüdür.

E-posta şablonları

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/email-templates	oku	E-posta şablonlarını listeler. q, ad, konu ve açıklamaya göre arama yapar; category=transactional veya category=marketing, tek bir e-posta türünü listeler
YAYIN	/api/v1/email-templates	yaz	Bir düzen oluşturun
AL	/api/v1/email-templates/:id	oku	Tasarımı veya ekleriyle birlikte, altbilgi metinleri ve dil listesi içeren tek bir sayfa düzeni
PUT / PATCH	/api/v1/email-templates/:id	yaz	Bir düzeni değiştirin. Yalnızca gönderdiğiniz alanlar değişir
SİL	/api/v1/email-templates/:id	yaz	Bir düzeni, çevirileriyle ve sürümleriyle birlikte silme
AL	/api/v1/layout-schema	oku	Bir düzen nasıl yazılır: tasarım biçimi, her bloğun varsayılan ayarları, kullanabileceğiniz Liquid kodları, sınırlamalar ve bir örnek

Liste, page (varsayılan 1), limit (varsayılan 25, maksimum 100) ve ad, konu ve açıklamayı arayan q parametrelerini kabul eder. API üzerinden türe göre filtreleme yapılmamaktadır; bunun yerine her bir düzeninde category parametresini inceleyin.

Bir düzen şu alanları içerir:

Alan	Notlar
name, description	Ad girişi zorunludur, en fazla 200 karakter; açıklama en fazla 2000 karakter
bodyType	visual (varsayılan) veya text. Oluşturulduktan sonra değiştirilemez
defaultLocale	Düzenin kendi içeriğinin dili; aksi belirtilmedikçe en
category	transactional (varsayılan) veya marketing. Aşağıya bakınız
subject, previewText	Sıvı izin verilir. Konu zorunludur
bodyDesign	Görsel düzenler: { blocks, global?, header?, footer?, testVariables? }. Tasarımı değiştirirken tam halini gönderin; HTML body etiketi buradan oluşturulur
body	Metin düzenleri: HTML gövdesi
attachments	Metin düzenleri: Yüklenen dosyalar için [{ filename, fileKey, sendAsLink? }] (aşağıdaki dosyalara bakınız) veya e-posta gönderildiğinde https üzerinden alınan bir dosya için [{ filename, url }]
marketingTexts	Bir pazarlama şablonunun altbilgi metinleri veya null. Aşağıya bakınız

Konu, önizleme metni, ana metin ve her blok metindeki Liquid kodları ayrıştırılmalıdır; ayrıca her fileKey, mağazanıza ait olmalıdır; aksi takdirde, ilgili alanı belirten bir 400 hatası ile yazma işlemi reddedilir. Görsel tasarım oluşturmadan önce GET /api/v1/layout-schema adresini inceleyin: bu, oluşturucu tarafından kendiliğinden üretildiğinden, değişiklik göstermez.

Bu API aracılığıyla yapılan her yazma işlemi, tıpkı uygulamada bir kaydetme işlemi gibi, düzenin sürüm geçmişinde saklanır.

İşlem ve pazarlama şablonları

category, bir düzenin ne amaçla kullanıldığını belirtir. İşlemsel bir düzen, hiçbir değişiklik yapılmadan her alıcıya gönderilir. Pazarlama düzeni, abonelikten çıkan alıcıları atlar (bu adımda "To" alıcılarının tümü abonelikten çıkmış olduğundan mesaj gönderilmez ve geçmişte SKIPPED olarak gösterilir), her "To" alıcısına kendi abonelikten çıkma bağlantısı içeren tek bir mesaj olarak gönderilir (adım başına en fazla 20 adet) ve abonelikten çıkma cümlesi ile şirket bilgilerinizle sona erer. {{ unsubscribe_url }} ve {{ unsubscribe_link }} yerlerine bağlantıyı kendiniz yerleştirin; işlem amaçlı şablonlarda her ikisi de boştur. Bunun satıcı tarafı Pazarlama e-postaları ve abonelikten çıkma işlemleri bölümünde yer almaktadır.

marketingTexts, bir pazarlama şablonunun Ayarlar bölümündeki mağaza genelindeki metinler yerine kullandığı altbilgi metnidir:

{
  "marketingTexts": {
    "unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
    "unsubscribeLinkLabel": "Unsubscribe",
    "companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
  }
}

Her alan isteğe bağlıdır. Değer girilen bir alan, o alanın Ayarlar metnini değiştirir; diğerleri olduğu gibi kalır. null (varsayılan) değeri, e-postanın diline ait Ayarlar metinlerini ifade eder. Sınırlar: unsubscribeText ve companyDetails için 2000 karakter, unsubscribeLinkLabel için 100 karakter. Bir unsubscribeText alanı, {{ unsubscribe_link }} veya {{ unsubscribe_url }} ifadesini içermelidir; aksi takdirde yazma işlemi reddedilir. Bu alan tüm şablonlar için saklanır, ancak yalnızca pazarlama şablonlarıyla birlikte gönderilir.

Bir düzenin silinmesi hiçbir zaman engellenmez. Eğer Shopify Flow adımları hâlâ bu düzene işaret ediyorsa, yanıtta kaç tane olduğunu belirten bir warning uyarısı yer alır; bu adımlar, başka bir düzen kullanılana kadar başarısız olur.

Çeviriler

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/email-templates/:id/translations	oku	Bir mizanpajdaki her dil ve içeriği
AL	/api/v1/email-templates/:id/translations/:locale	oku	Tek dil
PUT	/api/v1/email-templates/:id/translations/:locale	yaz	Bir dil oluşturun veya mevcut bir dili değiştirin
SİL	/api/v1/email-templates/:id/translations/:locale	yaz	Bir dili kaldırın. Bu durumda sistem, yedek düzene geçer.
YAYIN	/api/v1/email-templates/:id/translations/:locale/promote	yaz	Bu dili, düzenin ana dili olarak belirleyin

:locale, de, fr veya pt-br gibi bir dil kodudur; büyük/küçük harf ve ayırıcı önemli değildir. Her düzen için en fazla 30 dil desteklenir. Shopify Flow adımındaki Dil alanı, gönderim anında bir dil seçer: tam yerel ayar, ardından temel dil, sonra bölgesel bir varyant; bunlar yoksa düzenin kendisi kullanılır.

PUT komutu, çevrilmiş içeriğin tamamını alır: subject (zorunlu), previewText ve bodyDesign (görsel) veya body (metin). Liquid etiketlerini ve URL’leri değiştirmeyin. Çeviriye özgü iki alan vardır:

Alan	Metin düzenleri	Anlamı
attachments	evet	Bir liste (düzeninkiyle aynı biçimde) = bu dilin kendi ekleri, [] = bu dilde yok. null = düzenin eklerini gönder. Atlandığında = mevcut seçimi korur; yeni bir dil, düzeninkini kullanır. Görsel düzenler, eklerini her dilin bodyDesign'inde bloklar olarak taşır ve bu alanı reddeder
marketingTexts	herhangi bir	Bu dilin altbilgi metinleri, düzenin metinlerinin üzerine alan bazında eklenir. null: düzenin metni kullanılır. Belirtilmezse: mevcut seçim korunur

Aynı iki alanı içeren bir çeviri döndürülür: attachments, düzenin metinlerini gönderirken null olurken, marketingTexts ise düzenin metinlerini kullanırken null olur.

promote, düzeni ve çeviriyi yer değiştirir: düzen, çevirinin içeriğini ve yerel ayarını alır; düzenin daha önce sahip olduğu içerik ise, daha önce ait olduğu dil için çeviri haline gelir. Ekler ve altbilgi metinleri de yer değiştirir, böylece her dil daha önce gönderdiği içeriği göndermeye devam eder. Yanıtta promoted, previousMainLanguage ve düzen bildirilir. Bu tek bir sürümdür, dolayısıyla geri alınabilir.

Sürümler

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/email-templates/:id/versions	oku	Kaydedilmiş sürümler, en yenisi önce. Uygulama en yeni 25 tanesini saklar
AL	/api/v1/email-templates/:id/versions/:version	oku	Bir sürümün tam anlık görüntüsü: mizanpaj ve tüm çeviriler
YAYIN	/api/v1/email-templates/:id/versions/:version/restore	yaz	O sürümü geri koy. Yeni bir sürüm olarak kaydedildi
AL	/api/v1/email-templates/:id/versions/github?page=	oku	Bağlı GitHub deposunda tutulan her sürüm, sayfa başına 20 adet
AL	/api/v1/email-templates/:id/versions/github/:sha	oku	Bir commit anındaki düzen
YAYIN	/api/v1/email-templates/:id/versions/github/:sha/restore	yaz	GitHub sürümünü geri yükleyin; bu işlem bir kaydetme işlemi gibi işlenir

Geliştirici sayfasında hiçbir depo bağlı değilken GitHub uç noktaları 409 hatası veriyor. Sayfa düzeni sürüm geçmişi ve GitHub'da sınırsız düzen geçmişi saklayın bölümlerine bakın.

E-posta gönderenler

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/smtp-configs	oku	SMTP gönderenlerini listele
AL	/api/v1/senders	oku	Bağlı posta kutularını listele (Microsoft 365, Google)

SMTP gönderenleri, kimlik bilgilerinin kendisini değil, hasUsername ve hasPassword değerlerini bildirir; kullanıcı adı da şifre kadar kimlik bilgilerinin bir parçası olduğu için her iki bilgi de gizlenir. Bir gönderen, adı, ana bilgisayarı ve gönderen adresi aracılığıyla tanımlanabilir durumda kalır. Bağlı posta kutuları, so***@example.com gibi kısmen maskelenmiş bir adres bildirir ve hiçbir zaman oturum açma jetonlarını paylaşmaz.

Yalnızca okunabilir. Uygulamada gönderenleri bağlayın ve düzenleyin.

Sırlar

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/secrets	oku	Gizli isimleri ve açıklamaları listele

hasValue değerini döndürür, asla gizli anahtarın kendisini döndürmez. Gizli anahtarı geri okuyan bir uç nokta yoktur. Gizli anahtarları uygulama içinde oluşturun ve güncelleyin.

Yüklenen dosyalar

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/files	oku	Yüklenen logolar, resimler ve eklerin listesi
SİL	/api/v1/files	yaz	Gövdedeki key'ye göre birini sil

List, dosya adına göre arama yapmak için page, limit (en fazla 100) ve q parametrelerini kabul eder.

?usage=true eklediğinizde, her dosya inUse değerinin yanı sıra, o dosyaya referans veren düzenleri ve ön ayarları listeleyen bir usedBy dizisi de bildirir. Tek bir istekle silinmesinde sakınca olmayan tüm öğeleri bu şekilde bulabilirsiniz. Bu özellik, düzenlerinizi ve ön ayarlarınızı taradığından, varsayılan olarak etkin değildir; kullanılması için özel olarak etkinleştirilmesi gerekir.

Dosya yükleme işlevi burada gösterilmemektedir - dosyaları uygulamadaki medya seçici aracılığıyla ekleyin.

HTTP istekleri

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/http-requests	oku	HTTP isteklerini listele
YAYIN	/api/v1/http-requests	yaz	Bir tane oluştur
AL	/api/v1/http-requests/:id	oku	Bir tane al
PUT / PATCH	/api/v1/http-requests/:id	yaz	Birinci güncelleme
SİL	/api/v1/http-requests/:id	yaz	Birini sil
YAYIN	/api/v1/http-requests/:id/test	yürütmek	Gerçek hedefe karşı çalıştırın

List, e-posta şablonlarıyla aynı page, limit ve q parametrelerini kabul eder.

url hedef adresi, http:// veya https:// şeklinde olmalıdır. Kaydederken diğer şemalar reddedilir.

Başlığa veya gövdeye doğrudan yazılan kimlik bilgileri, her yanıtta maskelenir. {{ secrets.KEY }} şeklinde referans verilen değerler, referansın kendisi hassas olmadığı için yazıldığı şekliyle döndürülür.

Tarihçe ve istatistikler

Hem e-posta gönderimlerini hem de HTTP isteklerini kapsar.

Yöntem	Yol	Seviye	Amaç
AL	/api/v1/history	oku	Yürütme listesi
AL	/api/v1/history/:id	oku	İstek ve yanıt verilerini içeren tek bir yürütme elde edin
AL	/api/v1/stats	oku	Toplamlar ve başarı oranı

History, tek bir düzen veya isteğe göre filtreleme yapmak için page, limit (en fazla 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) ve actionConfigId parametrelerini kabul eder.

SKIPPED, alıcılarının tamamının abonelikten çıkmış olduğu bir pazarlama e-postasıdır: hiçbir şey gönderilmemiştir, kota kullanılmamıştır ve başarı oranına dahil edilmez.

actionType değeri tam olarak EMAIL veya HTTP_REQUEST olmalıdır. Tanınmayan bir değer reddedilmez, göz ardı edilir; dolayısıyla yazım hatası durumunda hata mesajı yerine tüm veriler döndürülür.

Stats, days değerini kabul eder (varsayılan 30, en fazla 365).

Durum kodları

Kod	Anlamı
200	Başarı
201	Oluşturuldu
400	İstek biçiminde bir hata var veya doğrulama başarısız oldu. error, alanın adını belirtir; örneğin, subject: required
401	Eksik, hatalı biçimlendirilmiş veya iptal edilmiş API anahtarı
403	Anahtar geçerli ancak bu uç nokta için seviyesi çok düşük
404	Bulunamadı veya başka bir mağazaya ait
405	Bu yol için yanlış yöntem
409	Kayıt hâlâ kullanımda olduğu için (dosya silme) veya GitHub bağlantısı kurulamadığı için (GitHub sürümleri) reddedildi
429	Hız sınırlaması uygulanmaktadır - aşağıya bakınız
502	İstek çalıştırıldı, ancak üçüncü taraf hedefi başarısız oldu

Başka bir mağazaya ait bir kayıt, 403 yerine 404 hatası döndürüyor; bu nedenle API, bir kimliğin başka bir yerde mevcut olup olmadığını hiçbir zaman doğrulamıyor.

Hız sınırları

Her biri tuş başına olmak üzere iki ayrı bütçe:

• Tüm uç noktalarda 60 saniye başına 300 istek.
• Bunun yanı sıra, saatte 60 çağrı gerçekleştirilir; bu çağrılar POST /api/v1/http-requests/:id/test adresini kapsar.

Her iki sınırın da aşılması durumunda, açıklayıcı bir error mesajıyla birlikte 429 hatası döndürülür. Yürütme bütçesi kasıtlı olarak kısıtlı tutulmuştur: Bir ödeme sağlayıcısına sürekli istek gönderen kontrolsüz bir döngü, yavaş çalışan bir komut dosyasından çok daha ciddi bir hatadır.

Bütçeler mağaza başına değil, anahtar başına belirlenir; dolayısıyla bir entegrasyonun bütçesi, başka bir entegrasyonun bütçesini tüketemez.