توثيق المطورين

البداية

أنشئ مفتاح ربط من لوحة التحكم ← المطورون. يظهر المفتاح مرة واحدة، ويبدأ بـ isht_live_. أرسله في كل طلب:

Authorization: Bearer isht_live_…

صلاحيات المفاتيح

fullكل شيء، بما فيه الإرسال والحذف.
readالقراءة فقط: القوائم والتقارير والمعاينة.
signupsإضافة العملاء فقط (add_contact)، لنماذج التسجيل في موقعك.

ربط مساعد ذكي (MCP)

خادم MCP يعطي المساعد الذكي أدوات بأسماء الإجراءات نفسها ومدخلاتها نفسها. المساعد لا يرى إلا الأدوات التي تسمح بها صلاحية المفتاح، وأدوات الإرسال والحذف معلَّمة بأنها لا يمكن التراجع عنها، فيطلب المساعد موافقتك قبلها.

العنوان

https://ishtaqna.com/mcp

طريقة الربط في كل برنامج

Claude Code

في الطرفية:

claude mcp add --transport http ishtaqna https://ishtaqna.com/mcp \
  --header "Authorization: Bearer isht_live_…"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "ishtaqna": {
      "url": "https://ishtaqna.com/mcp",
      "headers": {
        "Authorization": "Bearer isht_live_…"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "ishtaqna": {
      "type": "http",
      "url": "https://ishtaqna.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ishtaqna-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "ishtaqna-key",
      "description": "Ishtaqna API key",
      "password": true
    }
  ]
}

Codex

~/.codex/config.toml، مع المفتاح في متغير البيئة ISHTAQNA_API_KEY:

[mcp_servers.ishtaqna]
url = "https://ishtaqna.com/mcp"
bearer_token_env_var = "ISHTAQNA_API_KEY"

Claude على الويب وClaude Desktop يربطان الخوادم البعيدة عبر OAuth فقط، وهذا قادم لاحقاً. حتى ذلك الحين استخدم Claude Code أو Cursor أو VS Code أو Codex.

جرّب أن تطلب

كم عميلاً عندي في الرياض لم نراسلهم بعد؟
أنشئ حملة «اشتقنا لك» لكبار العملاء، واكتب عنواناً قصيراً بلهجة سعودية، ثم أرسل لي نسخة تجريبية.
ما نتائج آخر حملة؟ وما الرابط الذي نُقر أكثر؟

الأمان

كل أداة تمر بـ runAction نفسه الذي تستخدمه لوحة التحكم، فحدود الباقة والإيقاف التلقائي ومراجعة المحتوى تنطبق على المساعد كما تنطبق عليك.
أدوات الإرسال (send_test_email وsend_campaign وresume_campaign) والحذف لا يمكن التراجع عنها، وتطلب من المساعد أن يأخذ موافقتك الصريحة أولاً.
أسماء العملاء والعناوين والردود بيانات كتبها غيرك، ويُطلب من المساعد ألا يتبع أي تعليمات بداخلها.
كل استدعاء يُسجَّل في سجل التدقيق مع via: mcp، ويمكنك إلغاء المفتاح في أي وقت.

REST API

كل الطلبات JSON على /api/v1. الحد 300 طلب في الدقيقة لكل مفتاح. القوائم الطويلة تعيد nextCursor، أرسله في cursor لجلب الصفحة التالية.

curl https://ishtaqna.com/api/v1/campaigns \
  -H "Authorization: Bearer isht_live_…" \
  -H "Content-Type: application/json" \
  -d '{"template": "win_back"}'

رموز الأخطاء

كل خطأ بالشكل { "error": { "code", "message" } }. الرموز ثابتة ولا يتغير معناها أبداً، فابنِ منطقك عليها لا على النص.

الرمز	HTTP	المعنى
unauthorized	401	مفتاح الربط أو الجلسة غير صالحة أو منتهية.
forbidden	403	صلاحيتك لا تسمح بهذا الإجراء.
not_found	404	غير موجود في هذه المنشأة.
validation_failed	400	البيانات المدخلة غير صحيحة.
conflict	409	الحالة الحالية لا تسمح بهذا الإجراء.
revision_conflict	409	تم تعديله بعد فتحك له. حدّث الصفحة وحاول مرة أخرى.
rate_limited	429	طلبات كثيرة. انتظر قليلاً ثم حاول مرة أخرى.
subscription_required	402	هذا يتطلب اشتراكاً فعّالاً.
plan_limit_emails	402	لم يتبقَّ رصيد كافٍ من الإيميلات في باقتك هذا الشهر.
plan_limit_contacts	402	وصلت إلى الحد الأقصى لعدد العملاء في باقتك.
plan_limit_brands	402	وصلت إلى الحد الأقصى لعدد العلامات التجارية في باقتك.
credit_insufficient	402	الرصيد غير كافٍ لإرسال الرسائل.
account_blocked	403	تم إيقاف المنشأة مؤقتاً. يمكنك الاطلاع والإيقاف والدفع فقط.
sender_not_allowed	422	عنوان المرسل غير مسموح.
send_check_failed	422	فشل أحد فحوصات ما قبل الإرسال.
no_recipients	422	لا يوجد مستلمون.
channel_not_connected	422	هذه القناة غير مربوطة بعد.
template_not_approved	422	قالب واتساب لم تتم الموافقة عليه بعد.
quiet_hours	422	لا يمكن إرسال رسائل تسويقية في أوقات الهدوء.
sending_disabled	503	لا يوجد مزوّد إرسال مُعدّ، لذلك لا يمكن الإرسال الآن.
unavailable	503	خدمة مطلوبة غير متاحة. حاول لاحقاً.
internal_error	500	حدث خطأ من جهتنا.

مرجع الإجراءات

كل إجراء متاح بثلاث طرق: مسار REST، وأداة MCP بالاسم نفسه، وفي لوحة التحكم.

أوصاف الحقول بالإنجليزية، كما يقرؤها المساعد الذكي في MCP.

المنشأة

عرض المنشأة

قراءة فقط

GET/api/v1/organization·MCP tool: get_organization·Keys: full, read

يعرض المنشأة التي يتبع لها المفتاح أو الجلسة: الاسم والدولة والمنطقة الزمنية والباقة وحدودها.

لا يحتاج مدخلات.

تعديل المنشأة

PATCH/api/v1/organization·MCP tool: update_organization·Keys: full

