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

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

[English](/en/api)

واجهة ناشر البرمجية متاحة في باقتَي **الفِرق** و**الوكالات**. كل النقاط تحت `https://api.naasher.com/api/sdk/v1`، والتوثيق التفاعلي على [api.naasher.com/docs](https://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 للوكلاء والتطبيقات](#oauth-21-للوكلاء-والتطبيقات)

استخدم **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)](#النطاقات-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 | حذف رابط      |

راجع [صفحة الويب هوكس](/webhooks) للتحقق من التوقيع.

## [الحدود والأخطاء](#الحدود-والأخطاء)

الطلبات محدودة المعدّل لكل عنوان 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](/api-lifecycle) لمعرفة ترويسات `Deprecation` و`Sunset` وفترة الانتقال الدنيا.

[الوارد والتحليلاتالردّ على التفاعلات من صندوق واحد، وقراءة أداء المحتوى بأرقام تثق بها.](/inbox-analytics)[دورة حياة واجهة Naasher APIسياسة إصدارات واجهة ناشر البرمجية، والتوافق، والإهمال التدريجي، ومواعيد الإيقاف.](/api-lifecycle)

---

Canonical URL: https://docs.naasher.com/api