# API שאלות נפוצות (FAQs)

שאלות נפוצות (FAQs) הן רשומות של שאלות ותשובות שהבוט מבוסס הבינה המלאכותית שלך מסתמך עליהן בעת מענה ללקוחות. כל שאלה נפוצה שייכת לחשבון שלך וניתן לקשר אותה לקמפיין אחד או יותר, כך שניתן לעשות שימוש חוזר באותה תשובה בכל מקום רלוונטי. ה-API של השאלות הנפוצות מאפשר לך לנהל את הספרייה הזו באופן תכנותי — ליצור, לעדכן, לייבא בכמות גדולה, לשנות סדר ולקשר שאלות נפוצות לקמפיינים ישירות מהקוד שלך.

כל נקודות הקצה להלן יחסיות לכתובת ה-URL הבסיסית `https://api.youraiconnector.com/v1`. כל בקשה חייבת לעבור אימות — ראה [גישה ל-API](../integrations/api-access.md) ו-[אימות](authentication.md). גישה ל-API היא תכונה בתשלום; ללא גישה זו, בקשות יידחו עם `403`.

> **כיצד הבוט משתמש בשאלה נפוצה:** כאשר אתה יוצר או משנה שאלה נפוצה, הפלטפורמה מכינה את נתוני החיפוש שלה (המשמשים להתאמת השאלה הנפוצה לשאלות נכנסות) ברקע. תהליך זה מסתיים בדרך כלל תוך מספר שניות, ולאחריו הבוט מתחיל להשתמש ברשומה באופן אוטומטי.


---

## אובייקט השאלה הנפוצה (FAQ)

לכל שאלה נפוצה שחוזרת מה-API יש את המבנה הבא:

| שדה | סוג | תיאור |
|---|---|---|
| `id` | string | המזהה הייחודי של ה-FAQ. |
| `question` | string | שאלת הלקוח שערך זה עונה עליה. |
| `answer` | string | התשובה שהבוט מבוסס הבינה המלאכותית מספק. |
| `category` | string \| null | תווית קטגוריה חופשית אופציונלית. |
| `tags` | string[] | תוויות אופציונליות לארגון שאלות נפוצות. |
| `is_active` | boolean | האם לבוט מותר להשתמש ב-FAQ זה. ברירת המחדל היא `true`. |
| `is_global` | boolean | מסמן את ה-FAQ ככזה שאינו קשור לקמפיין או לסוכן ספציפי. זה לא גורם ל-FAQ לחול בכל מקום: FAQ משמש רק את הקמפיינים והסוכנים שאליהם הוא מקושר. ברירת המחדל היא `false`. |
| `usage_count` | integer | כמה פעמים נעשה שימוש ב-FAQ זה בתשובות של הבינה המלאכותית. |
| `order_index` | integer | מיקום התצוגה של FAQ זה בתוך הקמפיין שלו. |
| `campaign_ids` | string[] | מזהים של הקמפיינים שאליהם FAQ זה מקושר. |
| `created_at` | string \| null | חותמת זמן בפורמט ISO 8601 של מועד יצירת ה-FAQ. |
| `updated_at` | string \| null | חותמת זמן בפורמט ISO 8601 של השינוי האחרון. |

השדות שניתן **להגדיר** הם: `question`, `answer`, `is_active`, `is_global`, `category`, `tags`, ו-`order_index`. הפלטפורמה מנהלת את כל השאר (נתוני חיפוש, ספירות שימוש, חותמות זמן); כל שדה אחר בגוף הבקשה שלך יתעלם.

---

## רשימת שאלות נפוצות

`GET /faqs`

מחזיר את השאלות הנפוצות בחשבונך, מהחדשה ביותר לישנה ביותר. ניתן לסנן לפי קמפיין בודד או לפי מצב פעיל.

**פרמטרים של שאילתה**

