واجهة برمجة التطبيقات (REST API)

تسجيل مسارات REST الخاصة بـ PrimoCRM ضمن نطاق primocrm/v1 على خطاف rest_api_init. يستخدم تطبيق لوحة التحكم نفس نقاط النهاية هذه، لذا فإن أي إجراء تقوم به واجهة المستخدم متاح برمجياً.

عنوان URL الأساسي

https://yoursite.com/wp-json/primocrm/v1/

المصادقة

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

• من تطبيق لوحة التحكم (نفس المصدر): تتم مصادقة الطلبات بواسطة الجلسة المسجلة ورمز الأمان (REST nonce). يرسل ووردبريس رمز الأمان في ترويسة X-WP-Nonce. يكون هذا تلقائياً للكود الذي يعمل داخل لوحة تحكم ووردبريس (wp-admin).
• من الكود الخارجـي: استخدم طريقة مصادقة يقبلها ووردبريس لواجهة برمجة تطبيقات REST، مثل كلمات مرور التطبيقات، مع مستخدم لديه الصلاحية المطلوبة. يضيف PrimoCRM Pro مفاتيح واجهة برمجة التطبيقات المخصصة للوصول البرمجي.

نقاط النهاية التي تدير الإعدادات، أو الإرسال، أو العمليات التدميرية تتطلب صلاحية بمستوى مدير الموقع. تتطلب عمليات القراءة وجهات الاتصال الروتينية صلاحية الوصول إلى نظام إدارة علاقات العملاء (CRM).

نقاط النهاية النموذجية

القائمة أدناه هي عينة نموذجية وليست شاملة. استكشف المجموعة الكاملة من علامة تبويب شبكة المتصفح أثناء استخدام تطبيق لوحة التحكم، نظراً لأن واجهة المستخدم تستدعـي نفس المسارات.

جهات الاتصال

الطريقة	المسار	الغرض
GET	/contacts	سرد جهات الاتصال (يدعم التقسيم لصفحات والتصفية)
POST	/contacts	إنشاء جهة اتصال
GET	/contacts/{id}	الحصول على جهة اتصال واحدة
PUT	/contacts/{id}	تحديث جهة اتصال
DELETE	/contacts/{id}	حذف جهة اتصال
POST	/contacts/bulk-action	تطبيق إجراء جماعي على العديد من جهات الاتصال
POST	/contacts/bulk-delete	حذف العديد من جهات الاتصال
GET	/contacts/statuses	سرد الحالات المتاحة
GET	/contacts/{id}/activities	سجل نشاط جهة الاتصال
GET	/contacts/{id}/emails	البريد الإلكتروني المرسل إلى جهة الاتصال

الأتمتة

الطريقة	المسار	الغرض
GET	/automations/triggers	كافة المشغلات المسجلة
GET	/automations/actions	كافة الإجراءات المسجلة
GET	/automations/condition-options	الحقول والمعاملات الخاصة بمنشئ الشروط

النماذج والرموز الذكية

الطريقة	المسار	الغرض
GET	/forms/field-types	كافة أنواع حقول النماذج المسجلة
GET	/smart-codes	كتالوج علامات التخصيص

تعرض الحملات، والتسلسلات، والقوائم، والوسوم، والقوالب، والترحيل، والإعدادات مساراتها الخاصة تحت نفس النطاق، مع اتباع نمط وحدة التحكم نفسه.

مثال على طلب

إنشاء جهة اتصال باستخدام مصادقة كلمة مرور التطبيق:

curl -X POST https://yoursite.com/wp-json/primocrm/v1/contacts \
  -u "admin:APPLICATION_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","first_name":"Ada","status":"subscribed"}'

شكل الاستجابة وتقييد الصلاحيات

تُرجع الاستجابات الناجحة بصيغة JSON. عندما تحظر ميزة Pro أو حد خطة معينة طلباً ما، يُرجع PrimoCRM رمز 403 يتضمن محتواه pro_lock: true، والذي يستخدمه تطبيق لوحة التحكم لإظهار مطالبة الترقية. قم معالجة هذا الشكل إذا كنت تستدعي نقاط النهاية المقيدة بإصدار Pro من الكود الخاص بك.

تنبيه

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