Shopify entegrasyon rehberi

Tajo, Shopify’ı Brevo’ya iki noktada bağlar. Tajo Shopify uygulaması, Shopify webhook’larını geldikleri anda Brevo yazmalarına dönüştürür. Bir agent’ın oluşturduğu ve bir kişinin onayladığı senkronizasyon kuralları ise kayıtları bir zamanlamaya göre Brevo’ya taşır. Bu sayfa önce ikisini, ardından Tajo’nun MCP üzerinden sunduğu Shopify araçlarını anlatır.

Ön koşullar

Entegrasyona başlamadan önce şunlara sahip olduğunuzdan emin olun:

• Herhangi bir pakette (Basic, Shopify, Advanced veya Plus) bir Shopify mağazası
• Tajo hesabı (Tajo erken erişim aşamasındadır)
• Senkronizasyonun hedefi olan bir Brevo hesabı
• Shopify mağazanıza yönetici erişimi

Adım 1: Shopify mağazanızı bağlayın

Tajo erken erişim aşamasındadır. Shopify uygulaması Shopify App Store’da listelenmiyor ve kendi kendine yükleme bağlantısı yok. Kurulum için ekiple iletişime geçin. Tajo çalışma alanınız hazır olduğunda:

1. Tajo’da Connections’ı açın.
2. Mağazanızın myshopify.com alan adını girin ve Connect Shopify’ı seçin. Shopify, Tajo’nun istediği kapsamları gösterir ve onayladığınızda sizi Tajo’ya geri döndürür.
3. Her kapsamın ne için olduğunu ve Tajo’nun Shopify’a neleri geri yazdığını Shopify izinlerinin açıklaması sayfasında kontrol edin.

Adım 2: Tajo Shopify uygulaması Brevo’ya neler gönderir

Uygulama her Shopify webhook’unu doğrular, saklar, kuyruğa alır ve hemen işler. Müşteri ve ürün konuları önce yaklaşık dört saniye bekler. Toplu iş penceresi yoktur. Başarısız bir iş, geri çekilme (backoff) ile yeniden denenir.

Webhook konuları

Tajo Shopify uygulaması şu Shopify webhook konularına abone olur:

Shopify’ın zorunlu gizlilik webhook’ları (müşteri verisi talebi, müşteri silme, mağaza silme) de işlenir. Uygulama carts/* konularına abone olmaz. Terk edilen sepetler checkouts/* konularından gelir.

Brevo’ya ulaşanlar:

Uygulama temanıza “Notify me” düğmesi eklemez. Yeniden stok talebinin mağaza vitrininizden gelmesi gerekir, örneğin sizin eklediğiniz bir düğmeden.

Mevcut veriler

Yükleme sırasında uygulama mevcut müşterilerinizi Brevo kişileri olarak içe aktarır. Tam bir geçmiş senkronizasyonu, uygulamanın senkronizasyon sayfasından başlatılır. Ücretli planlarda ürünleri, koleksiyonları, şirketleri ve siparişleri de içe aktarır.

Adım 3: Agent ile bir senkronizasyon kuralı oluşturun

Senkronizasyon kuralı, tek bir senkronizasyonun bildirimsel tanımıdır: bir kaynak nesnesi (source resource), bir Brevo eylemi, bir alan eşlemesi ve bir filtre. Onu elle yazmazsınız. Siz tarif edersiniz, bir agent oluşturur ve bir kişi onaylar.

1. Tajo’da Agents bölümünü açın ve Brevo Integration Architect’ten senkronizasyonu sade bir dille isteyin. Örneğin: “E-posta pazarlamasını kabul eden Shopify müşterilerini Brevo’ya kişi olarak gönder.”
2. Agent, Shopify bağlayıcısını inceler. Örneği alan adlarını ve türlerini döndürür, müşteri değerlerini asla döndürmez.
3. Alan eşlemesi ve bir filtre içeren bir kural önerir, ardından alan eşlemesini Brevo’nun eylemine göre doğrular ve taslağı deneme olarak çalıştırır (dry run). Bu adımların hiçbiri müşteri kayıtlarını okumaz.
4. Kuralı taslak olarak kaydeder. Connections > Syncs and mappings > New sync from template altındaki bir şablonla da başlayabilirsiniz.
5. Request publish approval, mağazanıza karşı bir önizleme çalıştırır. Önizleme en fazla 10 kayıt okur, Brevo’ya hiçbir şey yazmaz ve imleci (cursor) ilerletmez. Yalnızca sayıları kaydeder: çekilen, uygun, eşlenen ve filtre tarafından reddedilen kayıtlar ile eşleme hataları. Önizleme başarısız olursa onay talebi oluşturulmaz.
6. Bir kişi talebi Approvals sayfasında yazılı bir gerekçeyle onaylar. Onay, kuralın SHA-256 özetine (digest) bağlıdır ve 30 dakika sonra sona erer. Ardından kuralın sayfasında Publish approved version görünür.

Yayımlanmış bir kuralı düzenlemek onu taslağa döndürür. Kural yeniden çalışmadan önce önizleme ve onaydan tekrar geçer.

Gerçek bir kural

Tajo’nun tanımladığı haliyle Shopify customers -> Brevo contacts şablonu budur:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Filtre, rıza kontrolüdür. Tajo her iki değeri de Shopify’ın email_marketing_consent.state alanından veya daha eski accepts_marketing bayrağından türetir. Brevo’ya kişi yazan bir kural, bu filtre olmadan yayımlanamaz. Diğer Shopify şablonu olan Shopify orders → Brevo orders, ödeme sırasında pazarlamayı kabul eden alıcıların siparişlerini Brevo’ya kaydeder.

Bir kural ne zaman çalışır

• Kişi senkronizasyon kuralları varsayılan olarak 15 dakikada bir çalışır. Her çalıştırma kuralın imlecinden başlar.
• Etkin bir kuralın sayfasında Test run (1 batch) düğmesi bulunur.
• Etkin ve yayımlanmış bir Shopify orders → Brevo orders kuralı da 15 dakikada bir çalışır. İlk zamanlanmış çalıştırması o andan birkaç dakika önce başlar ve daha eski siparişleri göndermez. Sonraki her çalıştırma, bir önceki çalıştırmadan bu yana güncellenen siparişleri gönderir.
• Geçmiş siparişler Brevo’ya yalnızca kuralı kendiniz çalıştırdığınızda ulaşır: Test run (1 batch) ile ya da Sync Operator agent’ından kuralı çalıştırmasını isteyerek.
• Bir sipariş kuralı, zamanlamaya göre yalnızca şablonun alıcı pazarlama rızası filtresiyle çalışır. Filtresi düzenlenmiş bir kural yalnızca siz başlattığınızda çalışır.
• Arka arkaya beş başarısız çalıştırmadan sonra kural kendini duraklatır ve sayfasında son hatayı gösterir. Nedeni giderin, ardından yeniden yayımlayın.

Her çalıştırma, okunan, yazılan ve başarısız olan kayıt sayıları ve süresiyle birlikte kuralın çalıştırma geçmişinde listelenir.

Shopify bağlayıcısı neleri okur ve yazar

Senkronizasyon kuralları yalnızca hedefe, burada Brevo’ya yazar. Shopify’a asla yazmazlar.

Tajo Shopify uygulaması 12 kapsam ister ve Shopify’a, rıza iptalleri ve sadakat etiketleri gibi kısa bir yazma listesi yapar. Shopify izinlerinin açıklaması, her kapsamı ve her yazmayı, onu neyin tetiklediğiyle birlikte listeler.

Agent’lar ve MCP ana bilgisayarları mağazaya Shopify bağlayıcısı üzerinden ulaşır:

Bağlayıcı ayrıca bir stok düzeltmesi tanımlar. Bu, Tajo Shopify uygulamasının istemediği write_inventory kapsamını gerektirir.

Adım 4: Shopify araçlarını MCP üzerinden kullanın

Tajo, Shopify bağlayıcısını https://alto.tajo.io/mcp/connectors/shopify adresinde bir MCP sunucusu olarak sunar. Claude Code’a ekleyin:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Ana bilgisayar Tajo’nun OAuth sunucusunu keşfeder ve Tajo giriş ekranını açar. Erişim, erken erişim hesaplarıyla sınırlıdır. Sunucu 12 araç sunar:

Sorun giderme

• Kişiler Brevo’da görünmüyor: bkz. Brevo’da eksik kişiler.
• Çalışmayan veya kendini duraklatan bir kural: bkz. veriler senkronize olmuyor.

Sonraki adımlar

• Veri senkronizasyonunu anlama, senkronizasyon kurallarının nasıl davrandığı
• Shopify izinlerinin açıklaması, her kapsam ve her yazma
• Shopify + Brevo, entegrasyon kılavuzu
• Kurulum için ekiple iletişime geçin