| פרמטר | נדרש | תיאור |
|---|---|---|
| `campaign_id` | לא | החזר רק שאלות נפוצות המקושרות לקמפיין זה. |
| `is_active` | לא | החזר רק שאלות נפוצות עם מצב פעיל זה (`true` או `false`). מסנן זה מוחל לכל עמוד, לכן עמוד עשוי להכיל פחות פריטים מ-`limit`. |
| `limit` | לא | מספר מקסימלי של שאלות נפוצות לעמוד. ברירת המחדל היא `50`, המקסימום הוא `100`. |
| `cursor` | לא | מזהה שאלה נפוצה להמשך אחריו. העבר את הערך `next_cursor` מהעמוד הקודם. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.faqs, data.next_cursor);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs",
    params={"campaign_id": "campaign123", "limit": 50},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["faqs"], data["next_cursor"])
```

**תגובה**

```json
{
  "success": true,
  "faqs": [
    {
      "id": "aBcD1234eFgH5678",
      "question": "How long does shipping take?",
      "answer": "Standard shipping takes 3-5 business days.",
      "category": "shipping",
      "tags": ["logistics", "delivery"],
      "is_active": true,
      "is_global": false,
      "usage_count": 12,
      "order_index": 0,
      "campaign_ids": ["campaign123"],
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-02T08:30:00.000Z"
    }
  ],
  "next_cursor": "aBcD1234eFgH5678"
}
```

כאשר `next_cursor` הוא `null`, אין יותר תוצאות.

---

## קבלת שאלות נפוצות (FAQ)

`GET /faqs/{faqId}`

מחזיר שאלת FAQ בודדת לפי המזהה שלה.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { faq } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
faq = res.json()["faq"]
```

**תגובה**

```json
{
  "success": true,
  "faq": {
    "id": "aBcD1234eFgH5678",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"],
    "is_active": true,
    "is_global": false,
    "usage_count": 12,
    "order_index": 0,
    "campaign_ids": ["campaign123"],
    "created_at": "2026-01-01T12:00:00.000Z",
    "updated_at": "2026-01-02T08:30:00.000Z"
  }
}
```

---

## יצירת שאלת FAQ

`POST /faqs`

יוצר שאלת FAQ חדשה ומקשר אותה לקמפיין.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שאליו יש לקשר את ה-FAQ החדש. |
| `question` | כן | שאלת הלקוח שעליה עונה ערך זה. |
| `answer` | כן | התשובה שהבוט צריך לתת. |
| `is_active` | לא | האם הבוט רשאי להשתמש ב-FAQ זה. ברירת המחדל היא `true`. |
| `is_global` | לא | האם ה-FAQ חל על כל הקמפיינים. ברירת המחדל היא `false`. |
| `category` | לא | תווית קטגוריה חופשית. |
| `tags` | לא | מערך של תוויות. |
| `order_index` | לא | מיקום תצוגה בתוך הקמפיין. ברירת המחדל היא `0`. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    question: "How long does shipping take?",
    answer: "Standard shipping takes 3-5 business days.",
    category: "shipping",
    tags: ["logistics"],
  }),
});
const { faq_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "tags": ["logistics"],
    },
)
faq_id = res.json()["faq_id"]
```

**תגובה**

```json
{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## עדכון שאלות נפוצות (FAQ)

`PUT /faqs/{faqId}`

מעדכן חלקית שאלות נפוצות. רק השדות הניתנים לכתיבה שסופקו ישתנו; כל השאר שומרים על ערכם הנוכחי. שינוי ה-`question` או ה-`answer` מרענן באופן אוטומטי את נתוני החיפוש של השאלות הנפוצות ברקע.

אם תשלח `question` או `answer`, הם חייבים להיות מחרוזות שאינן ריקות. שליחת שדות שאינם מזוהים כניתנים לכתיבה תחזיר `400`.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_active: false }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## מחיקת שאלות נפוצות (FAQ)

`DELETE /faqs/{faqId}`

מוחק לצמיתות שאלות נפוצות. ניתן להעביר באופן אופציונלי את `campaign_id` כפרמטר שאילתה כדי להסיר גם את השאלות הנפוצות מרשימת השאלות הנפוצות של אותו קמפיין.

**פרמטרים של שאילתה**

