مركز المساعدة · API وWebhooks

API وWebhooks — اربط Craft بنظام CRM أو بموقعك

كيف تتحكم في Craft عبر طلبات بمفتاح، وتستقبل على خادمك أحداث جهات الاتصال الجديدة والضغط على الأزرار والمدفوعات والمنشورات.

آخر تحديث: 21 نوفمبر 2026

يمكنك ربط Craft بنظام CRM لديك، أو بموقع أحد عملائك، أو بأي خدمة خاصة بك. كل ما يستطيعه موصل MCP متاح أيضًا كطلب HTTPS عادي بمفتاح: الأقماع التسويقية، وجهات الاتصال، والرسائل الجماعية، والمنشورات، ومنشورات الكاروسيل (المنشورات الدوّارة)، والصور. أما Webhooks فتعمل في الاتجاه المعاكس: يرسل Craft حدثًا إلى خادمك عندما تظهر جهة اتصال جديدة، أو يضغط شخص على زر، أو يصل إلى هدف القمع، أو يدفع، أو يُنشر منشور.

كيف يعمل#

  • في Craft تنشئ مفتاحًا وتحدد ما يُسمح له بفعله: القراءة فقط، أو العمل مع الأقماع وجهات الاتصال والرسائل الجماعية والمنشورات وغيرها.
  • يرسل خادمك طلبًا إلى https://craftopen.space/api/v1/tools/<method> مع المفتاح في ترويسة الطلب. أما معاملات الطريقة فتوضع في جسم الطلب بصيغة JSON.
  • ينفّذ Craft الطريقة في حسابك — تمامًا كما لو فعلت ذلك بنفسك على الموقع أو طلبته من الذكاء الاصطناعي عبر موصل MCP، بالفحوصات والحدود نفسها.
  • لتلقي الأحداث تضيف Webhook، وهو عنوان خادمك. يرسل Craft إليه طلبًا موقّعًا، ويعيد المحاولة إذا لم يرد خادمك.

ما الذي تحتاجه#

  • أي خطة: يمكن إنشاء المفاتيح وWebhooks في كل الخطط، بما فيها الخطة المجانية.
  • خادم أو خدمة تستطيع إرسال طلبات HTTPS واستقبالها: كودك الخاص، أو Make، أو n8n، أو Zapier، أو نظام CRM يدعم Webhooks الواردة.

الخطوة 1. أنشئ مفتاحًا#

قائمة الملف الشخصي ← "API وWebhooks" (أو "الإعدادات" ← "API وWebhooks") ← "مفتاح جديد".

  1. أعطِ المفتاح اسمًا تعرفه به لاحقًا: "HubSpot"، "موقع العميل".
  2. اختر ما يُسمح للمفتاح بفعله. المفتاح الجديد يستطيع القراءة فقط افتراضيًا. كل ما عدا ذلك يُفعَّل بمربعات الاختيار: الأقماع، وجهات الاتصال، والرسائل الجماعية، والمنشورات، والمحتوى، ومصنع المحتوى، والحسابات. خيار "كل شيء" يفتح كل الإمكانات، بما فيها التي تُضاف لاحقًا.
  3. اختر كيف ينشر المفتاح المنشورات والرسائل الجماعية: - "مسودات فقط" — يُحفظ كل شيء كمسودة، وترسله أنت بنفسك من Craft؛ - "مجدول" — ليس قبل 10 دقائق، ليتسع الوقت للإلغاء؛ - "فورًا" — ينشر ويرسل لحظة وصول الطلب.
  4. حدّد الحد اليومي للإنفاق على الصور.
  5. اضغط "إنشاء مفتاح" وانسخه فورًا.

🔴 يظهر المفتاح مرة واحدة فقط. يحتفظ Craft ببصمته فقط ولا يستطيع استعادته. فقدته؟ أبطله وأنشئ مفتاحًا جديدًا. لا تضع المفتاح أبدًا في كود صفحات الموقع أو في تطبيق جوال، وإلا سيراه كل زائر. مكان المفتاح على الخادم فقط.

