تكامل
الواجهة البرمجية REST في نافس CRM: ربط أنظمتك برمز Bearer
يقدّم نافس CRM واجهة REST تقبل الترويسة Authorization: Bearer، وتتيح عمليات القراءة والإنشاء والتعديل والحذف على السجلات، مع البحث والاستيراد والتصدير وربط السجلات ببعضها، بصلاحيات المستخدم صاحب الرمز.
ما الذي تبنيه بالواجهة البرمجية
الواجهة البرمجية هي الطريق عندما لا يكفي تكامل جاهز: نظام تخطيط موارد يحدّث مبالغ الصفقات كل ليلة، أو بوابة عملاء داخلية تنشئ جهات اتصال، أو مهمة مجدولة تسحب الصفقات المفتوحة إلى لوحة تحليل. وتكمّلها الـ Webhooks الصادرة التي تخبر نظامك بالتغييرات لحظة حدوثها.
| العملية | الطلب |
|---|---|
| قائمة سجلات | GET /api/contacts أو /api/companies أو /api/deals |
| سجل واحد | GET /api/deals/{id} |
| إنشاء | POST /api/contacts |
| تعديل | PUT /api/deals/{id} |
| حذف | DELETE /api/contacts/{id} |
| بحث شامل | GET /api/search |
| بحث في نوع واحد | GET /api/deals/search |
| استيراد CSV | POST /api/contacts/import/upload ثم POST /api/contacts/import/{id} |
| تصدير | POST /api/deals/export |
| ربط سجلات | PUT /api/associations/deals/{id} |
الحصول على رمز والبدء
تأكد من صلاحية الوصول
صلاحية الواجهة البرمجية مفعّلة لكل من يسجّل أو يقبل دعوة، ويظهر لمن يملكها تبويب «رموز الواجهة البرمجية» في الإعدادات ← شخصي ← «حساباتي المرتبطة».
أنشئ رمزًا باسم واضح
اضغط «رمز جديد»، واكتب اسمًا يدل على النظام الذي سيستخدمه، ثم أنشئه.
احصل على قيمة الرمز
مشكلة معروفة في الإصدار الحالي: لا تعرض الشاشة قيمة الرمز الجديد. وإلى أن تُصلح، يحصل المطوّر على رمز Bearer بالطلب POST /api/token مع البريد وكلمة المرور واسم الجهاز device_name. وإذا كان التحقق بخطوتين مفعّلًا، يعيد الطلب challenge_token يُرسل مع رمز التطبيق إلى /api/token/2fa-challenge. والتفاصيل في دليل إنشاء رمز API.
أرسل أول طلب
ضع الرمز في الترويسة Authorization: Bearer مع Accept: application/json، وابدأ بطلب قراءة مثل قائمة جهات الاتصال.
حدد مساحة العمل عند الحاجة
إذا كان المستخدم عضوًا في أكثر من مساحة عمل، أرسل الترويسة X-Tenant-Slug بالاسم المختصر للمساحة؛ وإلا نُفّذ الطلب في آخر مساحة استخدمها، أو في أقدم مساحة انضم إليها إن لم تُحفظ له مساحة.
curl -s "$NAFFES_HOST/api/deals" \
-H "Authorization: Bearer $NAFFES_TOKEN" \
-H "Accept: application/json"الصلاحيات ودورة حياة الرمز
- الرمز يحمل صلاحيات صاحبه كاملة: ما يراه المستخدم أو يعدّله في التطبيق هو ما تراه الواجهة البرمجية أو تعدّله، وفق دوره ونطاقه.
- مدة افتراضية 14 يومًا: ينتهي الرمز بعدها، فخطط لتجديده في أنظمتك.
- الإلغاء فوري: من الإعدادات ← حسابي ← «الجلسات والأمان» ترى الرموز والجلسات مع آخر استخدام، وتلغي واحدًا أو الكل. ورموز المستخدم الموقوف تتوقف فورًا.
- حد الطلبات: 600 طلب في الدقيقة لكل مستخدم افتراضيًا.
- الاتجاه: نظامك يقرأ من نافس ويكتب فيه؛ ولإبلاغ نظامك بالتغييرات دون استعلام متكرر استخدم الـ Webhooks الصادرة.
نصيحة عملية: أنشئ مستخدمًا مخصصًا للتكامل، وامنحه دورًا مخصصًا لا يملك إلا ما يحتاجه، مثل قراءة الصفقات وتعديلها دون حذف، ثم أصدر الرمز باسمه. ويُحتسب هذا المستخدم ضمن عدد مستخدمي خطتك.
ما لا توفره الواجهة البرمجية بعد
- لا رموز محدودة النطاق: لا توجد رموز للقراءة فقط أو مقيدة بمورد؛ الحل هو المستخدم المخصص بدور محدود.
- لا توثيق OpenAPI منشور ولا مكتبات SDK رسمية.
- لا تسجيل دخول OAuth لتطبيقات الطرف الثالث: شاشة «تطبيقات OAuth» تصدر معرّفًا وسرًا، لكن لا توجد نقطة تفويض أو إصدار رموز بعد.
- لا يستطيع مدير مساحة العمل منع مستخدم بعينه من الواجهة البرمجية: الصلاحية مفعّلة للجميع، وتغييرها بيد مشغّل المنصة.
- شاشة الرموز لا تعرض الرمز الجديد حاليًا، كما في خطوات البدء.
أسئلة شائعة
الأسئلة 4
كم تبقى صلاحية الرمز؟
14 يومًا افتراضيًا، ثم يلزم رمز جديد. ويمكن إلغاؤه قبل ذلك في أي وقت من «الجلسات والأمان».
هل يستطيع الرمز الوصول إلى كل بيانات مساحة العمل؟
يصل إلى ما يصل إليه صاحبه فقط. لذلك يُنصح بإصدار رموز التكامل من مستخدم مخصص بدور محدود الصلاحيات.
لماذا لا أرى الرمز بعد إنشائه؟
مشكلة معروفة في الإصدار الحالي من شاشة الرموز. استخدم POST /api/token للحصول على رمز Bearer إلى أن تُصلح.
هل هناك حد لعدد الطلبات؟
نعم، 600 طلب في الدقيقة لكل مستخدم افتراضيًا. وزّع المزامنات الكبيرة على دفعات، واستخدم الاستيراد والتصدير للملفات الكبيرة.