| פרמטר | נדרש | תיאור |
|---|---|---|
| `campaign_id` | לא | הסר גם את ה-FAQ מרשימת ה-FAQ של קמפיין זה. |

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    params={"campaign_id": "campaign123"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true
}
```

---

## מחיקה מרוכזת של שאלות נפוצות (FAQs)

`POST /faqs/bulk-delete`

מוחק עד 500 שאלות נפוצות בבקשה אחת. כאשר `campaign_id` מסופק, השאלות הנפוצות שנמחקו מוסרות גם מרשימת ה-FAQ של אותו קמפיין.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `faq_ids` | כן | מערך לא ריק של מזהי FAQ למחיקה (מקסימום 500). |
| `campaign_id` | לא | הסר גם את השאלות הנפוצות שנמחקו מרשימת ה-FAQ של קמפיין זה. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/bulk-delete", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq_ids: ["faqId1", "faqId2"],
    campaign_id: "campaign123",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/bulk-delete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "deleted_count": 2
}
```

---

## שאלות נפוצות (FAQs) לייבוא

`POST /faqs/import`

ייבוא מרוכז של עד 500 שאלות נפוצות וקישורן לקמפיין אחד. פריטים שה-`question` שלהם תואם לשאלה נפוצה קיימת בספרייה שלך (ללא תלות באותיות רישיות/קטנות) **יעודכנו** במקום ליצור כפילות.

> **טיפ לביצועים:** התאמת כפילויות סורקת את כל ספריית השאלות הנפוצות שלך, לכן ספריות גדולות מאוד הופכות את הייבוא לאיטי יותר. העדף ייבוא של מספר קטן של קבצים גדולים על פני ייבוא של קבצים קטנים רבים.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שאליו מקושרות כל השאלות הנפוצות המיובאות. |
| `faqs` | כן | מערך לא ריק של פריטי שאלות נפוצות (מקסימום 500). לכל פריט חייבים להיות `question` ו-`answer` לא ריקים; הוא עשוי לכלול גם `is_active`, `is_global`, `category`, `tags`, ו-`order_index`. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "faqs": [
      { "question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide." },
      { "question": "What is your return policy?", "answer": "You can return any item within 30 days." }
    ]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    faqs: [
      {
        question: "Do you ship internationally?",
        answer: "Yes, we ship to most countries worldwide.",
      },
      {
        question: "What is your return policy?",
        answer: "You can return any item within 30 days.",
      },
    ],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "faqs": [
            {"question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide."},
            {"question": "What is your return policy?", "answer": "You can return any item within 30 days."},
        ],
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "faq_ids": ["aBcD1234eFgH5678", "iJkL9012mNoP3456"],
  "imported_count": 2
}
```

`faq_ids` הם מזהי השאלות הנפוצות שנוצרו או עודכנו, לפי הסדר שבו סיפקת אותם.

---

## סידור מחדש של שאלות נפוצות

`POST /faqs/reorder`

קובע את סדר התצוגה של השאלות הנפוצות בקמפיין. ספק את הרשימה ה**מלאה** של מזהי השאלות הנפוצות בסדר הרצוי; המיקום של כל שאלה נפוצה יעודכן בהתאם למיקומה במערך.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שאת השאלות הנפוצות שלו משנים את סדרן. |
| `ordered_faq_ids` | כן | מערך לא ריק של כל מזהי השאלות הנפוצות של הקמפיין בסדר התצוגה הרצוי (מקסימום 500). |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/reorder", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    ordered_faq_ids: ["faqId2", "faqId1", "faqId3"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"],
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true
}
```

אם הקמפיין או אחד ממזהי השאלות הנפוצות לא נמצא בחשבונך, הבקשה תחזיר `404 One or more FAQs were not found`.

---

## קישור שאלה נפוצה לקמפיין

`POST /faqs/{faqId}/link`

מקשר שאלה נפוצה קיימת לקמפיין נוסף. ניתן לשתף שאלה נפוצה בין כל מספר של קמפיינים, כך שצריך לתחזק את אותה תשובה פעם אחת בלבד.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שאליו יש לקשר את השאלה הנפוצה. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}
```

---

## ביטול קישור של שאלות נפוצות לקמפיין

`POST /faqs/{faqId}/unlink`

מסיר שאלות נפוצות מקמפיין מבלי למחוק את השאלות עצמן. השאלות הנפוצות נשארות בספרייה שלך וממשיכות להיות מקושרות לכל קמפיין אחר.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שממנו יש להסיר את השאלות הנפוצות. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}
```