يمكنك تغيير أذونات المفتاح وإعداداته في أي وقت من زر "الإعدادات"، وتسري التغييرات خلال دقيقة. أما زر "إبطال" فيوقف المفتاح فورًا.

الخطوة 2. طلبك الأول#

curl -X POST https://craftopen.space/api/v1/tools/list_funnels \
  -H "Authorization: Bearer craft_your_key" \
  -H "Content-Type: application/json" \
  -d '{}'

الرد الناجح يبدو دائمًا هكذا، والبيانات نفسها داخل data:

{"ok": true, "data": {"funnels": [ ... ]}}

إذا كان هناك خطأ، تحصل على "ok": false مع سبب واضح:

{"ok": false, "error": {"code": "funnel_not_found", "message": "Воронка не найдена."}}

⚠️ رسائل الأخطاء مكتوبة حاليًا بالروسية. ابنِ منطقك على error.code، فهو ثابت ولا يتغير بتغير اللغة.

الطرق المتاحة#

كل الطرق ومعاملاتها مع شرحها:

  • في Craft: الطلب GET https://craftopen.space/api/v1/tools بمفتاحك. تذكر القائمة الإذن الذي تحتاجه كل طريقة، وهل يُسمح لهذا المفتاح باستدعائها؛
  • وصف OpenAPI: craftopen.space/api/v1/openapi.json، وتفهمه Postman وInsomnia ومولّدات العملاء البرمجية.

الطرق هي نفسها طرق موصل MCP. وأكثرها استخدامًا:

المهمة الطريقة إذن المفتاح
قائمة الأقماع وإحصاءاتها list_funnels، get_funnel_stats القراءة
البحث عن مشتركي البوت find_contacts القراءة
بطاقة المشترك get_contact القراءة
إضافة وسم أو إزالته tag_contacts جهات الاتصال
تشغيل قمع لشخص واحد run_funnel_for_contact جهات الاتصال، ووضع "فورًا"
منشور مجدول list_publishing_accounts ← schedule_post المنشورات
رسالة جماعية في Telegram save_broadcast_draft ← send_broadcast_test ← send_broadcast الرسائل الجماعية
كاروسيل من نصك create_carousel، render_carousel المحتوى
صورة مقابل الرصيد generate_image المحتوى

الطلب GET https://craftopen.space/api/v1/me يُظهر أي مفتاح تستخدم، وأذوناته، وكم طلبًا تبقّى لك اليوم.

إعادة المحاولة دون تكرار#

إذا انقطع الطلب ولا تعرف هل وصل أم لا، أرسله مرة أخرى مع ترويسة Idempotency-Key نفسها. لن يُنشر المنشور مرتين، ولن تُحتسب الصورة مرتين.

curl -X POST https://craftopen.space/api/v1/tools/schedule_post \
  -H "Authorization: Bearer craft_your_key" \
  -H "Idempotency-Key: post-2026-09-27-lime-1" \
  -H "Content-Type: application/json" \
  -d '{"account_ids": ["..."], "confirm_usernames": ["@lime_agency"],
       "carousel_id": "...", "caption": "Post text",
       "scheduled_at": "2026-09-27T19:00:00+03:00"}'

⚠️ التأكيدات جزء من الطلب. حيث كان الموقع سيسألك "هل أنت متأكد؟"، ينتظر API تأكيدًا ضمن المعاملات: أسماء الحسابات بعلامة @ للمنشور (confirm_usernames)، والعدد الدقيق للمستلمين للرسالة الجماعية (confirm_recipients)، واسم القمع النشط الذي تعدّله، وسعر كتلة الدفع. إذا لم يطابق التأكيد ما يراه Craft، لا يُرسل شيء، ويخبرك الرد بالقيمة الصحيحة.

الأخطاء وما العمل#