يغيّر اسم المنشأة أو منطقتها الزمنية أو لغتها. أرسل الحقول التي تريد تغييرها فقط، وتبقى البقية كما هي.

الحقل	النوع	الوصف
name	string	The business name, as customers know it.
timezone	string	IANA time zone used for schedules and quiet hours, e.g. Asia/Riyadh.
locale	"ar" \| "en"	Language of the dashboard and system emails.

صحة الإرسال

قراءة فقط

GET/api/v1/organization/sending-health·MCP tool: get_sending_health·Keys: full, read

يعرض صحة إرسال البريد للمنشأة: نسب الارتداد والبلاغات خلال 30 يوماً مقارنةً بحدود الإيقاف، ومستوى الإرسال، وحصة كل علامة تجارية اليومية في Gmail أثناء التسخين، وعدد العملاء الخاملين والمحظورين.

لا يحتاج مدخلات.

أرقام لوحة التحكم

قراءة فقط

GET/api/v1/organization/stats·MCP tool: get_overview_stats·Keys: full, read

أرقام المنشأة لآخر 7 أو 30 يوماً مقارنةً بالفترة التي قبلها: الرسائل المرسلة والمفتوحة والمنقورة وإلغاء الاشتراك (الحملات والأتمتة، دون التجارب)، وعدد العملاء ومن أُضيف منهم مع سلسلة يومية، وآخر الحملات المرسلة بنسب فتحها، والأرقام نفسها يوماً بيوم، وآخر 12 حدثاً (فتح، ونقر، وإلغاء اشتراك، وطلبات مدفوعة، ومشتركون جدد، واستيراد) لقائمة «آخر ما حدث».

الحقل	النوع	إلزامي	الوصف
days	integer		7 or 30 (default).

حذف الحساب

لا يمكن التراجع

DELETE/api/v1/organization·MCP tool: delete_organization·Keys: full

يحذف المنشأة وكل ما فيها: العملاء والحملات والعلامات والأتمتة وربط المتاجر والمفاتيح والأعضاء. يُقفل الحساب فوراً ويتوقف كل إرسال، وتُمحى البيانات نهائياً بعد 30 يوماً. تبقى سجلات إلغاء الاشتراك بصيغة مشفّرة باتجاه واحد حتى لا نراسل من ألغى اشتراكه مرة أخرى. أرسل اسم المنشأة كما هو، وacknowledged بقيمة true تأكيداً لقراءة صفحة حذف الحساب. لا يمكن التراجع عنه.

الحقل	النوع	إلزامي	الوصف
confirm	string	نعم	The organization's exact name, as a confirmation.
acknowledged	boolean	نعم	true: the owner has read /legal/delete-account and understands the deletion is permanent.

العلامات التجارية

قائمة العلامات التجارية

قراءة فقط

GET/api/v1/brands·MCP tool: list_brands·Keys: full, read

يعرض علامات المنشأة التجارية (محلاتها أو عياداتها أو متاجرها)، الأقدم أولاً، مع عناوين الإرسال.

لا يحتاج مدخلات.

عرض علامة تجارية

قراءة فقط

GET/api/v1/brands/{id}·MCP tool: get_brand·Keys: full, read

يعرض علامة تجارية واحدة بمعرّفها: أسماءها وبيانات الرد وعنوان الإرسال.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

فحص المعرّف المختصر

قراءة فقط

GET/api/v1/brands/slugs/{slug}·MCP tool: check_brand_slug·Keys: full, read

يخبرك هل المعرّف المختصر (slug) متاح. يصبح هذا المعرّف نطاقاً فرعياً للعلامة على نطاق الإرسال المشترك.

الحقل	النوع	إلزامي	الوصف
slug	string	نعم	The slug to check, e.g. alsanabel.

إضافة علامة تجارية

POST/api/v1/brands·MCP tool: create_brand·Keys: full

يضيف علامة تجارية (محلاً أو عيادة أو متجراً) إلى المنشأة. تستطيع الإرسال فوراً من عنوانها المشترك hello@<slug>.<النطاق المشترك>.

الحقل	النوع	إلزامي	الوصف
nameAr	string	نعم	The brand name in Arabic, as customers see it in messages.
nameEn	string		The brand name in English, if it has one.
postalAddress	string		Business address printed in email footers. Emails can't be sent without one.
replyToEmail	string		Where email replies go, e.g. the owner's Gmail.
replyToWhatsapp	string		WhatsApp number for the reply button in emails, in international format.
websiteUrl	string		The brand's website or Instagram page.
logoUrl	string		Square logo, https link.
slug	string		Lowercase letters, digits and dashes, 3 to 40 characters. Default: made from nameEn, or random.

تعديل علامة تجارية

PATCH/api/v1/brands/{id}·MCP tool: update_brand·Keys: full

يغيّر أسماء العلامة أو عنوانها أو بيانات الرد أو موقعها أو شعارها (null يحذف الشعار). أرسل الحقول التي تتغير فقط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
nameAr	string		The brand name in Arabic, as customers see it in messages.
nameEn	string		The brand name in English, if it has one.
postalAddress	string		Business address printed in email footers. Emails can't be sent without one.
replyToEmail	string		Where email replies go, e.g. the owner's Gmail.
replyToWhatsapp	string		WhatsApp number for the reply button in emails, in international format.
websiteUrl	string		The brand's website or Instagram page.
logoUrl	string \| null		Square logo, https link; null removes it.

حذف علامة تجارية

لا يمكن التراجع

DELETE/api/v1/brands/{id}·MCP tool: delete_brand·Keys: full

يحذف العلامة التجارية، فتتوقف حملاتها ويتوقف عنوان إرسالها المشترك. لا يمكن التراجع عنه. لا يمكن حذف آخر علامة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

تخصيص صفحة العلامة

PATCH/api/v1/brands/{id}/page·MCP tool: update_brand_page·Keys: full