---

## בנייה מחדש של נתוני החיפוש עבור שאלות נפוצות

`POST /faqs/{faqId}/rebuild-embeddings`

מכניס לתור בנייה מחדש של הנתונים שבהם משתמש הבוט מבוסס הבינה המלאכותית כדי למצוא שאלות נפוצות אלו (נתוני החיפוש הסמנטי וחיפוש מילות המפתח). פעולה זו שימושית אם שאלות נפוצות אינן מופיעות בתשובות כצפוי. הבנייה מחדש מתבצעת ברקע ובדרך כלל מסתיימת תוך מספר שניות; ייתכן שהשאלות הנפוצות יוחרגו זמנית מתשובות הבינה המלאכותית בזמן שהן נבנות מחדש.

נקודת קצה זו מחזירה `202 Accepted` מכיוון שהעבודה נמשכת לאחר שליחת התגובה. ה-`status` הוא תמיד `"processing"` — בצע אחזור חוזר של השאלות הנפוצות מאוחר יותר אם עליך לוודא את השלמת הפעולה.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "status": "processing"
}
```

---

## ניהול שאלות נפוצות בסיוע בינה מלאכותית

נקודות הקצה להלן חורגות מפעולות CRUD פשוטות: הן מפעילות את אותם כלי בינה מלאכותית שבהם משתמש עורך השאלות הנפוצות בלוח הבקרה — איתור כפילויות, יצירת ערכים מתוך מסמך, והתאמת שאלות נפוצות למשימות פתוחות של פערי ידע. גופי הבקשה בקבוצה זו משתמשים בשמות שדות `camelCase` (`campaignId`, `taskId`, `sourceIds`...), התואמים את מבני הבקשה של האפליקציה עצמה, ולא ב-`snake_case` המשמשים במקומות אחרים בדף זה — העתק את הדוגמאות להלן במקום לנחש את שם השדה.

### פיצול שאלה נפוצה לעותק המיועד לקמפיין בלבד

`POST /faqs/{faqId}/fork-for-campaign`

יוצר שאלה נפוצה חדשה שהיא עותק של שאלה קיימת, המוגבלת לקמפיין בודד, ומקשר מחדש את אותו קמפיין לעותק החדש במקום למקורי. השתמש בזה כאשר ברצונך להתאים אישית תשובה עבור קמפיין אחד מבלי לשנות אותה בכל מקום אחר שבו נעשה שימוש בשאלה המקורית. השאלה המקורית נשארת במקומה — היא רק מאבדת את הקישור לקמפיין זה.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `campaign_id` | כן | הקמפיין שעבורו יש להגביל את העותק החדש, ושממנו יש לקשר מחדש מהשאלה המקורית. |
| `question` | כן | השאלה עבור העותק החדש והספציפי לקמפיין. |
| `answer` | כן | התשובה עבור העותק החדש והספציפי לקמפיין. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign456",
    "question": "How long does shipping take to the EU?",
    "answer": "For EU orders, shipping takes 7-10 business days."
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "campaign456",
      question: "How long does shipping take to the EU?",
      answer: "For EU orders, shipping takes 7-10 business days.",
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign456",
        "question": "How long does shipping take to the EU?",
        "answer": "For EU orders, shipping takes 7-10 business days.",
    },
)
data = res.json()
```

**תגובה** — `201 Created`

```json
{
  "success": true,
  "faq_id": "nEwFaQiD9012mNoP",
  "campaign_id": "campaign456",
  "original_faq_id": "aBcD1234eFgH5678"
}
```

### מציאת שאלות נפוצות כמעט כפולות

`POST /faqs/dedupe`

