الصلاحيات والقدرات

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

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

كيف يُسمح بالطلب

ينتمي المفتاح إلى عضو واحد في الفريق ضمن حساب واحد، ولا تسمح علاقات بالطلب إلا إذا تحقق الشرطان معاً:

  1. أن يحمل المفتاح الإمكانية التي تحتاجها نقطة النهاية. تظهر الإمكانيات على بطاقة المفتاح في الإعدادات > التكاملات > واجهة التطبيق البرمجية.
  2. أن يملك عضو الفريق الذي أنشأ المفتاح صلاحية الإجراء في ذلك الحساب، وهي الصلاحية نفسها التي يحتاجها الإجراء داخل التطبيق.

الإمكانية لا تمنح صلاحية أبداً. فإذا لم يكن عضو الفريق قادراً على حذف جهات الاتصال في التطبيق، فلن يحذفها مفتاح يحمل contact-delete أيضاً.

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

متى يُرفض الطلب

رمز الحالة المعنى
401 المفتاح غير موجود، أو غير صحيح، أو منتهي الصلاحية، أو ملغى.
403 المفتاح لا يحمل الإمكانية التي تحتاجها نقطة النهاية، أو عضو الفريق لا يملك صلاحية الإجراء. وتميّز الرسالة بين الحالتين.
404 نقطة النهاية غير متاحة لمفاتيح API أصلاً، أو السجل غير موجود في الحساب.
423 عضو الفريق الذي أنشأ المفتاح معطّل في الحساب، أو الحساب مجدول للحذف.

{info} من الطبيعي أن تحصل على 404 من نقطة نهاية ترى التطبيق يستخدمها. فكثير من الطلبات التي يرسلها التطبيق لنفسه، كتلك التي تقف خلف صندوق الرسائل وسير العمل وإعدادات خطافات الويب، ليست جزءاً من الواجهة البرمجية العامة، وتُرجع 404 لمفاتيح API أياً كانت إمكانياتها. ولا تقبل مفاتيح API إلا نقاط النهاية المذكورة في هذه الصفحة.

كيانات إدارة العملاء

تتشارك جهات الاتصال والشركات والصفقات والتذاكر والمنتجات والفواتير المجموعة نفسها من الإمكانيات، وتبدأ كل إمكانية باسم الكيان:

الكيان بادئة الإمكانية مسار نقطة النهاية
جهات الاتصال contact /api/contacts
الشركات company /api/companies
الصفقات deal /api/deals
التذاكر ticket /api/tickets
المنتجات product /api/products
الفواتير invoice /api/invoices

في الجداول التالية يرمز {object} إلى البادئة و{path} إلى مسار نقطة النهاية، وتبدأ كل المسارات بـ https://app.alaaqat.com. يذكر عمود الصلاحية صلاحية جهات الاتصال، أما بقية الكيانات فيحتاج عضو الفريق فيها إلى الصلاحية المقابلة لذلك الكيان، مثل تعديل الصفقة للصفقات.

السجلات

الإمكانية نقاط النهاية صلاحية عضو الفريق
{object}-index GET {path} (القائمة)
POST {path}/check-duplicates
القائمة: عرض جميع جهات الاتصال أو عرض جهات الاتصال الخاصة بالفريق أو عرض جهات الاتصال الخاصة بالمستخدم
فحص التكرار: عرض جميع جهات الاتصال
{object}-show GET {path}/{id} عرض تفاصيل جهة الاتصال أو عرض جهات الاتصال الخاصة بالفريق أو عرض جهات الاتصال الخاصة بالمستخدم
{object}-create POST {path} إنشاء جهة اتصال جديدة
{object}-update PUT {path}/{id}
PUT {path}/update-selected
POST {path}/{id}/attach-…
POST {path}/{id}/detach-…
تعديل جهة الاتصال
{object}-delete DELETE {path}/delete-selected حذف جهة الاتصال

الربط يصل السجل بسجلات من كيان آخر، مثل POST /api/contacts/{id}/attach-deals، وفك الربط يزيل رابطاً واحداً، مثل POST /api/contacts/{id}/detach-deal. ويمكن ربط كل كيان بأي كيان آخر.

الخصائص ومجموعات الخصائص

الإمكانية نقاط النهاية صلاحية عضو الفريق
{object}-property-index GET {path}/properties لا شيء
{object}-property-create POST {path}/properties إنشاء حقل مخصص
{object}-property-update PUT {path}/properties/{id} تعديل حقل مخصص
{object}-property-delete DELETE {path}/properties/{id} حذف حقل مخصص
{object}-property-favorite PUT {path}/properties/{id}/favorite تفضيل حقل مخصص
{object}-property-group-index GET {path}/properties/groups عرض مجموعات الحقول
{object}-property-group-create POST {path}/properties/groups إنشاء مجموعة حقول
{object}-property-group-update PUT {path}/properties/groups/{id} تعديل مجموعة حقول
{object}-property-group-delete DELETE {path}/properties/groups/{id} حذف مجموعة حقول

صلاحيات الحقول المخصصة ومجموعات الحقول واحدة لكل الكيانات.

