מרכז עזרה

נהלו את מאמרי מרכז העזרה של הפרויקט ואת הקטגוריות שלהם. דורש שמרכז העזרה יהיה מופעל בפרויקט — כשהוא כבוי, כל נקודת קצה למטה מחזירה 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	מכסת המאמרים של התוכנית מוצתה.