מפעיל משימת רקע הסורקת את ספריית השאלות הנפוצות שלך עבור ערכים כמעט כפולים או חופפים וממזגת או מסירה אותם במקומות שבהם המערכת בטוחה בכך. שימושי לאחר ייבוא מרוכז, או לאחר כמה סבבים של שאלות נפוצות שנוצרו על ידי בינה מלאכותית שהותירו חפיפה בספרייה. ניתן להריץ רק משימת ניקוי כפילויות אחת בכל פעם עבור כל חשבון — הפעלת משימה שנייה בזמן שמשימה אחרת עדיין רצה תחזיר `409`.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `sourceIds` | לא | מערך של מזהי מקור של בסיס ידע כדי להגביל את ניקוי הכפילויות. השאר ריק כדי לסרוק את כל ספריית השאלות הנפוצות שלך. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={},
)
data = res.json()
```

**תגובה** — `202 Accepted`

```json
{
  "success": true,
  "job_id": "dedupJob_aBc123"
}
```

המשימה רצה ברקע ובדרך כלל לוקחת כמה דקות בספרייה גדולה. אין נקודת קצה נפרדת לסטטוס — בצע אחזור מחדש ל-[`GET /faqs`](#list-faqs) לאחר המתנה קצרה כדי לראות מה השתנה. כשתסיים לעבור על התוצאה, קרא לנקודת הקצה של הסגירה להלן כדי לנקות אותה.

### סגירת תוצאת בדיקת כפילויות

`POST /faqs/dedupe/dismiss`

מנקה את משימת ניקוי הכפילויות שהסתיימה כך שהיא תפסיק להופיע כתוצאה פעילה. פעולה אידמפוטנטית — בטוחה להפעלה גם אם אין מה לסגור. מחזירה `409` אם המשימה עדיין `queued` או `processing` (לא ניתן לסגור הרצה שטרם הסתיימה).

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe/dismiss", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{ "success": true }
```

### יצירת שאלות נפוצות ממסמכים שהועלו

`POST /faqs/generate-from-documents`

קורא מסמך אחד או יותר שכבר נמצאים באחסון הקבצים של החשבון שלך וגורם ל-AI לנסח שאלות נפוצות מתוכנם, תוך בדיקת הטיוטות מול הספרייה הקיימת שלך כדי לעשות שימוש חוזר או לעדכן רשומות במקום ליצור כפילויות. התוצאות **אינן** נכתבות באופן מיידי — הן נשמרות כקבוצת שינויים ממתינה בקמפיין כדי שתוכל לעבור עליהן, ולאחר מכן מוחלות (או נמחקות) באמצעות [החלת שינויי שאלות נפוצות שנסקרו](#apply-reviewed-faq-changes) להלן. פעולה זו כרוכה בעלות קרדיטים, מכיוון שמדובר במעבר יצירה של AI על טקסט המסמך.

נקודת קצה זו אינה נושאת את הקובץ: `storagePath` חייב להצביע על קובץ שכבר נמצא תחת תיקיית ההעלאות שלך (`users/{your user id}/uploads/`), לפי אותה מוסכמה כמו [ייבוא מסמך שהועלה](knowledge-base.md#import-an-uploaded-document) ב-API של מאגר הידע.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `campaignId` | כן | הקמפיין שעבורו מוצעות השאלות הנפוצות שנוצרו. |
| `uploadedFiles` | כן | מערך לא ריק של קבצים לקריאה, כל אחד `{ storagePath, fileName, mimeType }`. `storagePath` חייב להתחיל ב-`users/{your user id}/uploads/`. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/generate-from-documents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "uploadedFiles": [
      { "storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf" }
    ]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/generate-from-documents", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    uploadedFiles: [
      { storagePath: "users/abc123uid/uploads/handbook.pdf", fileName: "handbook.pdf", mimeType: "application/pdf" },
    ],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/generate-from-documents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "uploadedFiles": [
            {"storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf"},
        ],
    },
)
data = res.json()
```

**תגובה** — `202 Accepted`

```json
{
  "success": true,
  "faqCount": 6,
  "reusedCount": 2,
  "modifiedCount": 1,
  "newCount": 3
}
```

`faqCount` הוא המספר הכולל של שינויים מוצעים הממתינים לבדיקה; `reusedCount`, `modifiedCount` ו-`newCount` מפרקים זאת לשאלות נפוצות שתואמות לרשומה קיימת ללא שינוי, כאלו שה-AI מציע לערוך, וכאלו שהן חדשות לגמרי. קבצים שהועלו נמחקים מהאחסון ברגע שהעיבוד מסתיים, בין אם הוא מצליח ובין אם לא.

### החלת שינויי שאלות נפוצות שנסקרו

`POST /faqs/apply-optimization`

מחיל (או מוחק) קבוצה ממתינה של שינויי שאלות נפוצות שהוצעו על ידי ה-AI — הסוג שנוצר על ידי [יצירת שאלות נפוצות ממסמכים](#generate-faqs-from-uploaded-documents) לעיל, או על ידי סקירת אופטימיזציית השאלות הנפוצות בלוח הבקרה. אתה בוחר בדיוק אילו שינויים מוצעים לקבל; כל מה שלא ציינת נשאר ללא שינוי (שינוי שהושמט לעולם אינו מטופל כדחייה שמוחקת משהו).

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `campaignId` | אחד משניים אלו | הקמפיין ששינויי השאלות הנפוצות הממתינים שלו מוחלים. |
| `agentId` | אחד משניים אלו | סוכן ה-AI ששינויי השאלות הנפוצות הממתינים שלו מוחלים, בחשבון מבוסס סוכן. ספק בדיוק אחד מ-`campaignId` / `agentId`, לעולם לא את שניהם. |
| `acceptedChanges` | כן | מערך השינויים שאתה מקבל, כל אחד `{ action, faq_id?, faq_ref_path?, question?, answer?, edit_scope? }`. `action` הוא אחד מ-`keep`, `remove`, `add_from_library`, `create_new`, `modify`. שלח מערך ריק כדי למחוק את הקבוצה הממתינה מבלי להחיל דבר. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/apply-optimization?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "acceptedChanges": [
      { "action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days." },
      { "action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId" }
    ]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/apply-optimization", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    acceptedChanges: [
      { action: "create_new", question: "Do you ship to the EU?", answer: "Yes, EU shipping takes 7-10 business days." },
      { action: "remove", faq_ref_path: "users/abc123uid/faqs/oldFaqId" },
    ],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/apply-optimization",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "acceptedChanges": [
            {"action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days."},
            {"action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId"},
        ],
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "message": "Applied 2 FAQ changes",
  "faq_count": 7
}
```