الملاحظات

الإمكانية نقاط النهاية صلاحية عضو الفريق
{object}-note-index GET {path}/{id}/notes عرض جميع الملاحظات على جهة الاتصال
{object}-note-create POST {path}/{id}/notes إضافة ملاحظة على جهة الاتصال
{object}-note-update PUT {path}/{id}/notes/{note_id} تعديل ملاحظة على جهة الاتصال
{object}-note-delete DELETE {path}/{id}/notes/{note_id} حذف ملاحظة من جهة الاتصال

الردود الجاهزة

الإمكانية نقاط النهاية صلاحية عضو الفريق
predefined-response-index GET /api/conversations/predefined-responses
GET /api/conversations/predefined-responses/{id}
عرض الردود الجاهزة
predefined-response-create POST /api/conversations/predefined-responses إنشاء رد جاهز جديد
predefined-response-update PUT /api/conversations/predefined-responses/{id} تعديل رد جاهز
predefined-response-delete DELETE /api/conversations/predefined-responses/{id} حذف رد جاهز

واتساب

الإمكانية نقاط النهاية صلاحية عضو الفريق
broadcast-send POST /api/broadcasts/{id}/send (إرسال قالب) إرسال الرسائل
broadcast-send-otp POST /api/broadcasts/{id}/send-otp (إرسال رمز تحقق)
POST /api/verifications/{id}/verify (التحقق من الرمز)
إرسال الرسائل

المفتاح الذي لا يحمل إلا broadcast-send-otp وcurrent-user هو مفتاح رموز تحقق، ويمكن إنشاؤه في كل الخطط. راجع المصادقة.

المستخدم الحالي

الإمكانية نقاط النهاية صلاحية عضو الفريق
current-user GET /api/me (المستخدم الحالي) لا شيء

أضف current-user إلى أي مفتاح، فهي تتيح للتكامل التأكد من أن مفتاحه يعمل ومعرفة عضو الفريق الذي يتصرف باسمه.

إمكانيات يسهل إغفالها

لكي… يحتاج المفتاح إلى وليس
تربط سجلات أو تفك ربطها، كربط جهات اتصال بصفقة {object}-update للسجل الموجود في الرابط إمكانية ربط مستقلة
تعدّل عدة سجلات دفعة واحدة (update-selected) {object}-update إمكانية تعديل جماعي
تفحص التكرار {object}-index {object}-show
تقرأ رداً جاهزاً واحداً predefined-response-index إمكانية عرض
تتحقق من رمز broadcast-send-otp إمكانية تحقق

في الربط وفك الربط، تتبع الإمكانية الكيان الموجود في الرابط. فربط جهات اتصال بصفقة عبر /api/deals/{id}/attach-contacts يحتاج إلى deal-update، بينما يحتاج الربط نفسه عبر /api/contacts/{id}/attach-deals إلى contact-update.

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

جهات الاتصال: contact-index، contact-show، contact-create، contact-update، contact-delete، contact-property-index، contact-property-create، contact-property-update، contact-property-delete، contact-property-favorite، contact-property-group-index، contact-property-group-create، contact-property-group-update، contact-property-group-delete، contact-note-index، contact-note-create، contact-note-update، contact-note-delete

الشركات: company-index، company-show، company-create، company-update، company-delete، company-property-index، company-property-create، company-property-update، company-property-delete، company-property-favorite، company-property-group-index، company-property-group-create، company-property-group-update، company-property-group-delete، company-note-index، company-note-create، company-note-update، company-note-delete

الصفقات: deal-index، deal-show، deal-create، deal-update، deal-delete، deal-property-index، deal-property-create، deal-property-update، deal-property-delete، deal-property-favorite، deal-property-group-index، deal-property-group-create، deal-property-group-update، deal-property-group-delete، deal-note-index، deal-note-create، deal-note-update، deal-note-delete

التذاكر: ticket-index، ticket-show، ticket-create، ticket-update، ticket-delete، ticket-property-index، ticket-property-create، ticket-property-update، ticket-property-delete، ticket-property-favorite، ticket-property-group-index، ticket-property-group-create، ticket-property-group-update، ticket-property-group-delete، ticket-note-index، ticket-note-create، ticket-note-update، ticket-note-delete

المنتجات: product-index، product-show، product-create، product-update، product-delete، product-property-index، product-property-create، product-property-update، product-property-delete، product-property-favorite، product-property-group-index، product-property-group-create، product-property-group-update، product-property-group-delete، product-note-index، product-note-create، product-note-update، product-note-delete

الفواتير: invoice-index، invoice-show، invoice-create، invoice-update، invoice-delete، invoice-property-index، invoice-property-create، invoice-property-update، invoice-property-delete، invoice-property-favorite، invoice-property-group-index، invoice-property-group-create، invoice-property-group-update، invoice-property-group-delete، invoice-note-index، invoice-note-create، invoice-note-update، invoice-note-delete

الردود الجاهزة: predefined-response-index، predefined-response-create، predefined-response-update، predefined-response-delete

واتساب: broadcast-send، broadcast-send-otp

المستخدم الحالي: current-user