انتقل إلى المحتوى الرئيسي
وثائق ناشر

الواجهة البرمجية (REST)

مفاتيح API والنطاقات ونقاط النهاية في الإصدار v1 من واجهة ناشر البرمجية.

English

واجهة ناشر البرمجية متاحة في باقتَي الفِرق والوكالات. كل النقاط تحت https://api.naasher.com/api/sdk/v1، والتوثيق التفاعلي على api.naasher.com/docs.

المصادقة

أنشئ مفتاحًا من الإعدادات ← المطوّرون ← مفاتيح API، ثم أرسله في كل طلب:

curl https://api.naasher.com/api/sdk/v1/posts \
  -H "x-naasher-api-key: $NAASHER_API_KEY"

أو عبر ترويسة Authorization:

curl https://api.naasher.com/api/sdk/v1/posts \
  -H "Authorization: Bearer $NAASHER_API_KEY"

المفتاح يُعرض مرة واحدة

لا نحتفظ بالمفتاح كنص ظاهر — نخزّن بصمته فقط. إن فقدته أنشئ مفتاحًا جديدًا واحذف القديم.

OAuth 2.1 للوكلاء والتطبيقات

استخدم Authorization Code مع PKCE (S256) عندما يعمل التطبيق نيابةً عن مستخدم. يبدأ الاكتشاف من:

https://api.naasher.com/.well-known/oauth-authorization-server

سجّل العميل ديناميكيًا عبر نقطة registration_endpoint المنشورة، ثم أرسل resource=https://api.naasher.com/api/sdk/v1 في طلبَي التفويض والرمز. يربط ناشر الموافقة بمساحة عمل يختارها المستخدم، ولا يمنح إلا النطاقات التي تسمح بها عضويته الحالية. استخدم رمز التحديث للحصول على رمز وصول جديد، ونقطة الإلغاء المنشورة لإنهاء التفويض.

أي نوع مصادقة أختار؟

استخدم مفتاح API للأتمتة الداخلية الثابتة، وOAuth لتطبيقات الوكلاء أو العملاء المتعددين التي تحتاج موافقة المستخدم ودوران الرموز دون مشاركة مفتاح طويل العمر.

النطاقات (Scopes)

امنح كل مفتاح أقل صلاحية يحتاجها:

النطاقيسمح بـ
channels:readقراءة الحسابات المتصلة
channels:updateإدارة إعدادات الوجهات المرتبطة بالحسابات
posts:readقراءة المنشورات
posts:createإنشاء منشور
posts:updateتعديل سجل منشور موجود
posts:scheduleجدولة منشور
posts:publishنشر منشور أو إعادة محاولة نشره عبر المزوّد
posts:deleteحذف منشور
posts:shareإنشاء روابط مشاركة المنشور وقراءتها وإلغاؤها
media:readقراءة سجلات الوسائط
media:uploadبدء رفع وسيط وتأكيد اكتماله
media:updateتعديل بيانات الوسيط
media:deleteحذف سجل وسيط
schedule:readقراءة التقويم وفترات الجدولة
schedule:updateإنشاء فترات الجدولة وتعديلها وحذفها
analytics:readقراءة التحليلات
webhooks:readقراءة روابط الويب هوك
webhooks:createإنشاء رابط ويب هوك
webhooks:deleteحذف رابط ويب هوك
*بدل شامل حقيقي يجتاز كل فحص نطاق، بما في ذلك النطاقات المضافة لاحقًا

النطاق * ليس اختصارًا للصفوف الموجودة وقت إنشاء المفتاح فقط؛ يعامله الخادم بوصفه بدلًا شاملًا حقيقيًا يقبل كل صلاحية مطلوبة. تجنّبه ما لم يحتج المتصل فعلًا إلى وصول غير مقيّد، وابدأ بنطاقات القراءة ثم أضف كل نطاق كتابة على حدة.

نقاط النهاية

المنشورات

الطريقةالمسارالوصف
GET/postsقائمة المنشورات مع ترقيم وفلاتر
POST/postsإنشاء منشور (مسودة أو مجدول)
GET/posts/:idتفاصيل منشور
POST/posts/:id/scheduleجدولة منشور موجود
DELETE/posts/:idحذف منشور

مثال — إنشاء منشور مجدول:

curl -X POST https://api.naasher.com/api/sdk/v1/posts \
  -H "x-naasher-api-key: $NAASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "أطلقنا اليوم تحديثنا الجديد ☕️",
    "channelIds": ["ch_123"],
    "scheduledAt": "2026-08-01T08:30:00.000Z"
  }'

الحسابات

الطريقةالمسارالوصف
GET/channelsقائمة الحسابات المتصلة
GET/channels/:idتفاصيل حساب

التحليلات

الطريقةالمسارالوصف
GET/analyticsملخّص الوصول والتفاعل والنمو

الويب هوكس

الطريقةالمسارالوصف
GET/webhooksقائمة الروابط
POST/webhooksإنشاء رابط
DELETE/webhooks/:idحذف رابط

راجع صفحة الويب هوكس للتحقق من التوقيع.

الحدود والأخطاء

الطلبات محدودة المعدّل لكل عنوان IP ولكل مفتاح. تقرأ العملاء الحديثة السياسة والحصة المتبقية من RateLimit-Policy وRateLimit، وتتوفر كذلك ترويسات RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset للتوافق. عند تجاوز الحد تحصل على 429 مع Retry-After. جميع هذه الترويسات موثقة في OpenAPI ومتاحة لعملاء المتصفح عبر CORS. الأخطاء تعود بشكل موحّد:

{ "error": { "code": "billing:feature_not_in_plan", "message": "API access is available on Teams and Agency." } }

الرمز (code) ثابت وصالح للاعتماد عليه برمجيًا؛ النص (message) قد يتغير.

الإصدار والإهمال التدريجي

المسار /api/sdk/v1 هو الإصدار الرئيسي المستقر الحالي. لا نحذف حقولًا أو نغيّر معناها داخل الإصدار نفسه؛ التغييرات غير المتوافقة تنتقل إلى إصدار رئيسي جديد. راجع سياسة دورة حياة Naasher API لمعرفة ترويسات Deprecation وSunset وفترة الانتقال الدنيا.

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

الردّ على التفاعلات من صندوق واحد، وقراءة أداء المحتوى بأرقام تثق بها.

دورة حياة واجهة Naasher API

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