الواجهة البرمجية للمطورين (Developer API)
الواجهة البرمجية للمطورين (Developer API) هي واجهة Resool البرمجية من نوع REST. تتيح لأنظمتك الخاصة، مثل موقعك الإلكتروني أو نظامك الداخلي أو نظام ERP أو مستودع البيانات، قراءة بيانات Resool وتحديثها: إنشاء جهات الاتصال وتحديثها ووسمها، وعرض المحادثات، وإرسال الرسائل، وإنشاء التذاكر والمهام وتحديثها. تتم المصادقة بمفتاح API تنشئه في Resool، ولا يستطيع كل مفتاح إلا ما يُسمح به للعضو الذي أنشأه.
قبل أن تبدأ
- يستطيع المالك والمسؤول فقط إنشاء مفاتيح API وإلغاءها.
- يعمل المفتاح بصلاحيات العضو الذي أنشأه، ولا يملك أبدًا وصولًا أكثر من دور هذا العضو.
كيفية إنشاء مفتاح API
- انتقل إلى
الإعدادات › التطبيقاتوافتح تبويب أدوات المطورين. - انقر ربط (أو إدارة) على بطاقة Developer API. تفتح صفحة Developer API.
- في بطاقة مفاتيح الواجهة البرمجية انقر مفتاح جديد.
- أدخل الاسم ليوضح أين سيُستخدم المفتاح، مثل "الموقع" أو "ERP".
- اختر الصلاحية:
- قراءة: عرض جهات الاتصال والمحادثات والتذاكر والمهام.
- قراءة وكتابة: وأيضًا إنشاء السجلات وتعديلها وإرسال الرسائل.
- انقر إنشاء المفتاح.
الإعدادات › التطبيقات › أدوات المطورين › Developer API › مفتاح جديد
نافذة "مفتاح جديد" وفيها حقل الاسم ممتلئ ("الموقع") وخيارا الصلاحية قراءة وقراءة وكتابة، مع تحديد قراءة وكتابة.
الملف: screenshots/ar/developer-api-new-key.png
- في انسخ مفتاحك الجديد انقر زر النسخ واحفظ المفتاح في مكان آمن، مثل مخزن الأسرار على خادمك. هذه هي المرة الوحيدة التي يظهر فيها المفتاح. انقر تم.
كيفية إدارة مفاتيح API
تعرض بطاقة مفاتيح الواجهة البرمجية كل مفتاح نشط مع:
- الاسم، ومن أنشأه ومتى ("بواسطة … · التاريخ").
- المفتاح: الأحرف الأولى منه لتتعرّف عليه.
- الصلاحية: قراءة أو قراءة وكتابة.
- آخر استخدام: آخر مرة أرسل فيها المفتاح طلبًا، أو لم يُستخدم.
الإعدادات › التطبيقات › أدوات المطورين › Developer API
صفحة Developer API ببطاقة مفاتيح الواجهة البرمجية: العنوان الأساسي أسفل العنوان، وزر مفتاح جديد، وجدول بمفتاحين (أحدهما قراءة والآخر قراءة وكتابة) مع تواريخ آخر استخدام وأزرار الإلغاء.
الملف: screenshots/ar/developer-api-keys-list.png
لإيقاف مفتاح، انقر زر الإلغاء في صفه وأكّد إلغاء. يتوقف كل ما يستخدم المفتاح عن العمل فورًا. كما يتوقف المفتاح إذا أُزيل العضو الذي أنشأه.
كيفية إرسال أول طلب
يظهر العنوان الأساسي أسفل عنوان مفاتيح الواجهة البرمجية. أرسل المفتاح كـ Bearer token في ترويسة Authorization:
curl https://api.resool.io/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"الطلب /me هو اختبار الاتصال، ويعيد مساحة العمل والعضو صاحب المفتاح والصلاحيات التي يملكها المفتاح. استخدم العنوان الأساسي كما يظهر تمامًا في بطاقة مفاتيح الواجهة البرمجية.
الطلبات والردود بصيغة JSON، والتواريخ بصيغة ISO 8601، والمعرّفات UUID. لا حاجة إلى ملفات تعريف الارتباط (cookies).
ما يمكنك فعله بالواجهة البرمجية
| المجال | الطلبات |
|---|---|
| الحساب | GET /me |
| جهات الاتصال | GET /contacts (بحث وتقسيم صفحات)، GET /contacts/{id}، POST /contacts، PATCH /contacts/{id} |
| وسوم جهات الاتصال | POST /contacts/{id}/tags (بمعرّف الوسم، أو بالاسم فيُنشأ إن لم يوجد)، DELETE /contacts/{id}/tags/{tagId}، GET /tags |
| الرسائل | POST /contacts/{id}/messages (في آخر محادثة لجهة الاتصال)، POST /conversations/{id}/messages، GET /conversations/{id}/messages (آخر 50 رسالة) |
| المحادثات | GET /conversations (تصفية حسب الحالة)، PATCH /conversations/{id} (الحالة، المسؤول، الفريق) |
| التذاكر | GET /tickets، GET /tickets/{id}، POST /tickets، PATCH /tickets/{id} |
| المهام | GET /projects، GET /tasks، POST /tasks، PATCH /tasks/{id} |
| الأعضاء | GET /members |
| الاشتراك في الأحداث | POST /hooks، DELETE /hooks/{id}. راجع Webhooks. |
يتحقق كل طلب أيضًا من صلاحيات العضو. فمثلًا يتطلب إرسال رسالة صلاحية الرد في صندوق الوارد، ولا يستطيع مفتاح قراءة أبدًا الإنشاء أو التعديل أو الإرسال. وتظل قواعد القنوات سارية: على واتساب لا يمكن إرسال رسالة حرة إلا خلال 24 ساعة من آخر رسالة من العميل.
ملاحظات وقيود
- حد الطلبات: حتى 120 طلبًا في الدقيقة. عند تجاوزه تتلقى
429؛ انتظر ثم أعد المحاولة. - الأخطاء بصيغة JSON مع رمز الحالة ورمز الخطأ:
| الحالة | المعنى |
|---|---|
400 | المدخلات غير صالحة. |
401 | المفتاح مفقود أو خاطئ أو ملغى. |
402 | خطة مساحة العمل لا تشمل الواجهة البرمجية، أو الاشتراك غير نشط. |
403 | المفتاح للقراءة فقط، أو العضو لا يملك الصلاحية. |
404 | غير موجود في مساحة العمل هذه. |
429 | طلبات كثيرة جدًا. |
- يعمل المفتاح لمساحة عمل واحدة فقط: المساحة التي أُنشئ فيها.
الأسئلة الشائعة وحل المشكلات
أتلقى 401 رغم أنني نسخت المفتاح
ما يمكنك فعله:
- أرسل الترويسة بصيغة
Authorization: Bearer <key>مع مسافة بعد "Bearer" ودون علامات اقتباس. - تأكد أن المفتاح لم يُلغَ وأن العضو الذي أنشأه ما زال في مساحة العمل.
أتلقى 403 عند إنشاء جهة اتصال أو إرسال رسالة
المفتاح بصلاحية قراءة، أو أن العضو الذي أنشأه غير مسموح له بذلك. أنشئ مفتاحًا بصلاحية قراءة وكتابة من حساب عضو يملك دوره الصلاحية.
هل يمكنني رؤية مفتاح فقدته مرة أخرى؟
لا. يظهر المفتاح مرة واحدة فقط. ألغِ المفتاح المفقود وأنشئ مفتاحًا جديدًا.
هل أحتاج إلى الواجهة البرمجية لاستخدام Zapier أو Make أو n8n؟
لا تحتاج إلى إنشاء مفتاح، فهذه الأدوات تتصل بتسجيل الدخول إلى Resool. لكنها تحتاج إلى خطة التوسع (Scale). راجع Zapier وMake وn8n.
كيف أعرف بما يحدث دون أن أستعلم باستمرار؟
استخدم Webhooks. يرسل Resool طلبًا موقّعًا إلى خادمك عند تغيّر جهات الاتصال والمحادثات والتذاكر والمهام والصفقات.