Shopify انٹیگریشن گائیڈ

Tajo، Shopify کو Brevo سے دو جگہوں پر جوڑتا ہے۔ Tajo کی Shopify ایپ Shopify کے webhooks کو ان کے آتے ہی Brevo رائٹس میں بدلتی ہے۔ sync rules، جنہیں ایک ایجنٹ بناتا ہے اور ایک شخص منظور کرتا ہے، ریکارڈز کو ایک شیڈول پر Brevo میں منتقل کرتے ہیں۔ یہ صفحہ دونوں کا احاطہ کرتا ہے، پھر ان Shopify ٹولز کا جو Tajo، MCP پر پیش کرتا ہے۔

پیشگی شرائط

انٹیگریشن شروع کرنے سے پہلے یقینی بنائیں کہ آپ کے پاس یہ موجود ہیں:

• کسی بھی پلان (Basic، Shopify، Advanced یا Plus) پر Shopify اسٹور
• Tajo اکاؤنٹ (Tajo early access میں ہے)
• Brevo اکاؤنٹ، سنک کی منزل
• اپنے Shopify اسٹور تک ایڈمن رسائی

مرحلہ 1: اپنا Shopify اسٹور جوڑیں

Tajo early access میں ہے۔ Shopify ایپ Shopify App Store میں درج نہیں ہے، اور خود سے انسٹال کرنے کا کوئی لنک نہیں ہے۔ سیٹ اپ کے لیے ٹیم سے رابطہ کریں۔ جب آپ کا Tajo ورک اسپیس تیار ہو جائے:

1. Tajo میں Connections کھولیں۔
2. اپنے اسٹور کا myshopify.com ڈومین درج کریں اور Connect Shopify منتخب کریں۔ Shopify وہ اسکوپس دکھاتا ہے جو Tajo طلب کرتا ہے، اور آپ کے منظور کرنے پر آپ کو Tajo میں واپس بھیج دیتا ہے۔
3. ہر اسکوپ کس کام کے لیے ہے، اور Tajo Shopify میں واپس کیا لکھتا ہے، یہ Shopify اجازتوں کی وضاحت میں دیکھیں۔

مرحلہ 2: Tajo کی Shopify ایپ Brevo کو کیا بھیجتی ہے

ایپ ہر Shopify webhook کی تصدیق کرتی ہے، اسے محفوظ کرتی ہے، قطار میں لگاتی ہے اور فوراً پروسیس کرتی ہے۔ گاہک اور پروڈکٹ کے topics پہلے تقریباً چار سیکنڈ انتظار کرتے ہیں۔ کوئی بیچ ونڈو نہیں ہے۔ ناکام جاب کو backoff کے ساتھ دوبارہ آزمایا جاتا ہے۔

Webhook موضوعات

Tajo Shopify ایپ ان Shopify webhook موضوعات کو سبسکرائب کرتی ہے:

Shopify کے لازمی پرائیویسی webhooks (کسٹمر ڈیٹا کی درخواست، کسٹمر ریڈیکٹ، شاپ ریڈیکٹ) بھی ہینڈل کیے جاتے ہیں۔ ایپ carts/* کو سبسکرائب نہیں کرتی۔ چھوڑے گئے کارٹس checkouts/* موضوعات سے آتے ہیں۔

Brevo میں کیا پہنچتا ہے:

ایپ آپ کی تھیم میں “Notify me” بٹن شامل نہیں کرتی۔ دوبارہ اسٹاک کی درخواست آپ کے اسٹور فرنٹ سے آنی چاہیے، مثلاً آپ کے شامل کردہ کسی بٹن سے۔

موجودہ ڈیٹا

انسٹال ہونے پر ایپ آپ کے موجودہ گاہکوں کو Brevo کانٹیکٹس کے طور پر امپورٹ کرتی ہے۔ مکمل تاریخی سنک ایپ کے سنک صفحے سے شروع کیا جاتا ہے۔ ادائیگی والے پلانز پر یہ پروڈکٹس، کلیکشنز، کمپنیاں اور آرڈرز بھی امپورٹ کرتی ہے۔

مرحلہ 3: ایجنٹ کے ساتھ sync rule بنائیں

sync rule ایک سنک کی declarative تعریف ہے: ایک سورس ریسورس، ایک Brevo ایکشن، ایک فیلڈ میپ اور ایک فلٹر۔ آپ اسے ہاتھ سے نہیں لکھتے۔ آپ اسے بیان کرتے ہیں، ایک ایجنٹ اسے بناتا ہے، اور ایک شخص اسے منظور کرتا ہے۔

1. Tajo میں Agents کھولیں اور Brevo Integration Architect سے سادہ زبان میں سنک مانگیں۔ مثلاً: “جن Shopify گاہکوں نے ای میل مارکیٹنگ قبول کی ہے انہیں Brevo میں کانٹیکٹس کے طور پر بھیجیں۔”
2. ایجنٹ Shopify کنیکٹر کا معائنہ کرتا ہے۔ اس کا نمونہ فیلڈز کے نام اور اقسام واپس کرتا ہے، گاہکوں کی ویلیوز کبھی نہیں۔
3. وہ فیلڈ میپ اور ایک فلٹر کے ساتھ ایک قاعدہ تجویز کرتا ہے، پھر فیلڈ میپ کی Brevo کے ایکشن کے مقابلے میں توثیق کرتا ہے اور ڈرافٹ کا ڈرائی رن کرتا ہے۔ ان میں سے کوئی مرحلہ گاہکوں کے ریکارڈز نہیں پڑھتا۔
4. وہ قاعدے کو ڈرافٹ کے طور پر محفوظ کرتا ہے۔ آپ Connections > Syncs and mappings > New sync from template کے تحت کسی ٹیمپلیٹ سے بھی شروع کر سکتے ہیں۔
5. Request publish approval آپ کے اسٹور پر ایک پیش نظارہ چلاتا ہے۔ یہ زیادہ سے زیادہ 10 ریکارڈز پڑھتا ہے، Brevo میں کچھ نہیں لکھتا اور cursor کو آگے نہیں بڑھاتا۔ یہ صرف گنتی ریکارڈ کرتا ہے: کھینچے گئے، اہل، میپ کیے گئے اور فلٹر سے رد کیے گئے ریکارڈز، نیز میپنگ کی خرابیاں۔ اگر پیش نظارہ ناکام ہو جائے تو کوئی منظوری کی درخواست نہیں بنتی۔
6. ایک شخص Approvals صفحے پر تحریری وجہ کے ساتھ درخواست منظور کرتا ہے۔ منظوری قاعدے کے SHA-256 digest سے منسلک ہوتی ہے اور 30 منٹ بعد ختم ہو جاتی ہے۔ پھر قاعدے کا صفحہ Publish approved version دکھاتا ہے۔

کسی شائع شدہ قاعدے میں ترمیم اسے ڈرافٹ میں واپس لے جاتی ہے۔ دوبارہ چلنے سے پہلے وہ پھر سے پیش نظارہ اور منظوری سے گزرتا ہے۔

ایک حقیقی قاعدہ

یہ Shopify customers -> Brevo contacts ٹیمپلیٹ ہے، جیسا کہ 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)",

فلٹر ہی رضامندی کی جانچ ہے۔ Tajo دونوں ویلیوز Shopify کے email_marketing_consent.state سے، یا پرانے accepts_marketing فلیگ سے اخذ کرتا ہے۔ جو قاعدہ Brevo میں کانٹیکٹس لکھتا ہے وہ اس کے بغیر شائع نہیں ہو سکتا۔ دوسرا Shopify ٹیمپلیٹ، Shopify orders → Brevo orders، ان خریداروں کے آرڈرز Brevo میں ریکارڈ کرتا ہے جنہوں نے چیک آؤٹ پر مارکیٹنگ قبول کی۔

قاعدہ کب چلتا ہے

• کانٹیکٹ sync rules بطور ڈیفالٹ ہر 15 منٹ بعد چلتے ہیں۔ ہر رن قاعدے کے cursor سے شروع ہوتا ہے۔
• کسی فعال قاعدے کے صفحے پر Test run (1 batch) بٹن ہوتا ہے۔
• فعال اور شائع شدہ Shopify orders → Brevo orders قاعدہ بھی ہر 15 منٹ بعد چلتا ہے۔ اس کا پہلا شیڈول شدہ رن اس لمحے سے چند منٹ پہلے شروع ہوتا ہے اور اس سے پرانے آرڈرز نہیں بھیجتا۔ اس کے بعد ہر رن پچھلے رن کے بعد سے اپ ڈیٹ ہونے والے آرڈرز بھیجتا ہے۔
• پرانے آرڈرز Brevo تک صرف تب پہنچتے ہیں جب آپ خود قاعدہ چلائیں: Test run (1 batch) سے، یا Sync Operator ایجنٹ سے اسے چلانے کو کہہ کر۔
• آرڈرز کا قاعدہ شیڈول پر صرف ٹیمپلیٹ کے خریدار مارکیٹنگ opt-in فلٹر کے ساتھ چلتا ہے۔ جس قاعدے کا فلٹر تبدیل کیا گیا ہو وہ صرف تب چلتا ہے جب آپ اسے شروع کریں۔
• پانچ لگاتار ناکام رنز کے بعد قاعدہ خود رک جاتا ہے اور اس کا صفحہ آخری خرابی دکھاتا ہے۔ وجہ حل کریں، پھر دوبارہ شائع کریں۔

ہر رن قاعدے کی run history میں پڑھے، لکھے اور ناکام ریکارڈز اور دورانیے کے ساتھ درج ہوتا ہے۔

Shopify کنیکٹر کیا پڑھتا اور لکھتا ہے

sync rules صرف منزل میں لکھتے ہیں، یہاں Brevo میں۔ وہ Shopify میں کبھی نہیں لکھتے۔

Tajo کی Shopify ایپ 12 اسکوپس طلب کرتی ہے اور Shopify میں رائٹس کی ایک مختصر فہرست انجام دیتی ہے، جیسے رضامندی کی منسوخی اور لائلٹی ٹیگز۔ Shopify اجازتوں کی وضاحت ہر اسکوپ اور ہر رائٹ کو، اسے ٹرگر کرنے والی چیز کے ساتھ، درج کرتی ہے۔

ایجنٹس اور MCP ہوسٹس Shopify کنیکٹر کے ذریعے اسٹور تک پہنچتے ہیں:

کنیکٹر ایک انوینٹری ایڈجسٹمنٹ بھی declare کرتا ہے۔ اس کے لیے write_inventory اسکوپ درکار ہے، جو Tajo کی Shopify ایپ طلب نہیں کرتی۔

مرحلہ 4: MCP پر Shopify ٹولز استعمال کریں

Tajo، Shopify کنیکٹر کو https://alto.tajo.io/mcp/connectors/shopify پر MCP سرور کے طور پر پیش کرتا ہے۔ اسے Claude Code میں شامل کریں:

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

ہوسٹ Tajo کا OAuth سرور تلاش کرتا ہے اور Tajo کا سائن ان کھولتا ہے۔ رسائی early access اکاؤنٹس تک محدود ہے۔ سرور 12 ٹولز پیش کرتا ہے:

مسائل کا حل

• کانٹیکٹس Brevo میں ظاہر نہیں ہو رہے: دیکھیں Brevo میں کانٹیکٹس غائب۔
• کوئی قاعدہ جو نہیں چلتا، یا خود رک گیا: دیکھیں ڈیٹا سنک نہیں ہو رہا۔

اگلے اقدامات

• ڈیٹا سنک کو سمجھنا، sync rules کیسے کام کرتے ہیں
• Shopify اجازتوں کی وضاحت، ہر اسکوپ اور ہر رائٹ
• Shopify + Brevo، انٹیگریشن گائیڈ
• سیٹ اپ کے لیے ٹیم سے رابطہ کریں