الحالة المعنى
400 معاملات غير صالحة، ويذكر message أيها
401 لا يوجد مفتاح، أو المفتاح خاطئ، أو أُبطل
403 خطة بلا API (plan_required)، أو ينقص المفتاح إذن (scope_required)، أو وضع النشر لا يسمح بهذا الإجراء
404 غير موجود: القمع، أو جهة الاتصال، أو المنشور، أو الطريقة
409 تغيرت البيانات منذ قرأتها، أو لم يتطابق التأكيد — اقرأ البيانات من جديد
429 تجاوزت حد الطلبات — انتظر عدد الثواني المذكور في ترويسة Retry-After
500،‏ 503 عطل مؤقت — أعد المحاولة بعد دقيقة بالقيمة نفسها في Idempotency-Key

الحدود#

  • 60 طلبًا في الدقيقة و10,000 طلب في اليوم لكل حساب، عبر كل المفاتيح مجتمعة. يُحسب اليوم بتوقيت موسكو (UTC+3). تحتاج أكثر؟ راسل الدعم، ويُرفع الحد دون تغيير خطتك.
  • لا تُحتسب Webhooks ضمن الحد.
  • الصور تستهلك الرصيد بأسعار الموقع نفسها، ولا تتجاوز أبدًا الحد اليومي الذي وضعته للمفتاح.
  • الرسائل الجماعية: لا يوجد حد يومي. لكن قبل الإرسال لا بد من رسالة اختبار إلى نفسك عبر send_broadcast_test بالنص نفسه تمامًا.

Webhooks#

في صفحة "API وWebhooks" ← "إضافة Webhook": أدخل عنوان خادمك (https:// فقط) واختر الأحداث. مباشرة بعد الإنشاء يعرض Craft سر التوقيع. احفظه، فلن يظهر مرة أخرى (يمكنك إصدار سر جديد بزر "سر جديد").

زر "اختبار" يرسل الحدث ping ويعرض ما ردّ به خادمك. أما "السجل" فيعرض آخر عمليات التسليم: ما الذي أُرسل، وهل وصل، والرد، وزر "إعادة المحاولة".

الأحداث#

الحدث متى يصل
contact.created اشترك شخص في البوت، أو راسل حسابك على Instagram في الرسائل الخاصة لأول مرة
contact.tagged حصلت جهة اتصال على وسم — يدويًا أو من قمع أو عبر API. حدث واحد لكل وسم جديد
funnel.button_clicked ضغط شخص على زر في القمع
funnel.goal_reached وصل شخص إلى هدف القمع
payment.succeeded تمّت دفعة عبر كتلة الدفع في القمع
post.published نُشر منشور على الشبكة الاجتماعية
agent.message_received وصلت رسالة من عميل إلى وكيل الذكاء الاصطناعي، في Instagram أو Telegram
agent.replied ردّ وكيل الذكاء الاصطناعي على العميل وأُرسل الرد. البيانات تتضمن نص الرد
agent.handed_over حوّل وكيل الذكاء الاصطناعي العميل إلى الموظفين. البيانات تتضمن الملخص، وهل سُلّم الطلب ولمن

تحمل أحداث القمع والوسوم اسم الشخص و@اسم المستخدم ومعرّف Telegram وكل وسومه، فلا حاجة لطلب بطاقته بشكل منفصل.

تحمل أحداث الوكيل الحقول platform (instagram أو telegram)، وaccount_id (حساب Instagram أو البوت)، وcontact_id، وطابعًا زمنيًا، حتى تتمكن من حفظ سجل محادثات الوكيل في نظام CRM أو الخدمة الخاصة بك.

مثال على جسم الطلب:

{
  "id": "6f1c…",
  "type": "contact.created",
  "created_at": "2026-09-26T09:04:11+00:00",
  "data": {
    "platform": "telegram",
    "contact_id": "…",
    "bot_username": "shop_bot",
    "first_name": "Anna",
    "username": "anna",
    "source": {"type": "link", "ref": "promo"}
  }
}

يبقى معرّف الحدث id كما هو في كل إعادة محاولة، فاستخدمه لاستبعاد التكرارات.

التحقق من أن الطلب جاء من Craft#

كل طلب يحمل الترويسة Craft-Signature: t=<time>,v1=<signature>. التوقيع هو HMAC-SHA256 للسلسلة <time>.<request body> باستخدام سرّك. احسبه وقارن:

import hmac, hashlib, time

def craft_signature_ok(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:   # older than 5 minutes — reject
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])
const crypto = require("crypto");

