API وWebhooks — اربط Craft بنظام CRM أو بموقعك
كيف تتحكم في Craft عبر طلبات بمفتاح، وتستقبل على خادمك أحداث جهات الاتصال الجديدة والضغط على الأزرار والمدفوعات والمنشورات.
يمكنك ربط 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") ← "مفتاح جديد".
- أعطِ المفتاح اسمًا تعرفه به لاحقًا: "HubSpot"، "موقع العميل".
- اختر ما يُسمح للمفتاح بفعله. المفتاح الجديد يستطيع القراءة فقط افتراضيًا. كل ما عدا ذلك يُفعَّل بمربعات الاختيار: الأقماع، وجهات الاتصال، والرسائل الجماعية، والمنشورات، والمحتوى، ومصنع المحتوى، والحسابات. خيار "كل شيء" يفتح كل الإمكانات، بما فيها التي تُضاف لاحقًا.
- اختر كيف ينشر المفتاح المنشورات والرسائل الجماعية: - "مسودات فقط" — يُحفظ كل شيء كمسودة، وترسله أنت بنفسك من Craft؛ - "مجدول" — ليس قبل 10 دقائق، ليتسع الوقت للإلغاء؛ - "فورًا" — ينشر ويرسل لحظة وصول الطلب.
- حدّد الحد اليومي للإنفاق على الصور.
- اضغط "إنشاء مفتاح" وانسخه فورًا.
🔴 يظهر المفتاح مرة واحدة فقط. يحتفظ 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" للتطبيقات الخارجية: المفتاح يمنح الوصول إلى حسابك أنت فقط.