`faq_count` הוא סך כל השאלות הנפוצות המקושרות של הקמפיין (או הסוכן) לאחר ההחלה. אם לא הייתה קבוצת שינויים ממתינה להחלה, התגובה היא `{ "success": true, "message": "No pending FAQ changes to apply" }`.

### מציאת שאלות נפוצות דומות למשימה

`POST /faqs/similar-for-task`

מדרג את ספריית השאלות הנפוצות שלך לפי רלוונטיות לשאלה של משימת פער ידע — אותה בדיקה שנמצאת מאחורי בורר "השתמש בשאלה נפוצה קיימת" בלוח הבקרה. לקריאה בלבד. `taskId` חייב להצביע על משימה מסוג `faq_update`.

נקודת קצה זו תמיד משיבה `200`, גם במקרה של כשל צפוי כמו משימה לא ידועה — בדוק את `success` בגוף התגובה במקום את סטטוס ה-HTTP.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `taskId` | כן | משימת ה-`faq_update` שעבורה יש למצוא התאמות. |
| `limit` | לא | מספר התאמות מרבי להחזרה. ברירת המחדל היא 20, עם תקרה של 50. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/similar-for-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "limit": 10 }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/similar-for-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", limit: 10 }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/similar-for-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "limit": 10},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "task_id": "task789",
    "matches": [
      {
        "faq_id": "aBcD1234eFgH5678",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "created_at": "2026-01-01T12:00:00.000Z",
        "similarity": 0.81,
        "embedding_similarity": 0.81,
        "keyword_similarity": 0.6,
        "bm25_score": 4.2,
        "distance": 0.19
      }
    ]
  }
}
```

ההתאמות ממוינות לפי `similarity` (התאמה סמנטית כשהיא זמינה, או חפיפת מילות מפתח אחרת), מהטובה ביותר לראשונה. במקרה של כשל רך, המבנה הוא `{ "success": false, "error": "...", "error_code": 404 }` — `error_code` משקף את מה שהיה אמור להיות סטטוס ה-HTTP בדרך כלל.

### פתרון משימה באמצעות שאלות נפוצות (FAQ) קיימות

`POST /faqs/resolve-task`

פותר משימת פער ידע על ידי קישורה לשאלות נפוצות (FAQ) שכבר קיימות אצלך (במקום כתיבת חדשות), שולח את התשובה של אותן שאלות נפוצות לאיש הקשר שהפעיל את הפער, ומסמן את המשימה כהושלמה. השתמש בזה לאחר ש-[מציאת שאלות נפוצות דומות למשימה](#find-faqs-similar-to-a-task) מעלה שאלות נפוצות קיימות שכבר מכסות את השאלה.

בדומה לנקודת הקצה שלעיל, זו תמיד משיבה `200` — בדוק את `success` בגוף התגובה.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `taskId` | כן | משימת ה-`faq_update` לפתרון. |
| `faqId` | כן | השאלות הנפוצות (FAQ) הקיימות לקישור ושליחה כתשובה. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/faqs/resolve-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "faqId": "aBcD1234eFgH5678" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/faqs/resolve-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", faqId: "aBcD1234eFgH5678" }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/resolve-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "faqId": "aBcD1234eFgH5678"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "task_id": "task789",
    "faq_id": "aBcD1234eFgH5678",
    "follow_up_status": "published"
  }
}
```

