مركز المساعدة

أدر مقالات مركز المساعدة في المشروع وفئاتها. يتطلّب تفعيل مركز المساعدة للمشروع — فحين يكون مطفأً، تعيد كل نقطة نهاية أدناه 404.

متون المقالات بتنسيق Markdown، لا HTML. وتعرضها البوابة عبر عارض لا يُنفّذ HTML الخام أبدًا، فأي HTML ترسله يُعرض للقرّاء كنص حرفي.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	التصفية حسب الحالة: draft أو published أو archived.
`category_id`	`string`	المقالات في هذه الفئة فقط.
`limit`	`integer`	حجم الصفحة. الافتراضي 25، والحد الأقصى 100.
`offset`	`integer`	عدد العناصر المراد تخطّيها. الافتراضي 0.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	استعلام البحث. يدعم العبارات بين علامات اقتباس، وOR، والنفي بـ -.
`limit`	`integer`	عدد النتائج. الافتراضي 25، والحد الأقصى 100.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	حتى 200 حرف.
`body`	`string`	Markdown. حتى 50,000 حرف.
`excerpt`	`string`	ملخّص من سطر واحد، حتى 300 حرف. يُشتق من المتن عند حذفه.
`slug`	`string`	مقطع العنوان، حتى 80 حرفًا. يُشتق من العنوان عند حذفه.
`category_id`	`string`	الفئة التي يُصنَّف المقال تحتها.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	عنوان جديد.
`body`	`string`	متن Markdown جديد.
`excerpt`	`string`	ملخّص جديد؛ وnull يمسحه.
`slug`	`string`	مقطع عنوان جديد.
`category_id`	`string`	فئة جديدة؛ وnull يجعل المقال غير مصنّف.
`status`	`string`	draft أو published أو archived.

DELETE/v1/articles/:id

تُنشأ المقالات دائمًا كـمسودات — والنشر عملية PATCH منفصلة، فلا يصل شيء إلى بوابتك عرضًا. ويتطلّب إنشاء مقال وصول كتابة بخطة مدفوعة، وكذلك كل طريقة تعديل أخرى هنا.

سرد المقالات


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "How do I reset my password?",
      "slug": "how-do-i-reset-my-password",
      "body": "Open **Settings**, then choose *Reset password*.",
      "excerpt": "Open Settings, then choose Reset password.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

بلا تصفية، يعيد هذا المسودات والمقالات المؤرشفة أيضًا، بأحدث تحرير أولاً. مرّر status=published للحصول على ما يستطيع العملاء رؤيته فعلاً.

البحث في المقالات


curl "https://api.supdesk.app/v1/articles/search?q=reset+password&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "How do I reset my password?",
      "slug": "how-do-i-reset-my-password",
      "category_slug": "getting-started",
      "category_name": "Getting started",
      "snippet": "Open Settings, then choose Reset password.",
      "rank": 0.6079
    }
  ]
}

بحث نصّي كامل على المقالات المنشورة فقط، مُرتَّب، مع مقتطف بنص عادي حول التطابق. وتُرجَّح العناوين فوق الملخّصات، والملخّصات فوق المتون. أما الاستعلام الفارغ أو غير القابل للتحليل فيعيد قائمة فارغة بدلاً من خطأ.

جلب مقال


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

يعيد مقالاً واحدًا بالشكل نفسه الذي في القائمة، أو 404 عندما يكون المعرّف غير معروف في مشروعك.

إنشاء مقال


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How do I reset my password?",
    "body": "Open **Settings**, then choose *Reset password*.",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "How do I reset my password?",
    "slug": "how-do-i-reset-my-password",
    "body": "Open **Settings**, then choose *Reset password*.",
    "excerpt": "Open Settings, then choose Reset password.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

يعيد 201. وحذف slug يشتق واحدًا من العنوان، مع لاحقة -2 أو -3… إن كان ذلك العنوان مأخوذًا. وحذف excerpt يشتق واحدًا من المتن.

تحدّ خطتك عدد المقالات التي يمكن للمشروع الاحتفاظ بها — Free 5، وPro 50، وTeam بلا حدود. وبعد السقف يعيد هذا limit_reached (429). والمقالات المؤرشفة لا تُحتسب، فأرشفة واحد تحرّر مكانًا.

تحديث مقال


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

تُكتب الحقول التي ترسلها وحدها، فـ PATCH لا يفرّغ أبدًا شيئًا تركته. وضبط status على published يختم published_at أول مرة ويحافظ عليه بعدها — فتصحيح خطأ إملائي لا يجعل مقالاً قديمًا يبدو جديدًا. وضبطه على archived يُخرج المقال من الخدمة دون حذفه.

وإخراج مقال من الأرشيف يعيد فحص سقف الخطة، وقد يعيد limit_reached.

حذف مقال


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

يحذف المقال وملاحظات قرّائه نهائيًا، ويعيد 204. ولإخراج مقال من الخدمة مع الاحتفاظ به، اضبط حالته على archived بدلاً من ذلك.

الفئات

GET/v1/article-categories

Parameter	Type	Description
`limit`	`integer`	حجم الصفحة. الافتراضي 25، والحد الأقصى 100.
`offset`	`integer`	عدد العناصر المراد تخطّيها. الافتراضي 0.

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	حتى 80 حرفًا.
`description`	`string`	يظهر في البوابة، حتى 300 حرف.
`sort_order`	`integer`	موضع العرض. الافتراضي 0.

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	اسم جديد.
`description`	`string`	وصف جديد؛ وnull يمسحه.
`sort_order`	`integer`	موضع عرض جديد.

DELETE/v1/article-categories/:id


curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Getting started", "sort_order": 1 }'


{
  "data": {
    "id": "3c2b...",
    "name": "Getting started",
    "slug": "getting-started",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

تُسرد الفئات حسب sort_order، ثم حسب الاسم. وتُشتق الـ slugs من الاسم بالطريقة نفسها التي تُشتق بها slugs المقالات من العنوان.

حذف فئة يعيد 204 ولا يحذف مقالاتها — فتصبح غير مصنّفة وتبقى متاحة عبر البحث ومن الصفحة الأولى لمركز المساعدة.

الأخطاء

إلى جانب الرموز القياسية:

الرمز	الحالة	متى
`not_found`	404	معرّف غير معروف — أو أن مركز المساعدة مطفأ لهذا المشروع.
`forbidden`	403	كتابة على خطة بلا وصول كتابة إلى API.
`limit_reached`	429	نفدت حصة مقالات الخطة.