يغيّر صفحة الاشتراك العامة للعلامة على <slug>.ishtaqna.com: تشغيلها، وعنوانها ووصفها، ولونها (جاهز أو لون علامتك)، ومظهرها وخلفيتها، وما تطلبه (إيميل أو جوال أو كلاهما، والاسم الأول)، ونص الزر ورسالة الشكر، وعدد المشتركين، والروابط (واتساب، وإنستغرام، وإكس، وتيك توك، وسناب شات، وفيسبوك، وتيليجرام، ويوتيوب، وثريدز، والموقع). أرسل ما يتغير فقط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
enabled	boolean		false hides the page.
headline	string		The big line; the brand name when empty.
description	string		One or two sentences: what subscribers get.
accent	"teal" \| "emerald" \| "sky" \| "indigo" \| "plum" \| "rose" \| "amber" \| "ink"		teal, emerald, sky, indigo, plum, rose, amber or ink.
collect	"email" \| "phone" \| "both"		email, phone or both.
askName	boolean		Ask for a first name.
buttonText	string		The subscribe button text.
thanksText	string		Shown after subscribing.
showCount	boolean		Show the number of subscribers (from 50).
customColor	string		The brand's own color, e.g. #0F766E; empty goes back to accent.
theme	"light" \| "soft" \| "dark"		light, soft (tinted) or dark.
background	"plain" \| "dots" \| "grid" \| "glow" \| "aurora"		plain, dots, grid, glow or aurora.
links	object		Links under the form; send only the ones that change.

تصميم إيميلات العلامة

PATCH/api/v1/brands/{id}/design·MCP tool: update_brand_design·Keys: full