function craftSignatureOk(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

⚠️ يُحسب التوقيع على جسم الطلب الخام، أي البايتات نفسها التي وصلت تمامًا. إذا كان إطار العمل لديك يحلل JSON ثم يعيد تحويله إلى نص قبل ذلك، فلن يتطابق التوقيع.

إعادة المحاولات#

ينتظر Craft الرد حتى 10 ثوانٍ. أي رد 2xx يُعدّ تسليمًا ناجحًا. وإلا يعيد Craft المحاولة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم بعد 2 و6 و12 و24 ساعة — 8 محاولات إجمالًا، وبعدها يُعلَّم الحدث بأنه "فشل" (يمكنك إعادة إرساله من السجل).

🔴 بعد 50 عملية تسليم فاشلة متتالية يتوقف Webhook حتى لا يواصل طرق عنوان لا يرد. أصلح خادمك واضغط "تفعيل"، فيُصفَّر العداد. الأحداث التي وقعت أثناء إيقاف Webhook لا تُرسل.

ردّ بسرعة، وأنجز العمل البطيء بعد الرد: إذا استغرق خادمك أكثر من 10 ثوانٍ، يعدّ Craft المحاولة فاشلة ويرسل الحدث مرة أخرى.

قناتك الخاصة: ردود وكيل الذكاء الاصطناعي#

إذا كان العملاء يراسلونك في مكان لم يُربط فيه Craft (تطبيق مراسلة خاص بك، أو دردشة الموقع، أو نظام CRM)، يستطيع وكيل الذكاء الاصطناعي الرد هناك أيضًا. يرسل نظامك رسالة العميل، فيعيد Craft رد الوكيل، ثم يوصله نظامك إلى العميل.

curl -X POST https://craftopen.space/api/v1/agent/reply \
  -H "Authorization: Bearer craft_…" -H "Content-Type: application/json" \
  -d '{"ig_user_id": "1784…", "contact_id": "client-42", "text": "How much is JET+?", "name": "Ivan"}'
  • أي وكيل يرد: ig_user_id لحساب Instagram، أو tg_bot_id لبوت Telegram أُعدّ فيه وكيل. تُستخدم قواعده، وقاعدة المعرفة، والنموذج، وإعدادات التحويل.
  • contact_id: معرّف ثابت للعميل لديك، وبه يتذكر الوكيل المحادثة. أما name فاختياري، ويُستخدم عند التحويل إلى الموظفين.
  • الرد: reply هو النص الموجّه للعميل، وhanded_over يعني أن الوكيل حوّل العميل إلى الموظفين (يذهب العميل المحتمل إلى المكان نفسه الذي تذهب إليه طلبات Instagram)، وpaused يعني أن الوكيل يصمت حتى يعيده الموظفون، وcredits_charged هو الرصيد المستهلك.
  • الردود تستهلك الرصيد، تمامًا كما في Instagram. إذا نفد الرصيد تحصل على الخطأ no_credits.
  • الأحداث agent.message_received وagent.replied وagent.handed_over تصل لهذه القناة أيضًا.

⚠️ عبر هذه القناة يرسل الوكيل نصًا فقط، بلا مقاطع فيديو أو ملفات من الأقماع.

غير متاح بعد#

  • مكتبات عملاء جاهزة: استخدم وصف OpenAPI.
  • إنشاء المفاتيح وWebhooks عبر API نفسه: هذا ممكن فقط من صفحة "API وWebhooks".
  • "تسجيل الدخول عبر Craft" للتطبيقات الخارجية: المفتاح يمنح الوصول إلى حسابك أنت فقط.
لم تجد إجابتك؟راسلنا على Telegram أو على support@craftopen.space — سنرد عليك ونكمل المقال.
راسلنا على Telegram