Panduan integrasi Shopify

Tajo menghubungkan Shopify ke Brevo di dua tempat. Aplikasi Shopify Tajo mengubah webhook Shopify menjadi penulisan ke Brevo begitu webhook tiba. Aturan sinkronisasi, yang dibangun agen dan disetujui seseorang, memindahkan record ke Brevo sesuai jadwal. Halaman ini membahas keduanya, lalu tool Shopify yang disediakan Tajo melalui MCP.

Prasyarat

Sebelum memulai integrasi, pastikan Anda memiliki:

• Toko Shopify pada paket apa pun (Basic, Shopify, Advanced, atau Plus)
• Akun Tajo (Tajo berada dalam akses awal)
• Akun Brevo, tujuan sinkronisasi
• Akses admin ke toko Shopify Anda

Langkah 1: Hubungkan toko Shopify Anda

Tajo berada dalam akses awal. Aplikasi Shopify tidak terdaftar di Shopify App Store, dan tidak ada tautan pemasangan mandiri. Hubungi tim untuk penyiapan. Setelah ruang kerja Tajo Anda siap:

1. Di Tajo, buka Connections.
2. Masukkan domain myshopify.com toko Anda dan pilih Connect Shopify. Shopify menampilkan cakupan akses yang diminta Tajo dan mengembalikan Anda ke Tajo setelah Anda menyetujuinya.
3. Periksa kegunaan setiap cakupan akses, dan apa yang ditulis Tajo kembali ke Shopify, di Penjelasan izin Shopify.

Langkah 2: Apa yang dikirim aplikasi Shopify Tajo ke Brevo

Aplikasi memverifikasi setiap webhook Shopify, menyimpannya, memasukkannya ke antrean, dan langsung memprosesnya. Topik pelanggan dan produk menunggu sekitar empat detik terlebih dahulu. Tidak ada jendela batch. Job yang gagal dicoba ulang dengan backoff.

Topik webhook

Aplikasi Shopify Tajo berlangganan topik webhook Shopify berikut:

Webhook privasi wajib Shopify (permintaan data pelanggan, penghapusan data pelanggan, penghapusan data toko) juga ditangani. Aplikasi tidak berlangganan carts/*. Keranjang yang ditinggalkan berasal dari topik checkouts/*.

Yang sampai di Brevo:

Aplikasi tidak menambahkan tombol “Notify me” ke tema Anda. Permintaan pemberitahuan stok kembali harus berasal dari storefront Anda, misalnya dari tombol yang Anda tambahkan.

Data yang sudah ada

Saat dipasang, aplikasi mengimpor pelanggan Anda yang sudah ada sebagai kontak Brevo. Sinkronisasi historis penuh dimulai dari halaman sinkronisasi aplikasi. Pada paket berbayar, aplikasi juga mengimpor produk, koleksi, perusahaan, dan pesanan.

Langkah 3: Bangun aturan sinkronisasi dengan agen

Aturan sinkronisasi adalah definisi deklaratif dari satu sinkronisasi: resource sumber, aksi Brevo, pemetaan field, dan filter. Anda tidak menulisnya secara manual. Anda menjelaskannya, agen membangunnya, dan seseorang menyetujuinya.

1. Di Tajo, buka Agents dan minta sinkronisasinya kepada Brevo Integration Architect dalam bahasa sehari-hari. Misalnya: “Kirim pelanggan Shopify yang menyetujui pemasaran email ke Brevo sebagai kontak.”
2. Agen memeriksa konektor Shopify. Sampelnya mengembalikan nama dan tipe field, tidak pernah nilai pelanggan.
3. Agen mengusulkan aturan dengan pemetaan field dan filter, lalu memvalidasi pemetaan field terhadap aksi Brevo dan menjalankan dry run pada draf. Kedua langkah itu tidak membaca record pelanggan.
4. Agen menyimpan aturan sebagai draf. Anda juga dapat memulai dari template di Connections > Syncs and mappings > New sync from template.
5. Request publish approval menjalankan pratinjau terhadap toko Anda. Pratinjau membaca paling banyak 10 record, tidak menulis apa pun ke Brevo, dan tidak menggeser kursor. Pratinjau hanya mencatat jumlah: record yang diambil, yang memenuhi syarat, yang dipetakan, dan yang ditolak filter, ditambah error pemetaan. Jika pratinjau gagal, tidak ada permintaan persetujuan yang dibuat.
6. Seseorang menyetujui permintaan itu di halaman Approvals, dengan alasan tertulis. Persetujuan terikat pada digest SHA-256 dari aturan tersebut dan kedaluwarsa setelah 30 menit. Halaman aturan kemudian menampilkan Publish approved version.

Mengedit aturan yang sudah dipublikasikan mengembalikannya ke draf. Aturan harus melewati pratinjau dan persetujuan lagi sebelum berjalan kembali.

Contoh aturan nyata

Ini adalah template Shopify customers -> Brevo contacts sebagaimana didefinisikan Tajo:

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)",

Filter itu adalah pemeriksaan persetujuan pemasaran. Tajo menurunkan kedua nilainya dari email_marketing_consent.state milik Shopify, atau dari flag lama accepts_marketing. Aturan yang menulis kontak ke Brevo tidak dapat dipublikasikan tanpa filter ini. Template Shopify lainnya, Shopify orders → Brevo orders, mencatat pesanan di Brevo untuk pembeli yang menyetujui pemasaran saat checkout.

Kapan aturan berjalan

• Aturan sinkronisasi kontak berjalan setiap 15 menit secara default. Setiap run dimulai dari kursor aturan.
• Halaman aturan yang aktif memiliki tombol Test run (1 batch).
• Aturan Shopify orders → Brevo orders yang aktif dan sudah dipublikasikan juga berjalan setiap 15 menit. Run terjadwal pertamanya dimulai beberapa menit sebelum saat itu dan tidak mengirim pesanan yang lebih lama. Setiap run berikutnya mengirim pesanan yang diperbarui sejak run sebelumnya.
• Pesanan lama masuk ke Brevo hanya saat Anda menjalankan aturan sendiri: dengan Test run (1 batch), atau dengan meminta agen Sync Operator menjalankannya.
• Aturan pesanan berjalan sesuai jadwal hanya dengan filter opt-in pemasaran pembeli dari template. Aturan yang filternya sudah diedit hanya berjalan saat Anda memulainya.
• Setelah lima run gagal berturut-turut, aturan menjeda dirinya sendiri dan halamannya menampilkan error terakhir. Perbaiki penyebabnya, lalu publikasikan lagi.

Setiap run tercantum di riwayat run aturan, dengan jumlah record yang dibaca, ditulis, dan gagal, serta durasinya.

Apa yang dibaca dan ditulis konektor Shopify

Aturan sinkronisasi hanya menulis ke tujuan, dalam hal ini Brevo. Aturan tidak pernah menulis ke Shopify.

Aplikasi Shopify Tajo meminta 12 cakupan akses dan melakukan sedikit penulisan ke Shopify, seperti opt-out persetujuan pemasaran dan tag loyalitas. Penjelasan izin Shopify mencantumkan setiap cakupan akses dan setiap penulisan, beserta pemicunya.

Agen dan host MCP menjangkau toko melalui konektor Shopify:

Konektor juga mendeklarasikan penyesuaian inventaris. Penyesuaian ini memerlukan cakupan akses write_inventory, yang tidak diminta oleh aplikasi Shopify Tajo.

Langkah 4: Gunakan tool Shopify melalui MCP

Tajo menyediakan konektor Shopify sebagai server MCP di https://alto.tajo.io/mcp/connectors/shopify. Tambahkan ke Claude Code:

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

Host menemukan server OAuth Tajo dan membuka halaman masuk Tajo. Akses terbatas untuk akun akses awal. Server menyediakan 12 tool:

Pemecahan masalah

• Kontak tidak muncul di Brevo: lihat kontak tidak ada di Brevo.
• Aturan tidak berjalan, atau menjeda dirinya sendiri: lihat data tidak tersinkron.

Langkah berikutnya

• Memahami sinkronisasi data, cara kerja aturan sinkronisasi
• Penjelasan izin Shopify, setiap cakupan akses dan setiap penulisan
• Shopify + Brevo, panduan integrasinya
• Hubungi tim untuk penyiapan