يغيّر شكل إيميلات العلامة: لون الخلفية والنص والأزرار، وزوايا الأزرار والصور، والمحاذاة (يمين أو وسط)، وما يظهر في الأعلى (الشعار أو الاسم أو لا شيء). كل إيميل ترسله العلامة يستخدمه. أرسل ما يتغير فقط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
background	string		The email's background, e.g. #FFFFFF.
text	string		Headings and text, e.g. #171717.
accent	string		Buttons and links, e.g. #0F766E. Button text turns white or black to stay readable.
corners	"none" \| "small" \| "medium" \| "large" \| "full"		Button and image corners: none, small, medium, large or full (round buttons).
align	"right" \| "center"		right: aligned to the start, like a letter. center: centered, like an announcement.
header	"logo" \| "name" \| "none"		What sits at the top: the logo (the name when there's no logo), the name, or nothing.

العملاء

قائمة العملاء

قراءة فقط

GET/api/v1/contacts·MCP tool: list_contacts·Keys: full, read

يعرض عملاء المنشأة، الأحدث أولاً، 50 في الصفحة، مع وسومهم وحالة كل قناة. أعد nextCursor في cursor لجلب الصفحة التالية.

الحقل	النوع	الوصف
search	string	Part of an email, phone number or name.
tag	string	Only contacts with this tag.
city	string	Only contacts in this city.
channel	"email" \| "whatsapp"	Only contacts subscribed (active) on this channel.
segment	string	Only contacts a saved segment picks.
limit	integer	Contacts per page, 50 by default, 100 at most.
cursor	string	nextCursor from the previous page.

عرض عميل

قراءة فقط

GET/api/v1/contacts/{id}·MCP tool: get_contact·Keys: full, read

يعرض عميلاً واحداً بمعرّفه: بياناته ووسومه وحقوله المخصصة وسجل الموافقة وحالة كل قناة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إضافة عميل

POST/api/v1/contacts·MCP tool: add_contact·Keys: full, signups

يضيف عميلاً واحداً، أو يحدّثه إذا كان بريده أو جواله مسجلاً. تُسجَّل الموافقة لكل قناة؛ وإذا كان أساسها غير معروف تبقى القناة «معلّقة» فلا تصله عروض حتى يوافق. يعمل مع مفاتيح «تسجيل العملاء فقط».

الحقل	النوع	الوصف
email	string	Email address. Typos like gmial.com are fixed; role and throwaway inboxes are refused.
phone	string	Phone number in any common format; stored in international format.
firstName	string	First name, used to greet them.
lastName	string	Last or family name.
city	string	City.
tags	string[] \| string	Tags, as a list or comma-separated text.
fields	object	Values for the org's custom fields, by key.
source	string	Where they came from, e.g. website, qr, store. Default: api or dashboard.
consent	object	How each channel's consent was given: signup_form, qr, checkout, in_store, whatsapp_optin or unknown (the default).

تعديل عميل

PATCH/api/v1/contacts/{id}·MCP tool: update_contact·Keys: full

يغيّر اسم العميل أو مدينته أو وسومه أو قيم حقوله المخصصة. أرسل ما يتغير فقط: الوسوم تستبدل وسوم العميل، والحقول تغيّر المفاتيح المرسلة فقط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
firstName	string \| null		First name; null removes it.
lastName	string \| null		Last name; null removes it.
city	string \| null		City; null removes it.
tags	string[] \| string		The contact's tags, replacing the current ones.
fields	object		Custom field values by key; null removes one.

تغيير حالة قناة العميل

PATCH/api/v1/contacts/{id}/channels/{channel}·MCP tool: update_contact_channel·Keys: full

يلغي اشتراك العميل في قناة أو يعيدها فعّالة. إعادة التفعيل تتطلب consent: true، أي تأكيدك أن الشخص طلب ذلك. القنوات المرتدة أو المبلَّغ عنها لا تعود فعّالة أبداً.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
channel	"email" \| "whatsapp"	نعم	email or whatsapp.
status	"active" \| "unsubscribed"	نعم	active or unsubscribed.
consent	boolean		Required (true) to make a channel active: the person asked for it.

وسم العملاء

POST/api/v1/contacts/tag·MCP tool: tag_contacts·Keys: full

يضيف وسوماً إلى العملاء مع إبقاء وسومهم الحالية، لتختارهم الشرائح بالوسم.

الحقل	النوع	إلزامي	الوصف
ids	string[]	نعم	Contact IDs, 1,000 at most.
tags	string[]	نعم	Tags to add, 10 at most.

إزالة وسوم

POST/api/v1/contacts/untag·MCP tool: untag_contacts·Keys: full

يزيل وسوماً من العملاء، وتبقى وسومهم الأخرى كما هي.

الحقل	النوع	إلزامي	الوصف
ids	string[]	نعم	Contact IDs, 1,000 at most.
tags	string[]	نعم	Tags to remove, 10 at most.

حذف عملاء

لا يمكن التراجع

POST/api/v1/contacts/delete·MCP tool: delete_contacts·Keys: full

يحذف العملاء مع بياناتهم وسجلهم. لا يمكن التراجع عنه. العناوين الملغى اشتراكها أو المرتدة أو المبلَّغ عنها تبقى محظورة، فلا تُراسَل أبداً حتى لو استوردت لاحقاً.

الحقل	النوع	إلزامي	الوصف
ids	string[]	نعم	Contact IDs, 1,000 at most.

قائمة الوسوم

قراءة فقط

GET/api/v1/contacts/tags·MCP tool: list_contact_tags·Keys: full, read

يعرض وسوم عملاء المنشأة، الأكثر استخداماً أولاً، مع عدد العملاء لكل وسم (200 وسماً على الأكثر).

لا يحتاج مدخلات.

قائمة الحقول المخصصة

قراءة فقط

GET/api/v1/contacts/fields·MCP tool: list_contact_fields·Keys: full, read

يعرض الحقول المخصصة لعملاء المنشأة، مثل آخر زيارة أو تاريخ الميلاد، مع المفتاح والنوع.

لا يحتاج مدخلات.

إضافة حقل مخصص

POST/api/v1/contacts/fields·MCP tool: create_contact_field·Keys: full

يضيف حقلاً مخصصاً للعملاء، مثل last_visit أو birthday، بحد أقصى 20 حقلاً. التواريخ تُحفظ بصيغة YYYY-MM-DD.

الحقل	النوع	إلزامي	الوصف
key	string	نعم	The field's key, e.g. last_visit.
label	string	نعم	The field's name as owners see it, e.g. آخر زيارة.
type	"text" \| "number" \| "date"	نعم	text, number or date.

حذف حقل مخصص

لا يمكن التراجع

DELETE/api/v1/contacts/fields/{key}·MCP tool: delete_contact_field·Keys: full

يحذف تعريف حقل مخصص. لا يمكن التراجع عنه، لكن العملاء يحتفظون بقيمهم مخفية حتى يُضاف حقل بالمفتاح نفسه من جديد.

الحقل	النوع	إلزامي	الوصف
key	string	نعم	The field's key.

الاستيراد

استيراد العملاء

POST/api/v1/contacts/import·MCP tool: import_contacts·Keys: full

يستورد حتى 1,000 صف في كل طلب. تُصحَّح أرقام الجوال إلى الصيغة الدولية وأخطاء الإيميل الشائعة، وتُستبعد العناوين غير الصالحة والعامة والمؤقتة والمكررة والملغى اشتراكها سابقاً مع عدّها. أرسل الدفعة التالية بـ importId الأولى؛ والحد 250,000 صف لكل استيراد.

الحقل	النوع	إلزامي	الوصف
rows	object[]	نعم	The rows, 1,000 at most, with columns already mapped to fields.
consent	object	نعم	How these people agreed to hear from you, per channel. unknown keeps them pending until they agree.
attest	boolean	نعم	Must be true unless both channels are unknown: these people agreed to receive your messages; the list wasn't bought or scraped.
importId	string		The importId the first chunk answered with, to add rows to the same import.
fileName	string		The uploaded file's name, shown in the import history.
total	integer		With the first chunk: rows in the whole file, so the import turns done once all arrive.
firstRowNumber	integer		Row number of rows[0] in the file, for the left-out report. Default: continues from the import's count.

عرض عملية استيراد

قراءة فقط

GET/api/v1/contacts/imports/{id}·MCP tool: get_import·Keys: full, read

يعرض حالة الاستيراد وأرقامه: الصفوف المعالجة، والعملاء المضافين والمحدَّثين، والصفوف المستبعدة حسب السبب، والأخطاء المصححة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

قائمة عمليات الاستيراد

قراءة فقط

GET/api/v1/contacts/imports·MCP tool: list_imports·Keys: full, read

يعرض آخر عمليات الاستيراد في المنشأة، الأحدث أولاً، مع الحالة والأرقام.

الحقل	النوع	إلزامي	الوصف
limit	integer		How many, 10 by default, 50 at most.

الصفوف المستبعدة

قراءة فقط

GET/api/v1/contacts/imports/{id}/left-out·MCP tool: list_left_out·Keys: full, read

يعرض الصفوف التي استبعدها الاستيراد مع السبب ومحتوى الصف، بترتيب الملف، 100 في الصفحة. تُحفظ 7 أيام بعد الاستيراد.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
after	integer		Return rows after this cursor (nextCursor of the previous page).
limit	integer		Rows per page, 100 by default, 500 at most.

الشرائح

عدّ شريحة

POST/api/v1/segments/count·MCP tool: count_segment·Keys: full

يعدّ العملاء الذين تختارهم شروط معينة دون حفظ أي شيء. جرّب الشروط هنا قبل create_segment.

الحقل	النوع	إلزامي	الوصف
match	"all" \| "any"		all: contacts meeting every condition. any: at least one.
conditions	object[]	نعم	Up to 10 conditions. tag has/has_not; city/country/source is/is_not; added within_days/before_days (number); channel active/not_active (email\|whatsapp); orders bought_within_days/not_bought_within_days (bought before, but not in the last N days)/count_at_least/spent_at_least (store currency), from a connected store; field.<key> is/contains/is_set/not_set/before/since (YYYY-MM-DD)/at_least/less_than.

قائمة الشرائح

قراءة فقط

GET/api/v1/segments·MCP tool: list_segments·Keys: full, read

يعرض الشرائح المحفوظة، الأقدم أولاً، مع شروطها بالعربية وعدد العملاء الذين تختارهم الآن.

لا يحتاج مدخلات.

عرض شريحة

قراءة فقط

GET/api/v1/segments/{id}·MCP tool: get_segment·Keys: full, read

يعرض شريحة محفوظة مع شروطها وعدد العملاء الذين تختارهم الآن.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إنشاء شريحة

POST/api/v1/segments·MCP tool: create_segment·Keys: full

يحفظ شروطاً تختار بعض العملاء، مثل كبار العملاء في الرياض أو من لم يزرك منذ 90 يوماً. يدخل العملاء الشريحة ويخرجون منها حسب الشروط.

الحقل	النوع	إلزامي	الوصف
name	string	نعم	The segment's name, e.g. عملاء الرياض المميزون.
match	"all" \| "any"		all: contacts meeting every condition. any: at least one.
conditions	object[]	نعم	Up to 10 conditions. tag has/has_not; city/country/source is/is_not; added within_days/before_days (number); channel active/not_active (email\|whatsapp); orders bought_within_days/not_bought_within_days (bought before, but not in the last N days)/count_at_least/spent_at_least (store currency), from a connected store; field.<key> is/contains/is_set/not_set/before/since (YYYY-MM-DD)/at_least/less_than.

تعديل شريحة

PATCH/api/v1/segments/{id}·MCP tool: update_segment·Keys: full

يغيّر اسم الشريحة أو يستبدل شروطها. أرسل ما يتغير فقط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
name	string		The segment's name.
match	"all" \| "any"		all or any.
conditions	object[]		New conditions, replacing the old ones (same rules as create_segment).

حذف شريحة

لا يمكن التراجع

DELETE/api/v1/segments/{id}·MCP tool: delete_segment·Keys: full

يحذف شريحة محفوظة، ويبقى عملاؤها كما هم. لا يمكن التراجع عنه.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

الحملات

قوالب الحملات

قراءة فقط

GET/api/v1/campaigns/templates·MCP tool: list_campaign_templates·Keys: full, read

يعرض الحملات العربية الجاهزة (اشتقنا لك، منتج جديد، عرض، رمضان، العيد، ترحيب، عيد ميلاد، طلب تقييم، فارغة) التي تبدأ منها حملة أو أتمتة جديدة.

لا يحتاج مدخلات.

المناسبات القادمة

قراءة فقط

GET/api/v1/campaigns/occasions·MCP tool: list_occasions·Keys: full, read

يعرض المناسبات القادمة التي تبني عليها المتاجر في دولة المنشأة حملاتها (رمضان، والعيدان، والأيام الوطنية، والجمعة البيضاء، ويوم الرواتب)، مع الأيام المتبقية والقالب المقترح ونصيحة بالعربية. remind تعني أن وقت التجهيز حان. التواريخ الهجرية بتقويم أم القرى وقد تتغير يوماً.

الحقل	النوع	إلزامي	الوصف
days	integer		How far ahead to look, 60 days by default.

قائمة الحملات

قراءة فقط

GET/api/v1/campaigns·MCP tool: list_campaigns·Keys: full, read

يعرض حملات المنشأة، الأحدث أولاً، مع الحالة والأرقام الرئيسية (المستلمون، المرسَل، الفتح، النقر).

الحقل	النوع	إلزامي	الوصف
limit	integer		How many, 50 by default.

عرض حملة

قراءة فقط

GET/api/v1/campaigns/{id}·MCP tool: get_campaign·Keys: full, read

يعرض الحملة بمحتواها، ومن ستصله الآن، وعنوان المرسل، وأي شيء يمنع إرسالها.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إنشاء حملة

POST/api/v1/campaigns·MCP tool: create_campaign·Keys: full

ينشئ مسودة من قالب أو فارغة، ولا يرسل شيئاً. النوع permission_request ينشئ الإيميل الذي يُرسل مرة واحدة ليطلب موافقة العملاء المعلّقين.

الحقل	النوع	الوصف
name	string	Internal name. Default: the template's name.
template	string	A template key from list_campaign_templates. Default: blank.
kind	"campaign" \| "permission_request"	campaign, or permission_request for pending contacts.
brandId	string	The sending brand. Default: the organization's first brand.
channel	"email" \| "whatsapp"	email (default) or whatsapp.
waTemplateId	string	whatsapp: an approved template (list_whatsapp_templates).

تعديل مسودة حملة

PATCH/api/v1/campaigns/{id}·MCP tool: update_campaign·Keys: full

يغيّر اسم المسودة أو عنوانها أو نص المعاينة أو محتواها أو شريحتها أو علامتها. أرسل ما يتغير فقط. مع revision يُرفض التعديل إذا حفظ أحد غيرك في الأثناء.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
name	string		Internal name.
subject	string		Subject line. Merge tags like {{first_name\|عميلنا العزيز}} work.
previewText	string		Text inbox apps show after the subject.
content	object		The blocks: heading (level 1-3), text (bold and line breaks), list (bullet or number items), quote, button (solid or outline), image (full, wide or half width), divider. Most take align: right, center or left; without it the brand's email design decides.
segmentId	string \| null		A segment to send to, or null for every subscribed contact.
brandId	string		The sending brand.
waTemplateId	string \| null		whatsapp: the approved template to send.
fallbackEmail	boolean		whatsapp: also email contacts who have no WhatsApp subscription (uses the subject and blocks).
revision	integer		The revision you started from (get_campaign); refused with revision_conflict if it changed.

نسخ حملة

POST/api/v1/campaigns/{id}/duplicate·MCP tool: duplicate_campaign·Keys: full

ينسخ عنوان الحملة ونص المعاينة والمحتوى والشريحة والعلامة إلى مسودة جديدة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

حذف مسودة حملة

لا يمكن التراجع

DELETE/api/v1/campaigns/{id}·MCP tool: delete_campaign·Keys: full

يحذف المسودة. لا يمكن التراجع عنه. الحملات المرسلة لا تُحذف حتى تبقى تقاريرها.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

معاينة حملة

قراءة فقط

GET/api/v1/campaigns/{id}/preview·MCP tool: preview_campaign·Keys: full, read

يعرض الحملة كما تصل لعميل معيّن (أو قارئ تجريبي) مع تعبئة المتغيرات. لا يُرسل شيء ولا تُتتبَّع الروابط.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
contactId	string		A contact to preview as. Default: a sample reader.

إرسال إيميل تجريبي

لا يمكن التراجع

POST/api/v1/campaigns/{id}/test·MCP tool: send_test_email·Keys: full

يرسل الحملة كما حُفظت إلى عنوان واحد (عنوانك افتراضياً) مع [تجربة] قبل العنوان. يُحتسب من إيميلات الباقة. لا يمكن التراجع عنه.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
to	string		The address to send the test to. Default: the signed-in user's email (required for API keys).

إرسال حملة الآن

لا يمكن التراجع

POST/api/v1/campaigns/{id}/send·MCP tool: send_campaign·Keys: full

يرسل المسودة الآن لكل عميل مشترك بالبريد (أو لعملاء شريحتها)، إيميلاً واحداً لكل عميل. لا يمكن التراجع عنه: الإيميلات لا تُسترجع. إرسال حملة قيد الإرسال أو مرسلة يعيد conflict، فإعادة المحاولة لا ترسل مرتين. يُراجَع المحتوى أولاً (والتعليق يوقفها بالسبب content_review). العملاء الذين لم يُراسَلوا من قبل يُرسَل لهم على مراحل (2% ثم 5% ثم الباقي، بفاصل 30 دقيقة) ما دامت نسب الارتداد والبلاغات منخفضة. ومن تجاهل 6 حملات خلال 180 يوماً تصله رسالة «هل ما زلت تريد رسائلنا؟» بدلاً منها.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

جدولة حملة

لا يمكن التراجع

POST/api/v1/campaigns/{id}/schedule·MCP tool: schedule_campaign·Keys: full

يجدول مسودة لتُرسل وحدها في وقت بين 5 دقائق و60 يوماً من الآن، بعد فحوصات send_campaign نفسها. في الموعد تُرسل تماماً كما يرسلها send_campaign، مع التحقق من صلاحيات من جدولها من جديد. بعد إرسالها لا يمكن التراجع عنه، وقبله يلغيها unschedule_campaign. أرسل at مع المنطقة الزمنية، أو استعن بـ get_best_send_time لمعرفة متى يفتح عملاء المنشأة أكثر.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
at	string	نعم	When to send, ISO 8601 with an offset, e.g. 2026-11-12T20:00:00+03:00.

إلغاء جدولة حملة

POST/api/v1/campaigns/{id}/unschedule·MCP tool: unschedule_campaign·Keys: full

يلغي الإرسال المجدول، فتعود الحملة مسودة تعدّلها أو ترسلها أو تجدولها من جديد.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

أفضل وقت للإرسال

قراءة فقط

GET/api/v1/campaigns/best-time·MCP tool: get_best_send_time·Keys: full, read

متى يفتح عملاء المنشأة رسائلهم أكثر، من فتح الأشخاص وقراءة واتساب في آخر 90 يوماً، حسب اليوم والساعة بتوقيت المنشأة. best تبقى فارغة حتى يتوفر 30 فتحاً على الأقل.

لا يحتاج مدخلات.

إيقاف حملة مؤقتاً

POST/api/v1/campaigns/{id}/pause·MCP tool: pause_campaign·Keys: full

يوقف حملة قيد الإرسال. ما أُرسل يبقى مرسلاً، والباقي ينتظر resume_campaign.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

استئناف حملة

لا يمكن التراجع

POST/api/v1/campaigns/{id}/resume·MCP tool: resume_campaign·Keys: full

يرسل بقية حملة متوقفة. لا يمكن التراجع عنه: الإيميلات لا تُسترجع بعد خروجها. التوقف بسبب مراجعة المحتوى أو ارتفاع الارتداد والبلاغات لا يُستأنف بهذه الطريقة، ويعيد conflict.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إلغاء بقية الحملة

لا يمكن التراجع

POST/api/v1/campaigns/{id}/cancel·MCP tool: cancel_campaign·Keys: full

يوقف حملة قيد الإرسال أو متوقفة نهائياً، ويُسقط ما لم يُرسل بعد. لا يمكن التراجع عنه، وما أُرسل يبقى مرسلاً.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

نصائح الوصول للحملة

قراءة فقط

GET/api/v1/campaigns/{id}/tips·MCP tool: get_campaign_tips·Keys: full, read

يفحص محتوى الحملة قبل الإرسال: ما قد يعلّقها للمراجعة (طلبات تشبه الاحتيال، عروض ممنوعة، روابط خطرة) ونصائح تساعدها على الوصول إلى صندوق الوارد، بالعربية. لا يُرسل شيء.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

فحص الحملة قبل الإرسال

قراءة فقط

GET/api/v1/campaigns/{id}/checklist·MCP tool: get_campaign_checklist·Keys: full, read

مراجعة المسودة قبل إرسالها كقائمة فحص: ما يمنع الإرسال، وما يُنصح بإصلاحه (نص المعاينة، والتجربة بعد آخر تعديل، والمحتوى الذي سيراجعه فريقنا، ونصائح الوصول)، وما اجتاز الفحص (طول العنوان، ورابط إلغاء الاشتراك، والحجم، وعنوان المنشأة، والمرسل). كل بند يقول أين يُصلح. لا يُرسل شيء.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

تقرير الحملة

قراءة فقط

GET/api/v1/campaigns/{id}/report·MCP tool: get_campaign_report·Keys: full, read

نتائج الحملة: المستلمون، والمرسَل، والواصل، والمنتظر (مراحل لاحقة أو حصة Gmail للغد)، والفاشل، والمتخطى، والفتح (للأشخاص فقط؛ حماية خصوصية Apple Mail والماسحات تُحسب منفصلة)، والنقرات، والارتداد، والبلاغات، وإلغاء الاشتراك، وتأكيدات الموافقة، والنسب، والنقرات لكل رابط، ومع ربط متجر: الطلبات المدفوعة التي جلبتها (شراء خلال 7 أيام من النقر أو 3 أيام من الفتح).

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

الأتمتة

قائمة الأتمتة

قراءة فقط

GET/api/v1/automations·MCP tool: list_automations·Keys: full, read

يعرض أنواع الأتمتة الأربعة التي تشغّلها المنشأة (ترحيب، وعيد ميلاد، واسترجاع، وطلب تقييم بعد الشراء)، والموجود منها وحالته، وما أرسله وفُتح ونُقر، والإيرادات التي جلبها، وما يمنع المسودة من التشغيل.

لا يحتاج مدخلات.

عرض أتمتة

قراءة فقط

GET/api/v1/automations/{id}·MCP tool: get_automation·Keys: full, read

يعرض أتمتة واحدة بأرقامها وما يمنع تشغيلها، وآخر 20 شخصاً دخلوها مع حالة رسالة كل منهم.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إنشاء أتمتة

POST/api/v1/automations·MCP tool: create_automation·Keys: full

ينشئ أحد أنواع الأتمتة الأربعة مسودةً برسالة عربية جاهزة من قالبها، ولا يُرسل شيء حتى start_automation. قناة whatsapp تحتاج قالب واتساب معتمداً (waTemplateId)، وfallbackEmail يرسل إيميلاً لمن ليس على واتساب. تُعدَّل الرسالة بـ update_campaign على campaignId.

الحقل	النوع	إلزامي	الوصف
type	"welcome" \| "birthday" \| "win_back" \| "post_purchase"	نعم	welcome, birthday, win_back or post_purchase.
channel	"email" \| "whatsapp"		email (default) or whatsapp.
waTemplateId	string		For channel whatsapp: an approved WhatsApp template.
fallbackEmail	boolean		For channel whatsapp: email contacts who aren't on WhatsApp.
brandId	string		The brand it sends as; the first brand by default.
settings	object		Per type: welcome {delayMinutes}; birthday {field}; win_back {days, basis orders\|field, field}; post_purchase {days}; any {segmentId}.

تعديل إعدادات أتمتة

PATCH/api/v1/automations/{id}·MCP tool: update_automation·Keys: full

يغيّر متى ترسل الأتمتة (إعداداتها) أو اسمها. أرسل ما يتغير فقط، وتُدمج الإعدادات مع الحالية. الرسالة نفسها تُعدَّل بـ update_campaign ما دامت الأتمتة مسودة أو موقوفة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.
name	string		A name for the dashboard.
settings	object		The settings to change, e.g. { days: 90 } for win_back.

تشغيل أتمتة

لا يمكن التراجع

POST/api/v1/automations/{id}/start·MCP tool: start_automation·Keys: full

يشغّل الأتمتة: تُراجَع رسالتها، ثم تصل تلقائياً كل من يستوفي الشرط من الآن، مرة واحدة لكل مناسبة. الرسائل التي ترسلها لا يمكن التراجع عنها. يُحسب الناس من لحظة التشغيل فقط (الترحيب للعملاء الجدد لا القدامى)، وعيد الميلاد والاسترجاع وطلب التقييم تُرسل بين 10:00 و20:00 بتوقيت المنشأة، ولا تصل أحداً أكثر من رسالة تسويقية واحدة خلال 20 ساعة.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

إيقاف أتمتة

POST/api/v1/automations/{id}/pause·MCP tool: pause_automation·Keys: full

يوقف الأتمتة: لا يدخلها أحد جديد، وتُسقط رسائلها التي لم تُرسل بعد لأنها مرتبطة بوقتها، مثل الترحيب أو عيد الميلاد. أثناء الإيقاف يمكن تعديل الرسالة، وstart_automation يعيد تشغيلها.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

حذف أتمتة

لا يمكن التراجع

DELETE/api/v1/automations/{id}·MCP tool: delete_automation·Keys: full

يحذف أتمتة لم ترسل شيئاً مع رسالتها. لا يمكن التراجع عنه. الأتمتة التي أرسلت تبقى حتى يبقى تقريرها وإيراداتها: أوقفها بدلاً من ذلك.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

واتساب

حالة ربط واتساب

قراءة فقط

GET/api/v1/whatsapp·MCP tool: get_whatsapp·Keys: full, read

يعرض رقم واتساب المربوط (تقييم الجودة وحد Meta اليومي)، وطريقة الربط المتاحة هنا، وأوقات الهدوء لرسائل العروض.

لا يحتاج مدخلات.

ربط رقم واتساب

POST/api/v1/whatsapp/connect·MCP tool: connect_whatsapp·Keys: full

يربط رقم واتساب الخاص بالمنشأة. في الإنتاج استخدم embedded_signup مع الرمز ومعرّف WABA ومعرّف الرقم من Embedded Signup في Meta، أو manual مع رمز وصول موجود. محلياً، test يربط رقماً تجريبياً.

الحقل	النوع	إلزامي	الوصف
method	"test" \| "embedded_signup" \| "manual"	نعم	How to connect.
phone	string		test only: the number to simulate, in international format.
code	string		embedded_signup: the code from FB.login (valid for 30 seconds).
wabaId	string		The WhatsApp Business Account id.
phoneNumberId	string		The phone number id.
accessToken	string		manual: a business or system-user token with WhatsApp permissions. Stored encrypted.
coexistence	boolean		The number stays on the WhatsApp Business app too (skips registration).

فصل واتساب

لا يمكن التراجع

POST/api/v1/whatsapp/disconnect·MCP tool: disconnect_whatsapp·Keys: full

يفصل رقم واتساب عن اشتقنا وينسى رمز الوصول، وتتوقف حملات واتساب الجارية. لا يمكن التراجع عنه: إعادة الربط تعني إرسال القوالب للمراجعة من جديد.

لا يحتاج مدخلات.

تحديث بيانات واتساب من Meta

POST/api/v1/whatsapp/sync·MCP tool: sync_whatsapp·Keys: full

يقرأ من Meta تقييم جودة الرقم الحالي وحد الرسائل وحالة مراجعة كل قالب. الـ webhooks تفعل ذلك تلقائياً؛ هذا للتحقق الآن.

لا يحتاج مدخلات.

أوقات الهدوء في واتساب

PATCH/api/v1/whatsapp/settings·MCP tool: update_whatsapp_settings·Keys: full

يحدد الساعات، بتوقيت كل مستلم، التي تنتظر فيها رسائل العروض بدل أن تُرسل. الافتراضي من 22:00 إلى 09:00. تساوي الساعتين يلغي أوقات الهدوء.

الحقل	النوع	إلزامي	الوصف
quietHours	object	نعم	When marketing waits.

قوالب واتساب الجاهزة

قراءة فقط

GET/api/v1/whatsapp/library·MCP tool: list_whatsapp_library·Keys: full, read

يعرض قوالب واتساب العربية الجاهزة في اشتقنا (اشتقنا لك، منتج جديد، عرض، رمضان، العيد، ترحيب، عيد ميلاد، طلب تقييم) التي يمكن إرسالها لمراجعة Meta عبر create_whatsapp_template.

لا يحتاج مدخلات.

قائمة قوالب واتساب

قراءة فقط

GET/api/v1/whatsapp/templates·MCP tool: list_whatsapp_templates·Keys: full, read

يعرض القوالب المرسلة للرقم المربوط، مع حالة مراجعتها في Meta ومعاينتها كما يقرؤها عميل تجريبي.

لا يحتاج مدخلات.

إرسال قالب واتساب للمراجعة

POST/api/v1/whatsapp/templates·MCP tool: create_whatsapp_template·Keys: full

يفحص القالب بقواعد Meta وقواعد المحتوى لدينا، ثم يرسله لمراجعة Meta. اكتب بالمتغيرات ({{first_name|عميلنا العزيز}} و{{city}} و{{brand_name}}) أو ابدأ من مفتاح في المكتبة. قوالب العروض تحصل على زر إيقاف. تصل الموافقة عبر الـ webhook خلال دقائق عادة.

الحقل	النوع	الوصف
libraryKey	string	Start from a ready template (list_whatsapp_library).
brandId	string	The brand whose name is written into the template. Default: the first brand.
category	"MARKETING" \| "UTILITY"	MARKETING (default) for offers and news; UTILITY only for transactional updates.
body	string	The message text, up to 1024 characters after merge tags. Default: the library text.
footerText	string \| null	Small grey line under the message, up to 60 characters.
buttonText	string \| null	Label of the link button, up to 25 characters.
buttonUrl	string \| null	Where the button goes (https). Clicks are tracked.
optOut	boolean	Add the «إيقاف العروض» opt-out button (default true for marketing).

حذف قالب واتساب

لا يمكن التراجع

DELETE/api/v1/whatsapp/templates/{id}·MCP tool: delete_whatsapp_template·Keys: full

يحذف القالب هنا وفي Meta. لا يمكن التراجع عنه، والحملات التي تستخدمه لن تستطيع الإرسال.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

ردود واتساب

قراءة فقط

GET/api/v1/whatsapp/replies·MCP tool: list_whatsapp_replies·Keys: full, read

يعرض آخر رسائل العملاء إلى الرقم المربوط، الأحدث أولاً، مع تمييز طلبات الإيقاف. الرد عليها من تطبيق واتساب أو WhatsApp Manager.

الحقل	النوع	إلزامي	الوصف
limit	integer		How many (default 50).

المتاجر

المتاجر المربوطة

قراءة فقط

GET/api/v1/stores·MCP tool: get_stores·Keys: full, read

يعرض المتاجر الإلكترونية المربوطة بالمنشأة (سلة، زد)، وعدد العملاء والطلبات من كل متجر، وآخر مزامنة، والمنصات المتاحة للربط هنا، والإيرادات التي جلبتها الحملات في آخر 30 يوماً.

لا يحتاج مدخلات.

ربط متجر

POST/api/v1/stores/connect·MCP tool: connect_store·Keys: full

يربط متجراً في سلة أو زد: يعيد authorizeUrl ليثبّت صاحب المتجر اشتقنا أو يوافق عليه، ثم يظهر المتجر في صفحة المتاجر ليربطه (claim_store)، ونستورد العملاء والطلبات. محلياً، test يربط متجراً تجريبياً فوراً. يُستورد العملاء بأساس الموافقة الذي تختاره لكل قناة؛ وunknown يبقيهم معلّقين حتى يوافقوا.

الحقل	النوع	إلزامي	الوصف
platform	"salla" \| "zid" \| "test"	نعم	salla, zid, or test (development only).
consent	object	نعم	Why this store's customers may get marketing, per channel. unknown keeps them pending until they agree.
attest	boolean		Required (true) when a consent basis isn't unknown: these customers agreed to receive offers.
brandId	string		The brand this store belongs to; the first brand by default.

ربط متجر ثبّت اشتقنا

POST/api/v1/stores/claim·MCP tool: claim_store·Keys: full

يربط بالمنشأة متجراً ثبّت اشتقنا أو وافق عليه، ثم يستورد عملاءه وطلباته. تعرض لوحة التحكم installId لصاحب المتجر المسجّل بإيميل حساب المتجر نفسه، أو العائد للتو من الموافقة؛ ويعمل مرة واحدة خلال 7 أيام.

الحقل	النوع	إلزامي	الوصف
installId	string	نعم	From the link opened after installing Ishtaqna in the store.
consent	object	نعم	Why this store's customers may get marketing, per channel. unknown keeps them pending until they agree.
attest	boolean		Required (true) when a consent basis isn't unknown.

مزامنة متجر الآن

POST/api/v1/stores/{id}/sync·MCP tool: sync_store·Keys: full

يقرأ طلبات المتجر منذ آخر مزامنة الآن (وكل العملاء في المرة الأولى). الطلبات والعملاء الجدد يصلون تلقائياً عبر الـ webhooks، وهذا لالتقاط ما فات.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

فصل متجر

POST/api/v1/stores/{id}/disconnect·MCP tool: disconnect_store·Keys: full

يفصل المتجر وينسى رموز الوصول، فتتوقف الطلبات الجديدة. العملاء والطلبات السابقة تبقى، فتحتفظ التقارير بإيراداتها. إعادة الربط تعني الموافقة على اشتقنا في المتجر من جديد.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

طلبات المتجر

قراءة فقط

GET/api/v1/stores/orders·MCP tool: list_store_orders·Keys: full, read

يعرض طلبات المتاجر المربوطة، الأحدث أولاً، 50 في الصفحة، مع العميل والحملة المنسوب إليها كل طلب. صفِّ بـ campaignId لترى ما جلبته حملة واحدة. أعد nextCursor في cursor للصفحة التالية.

الحقل	النوع	الوصف
campaignId	string	Only orders credited to this campaign.
limit	integer	How many, 50 by default.
cursor	integer	nextCursor from the previous page.

إيرادات الحملات

قراءة فقط

GET/api/v1/stores/revenue·MCP tool: get_revenue·Keys: full, read

لآخر N يوماً: طلبات المتجر المدفوعة، وما جلبته الحملات منها (شراء خلال 7 أيام من النقر أو 3 أيام من الفتح أو القراءة)، مع أعلى الحملات. لا شيء قبل ربط متجر.

الحقل	النوع	إلزامي	الوصف
days	integer		The period, 30 days by default.

مفاتيح الربط

قائمة مفاتيح الربط

قراءة فقط

GET/api/v1/api-keys·MCP tool: list_api_keys·Keys: full, read

يعرض مفاتيح الربط في المنشأة، بما فيها الملغاة، الأحدث أولاً. المفاتيح نفسها لا تظهر مرة أخرى أبداً.

لا يحتاج مدخلات.

إنشاء مفتاح ربط

POST/api/v1/api-keys·MCP tool: create_api_key·Keys: full

ينشئ مفتاح ربط ويعرضه مرة واحدة فقط، ولا نحفظ إلا بصمته (hash). full يستطيع كل شيء، وread القراءة فقط، وsignups إضافة العملاء فقط.

الحقل	النوع	إلزامي	الوصف
name	string	نعم	What the key is for, e.g. Website signups.
level	"full" \| "signups" \| "read"	نعم	full, read or signups.

إلغاء مفتاح ربط

لا يمكن التراجع

DELETE/api/v1/api-keys/{id}·MCP tool: revoke_api_key·Keys: full

يلغي مفتاح الربط نهائياً: كل طلب به يعيد unauthorized من الآن. لا يمكن التراجع عنه.

الحقل	النوع	إلزامي	الوصف
id	string	نعم	The resource's ID.

للآلات

/api/v1/openapi.jsonمواصفات OpenAPI 3.1 لكل المسارات.
/llms.txtملخص قصير للمساعدات الذكية.
/llms-full.txtالمرجع الكامل مع مخططات المدخلات.

→ الصفحة الرئيسية