`follow_up_status` מדווח לך מה קרה עם המשך הטיפול באיש הקשר: `published` (נשלח מיד), `queued` (ה-AI כבר היה באמצע מענה לאיש קשר זה, לכן זה יישלח בהמשך), `skipped_no_contact` (למשימה אין איש קשר מקושר), או `skipped_no_campaign` (אין קמפיין שדרכו ניתן לשלוח את זה).

---

## שגיאות API של שאלות נפוצות (FAQs)

נקודות קצה של שאלות נפוצות מחזירות את מעטפת השגיאה הסטנדרטית:

```json
{
  "success": false,
  "error": "FAQ not found"
}
```

| סטטוס | מתי זה קורה בנקודת קצה של שאלות נפוצות (FAQ) |
|---|---|
| `400` | שדה נדרש חסר או לא תקין (למשל `question` ריק, `campaign_id` חסר, או יותר מ-500 פריטים בבקשה מרוכזת). |
| `404` | השאלות הנפוצות או הקמפיין לא נמצאו — או שהם לא קיימים או שהם שייכים לחשבון אחר. |
| `409` | `POST /faqs/dedupe` נקרא בזמן שעבודת מניעת כפילויות כבר `queued`/`processing`, או ש-`POST /faqs/dedupe/dismiss` נקרא בזמן שהעבודה טרם הסתיימה. |

הקודים המשותפים שכל נקודת קצה יכולה להחזיר — `401`, `403` (התוכנית שלך אינה כוללת גישת API), `429` (מגבלת קצב) ו-`500` — מפורטים עם הנחיות לניסיון חוזר ב-[שגיאות ועימוד](errors-and-pagination.md).

`POST /faqs/similar-for-task` ו-`POST /faqs/resolve-task` הם שני החריגים בדף זה: הם משיבים `200` גם עבור כשל צפוי (משימה לא ידועה, סוג משימה שגוי) ומציבים את הסטטוס האמיתי ב-`error_code` שבגוף התגובה במקום זאת — ראה כל נקודת קצה לעיל.

---

## קשור

- [API של קמפיינים](campaigns.md) — הקמפיינים שאליהם מקושרות השאלות הנפוצות שלך.
- [API של בסיס ידע](knowledge-base.md) — ייבוא אתרים ומסמכים לשאלות נפוצות באופן אוטומטי, וריכוז שאלות נפוצות לקבוצות ידע לשימוש חוזר.
- [גישת API](../integrations/api-access.md) — יצירת מפתח ה-API שלך.
- [אימות](authentication.md) — כל הדרכים להעברת המפתח שלך.