# واجهة برمجة تطبيقات الأسئلة الشائعة (FAQs API)

الأسئلة الشائعة (FAQs) هي مدخلات الأسئلة والأجوبة التي يستعين بها روبوت الذكاء الاصطناعي الخاص بك عند الرد على العملاء. تنتمي كل فقرة أسئلة شائعة إلى حسابك ويمكن ربطها بحملة واحدة أو أكثر، بحيث يمكن إعادة استخدام نفس الإجابة في أي مكان تكون فيه ذات صلة. تتيح لك واجهة برمجة تطبيقات الأسئلة الشائعة إدارة تلك المكتبة برمجياً — إنشاء الأسئلة الشائعة، وتحديثها، واستيرادها بكميات كبيرة، وإعادة ترتيبها، وربطها بالحملات من خلال الكود الخاص بك.

جميع نقاط النهاية أدناه نسبية إلى عنوان URL الأساسي `https://api.youraiconnector.com/v1`. يجب أن تكون كل طلبية مصادقاً عليها — راجع [الوصول إلى واجهة برمجة التطبيقات](../integrations/api-access.md) و[المصادقة](authentication.md). الوصول إلى واجهة برمجة التطبيقات هو ميزة مدفوعة؛ وبدونها، يتم رفض الطلبات مع `403`.

> **كيف يستخدم الروبوت الأسئلة الشائعة:** عند إنشاء أو تغيير سؤال شائع، تقوم المنصة بإعداد بيانات البحث الخاصة به (المستخدمة لمطابقة السؤال الشائع مع الأسئلة الواردة) في الخلفية. عادة ما ينتهي هذا في غضون ثوانٍ قليلة، وبعد ذلك يبدأ الروبوت في استخدام المدخل تلقائياً.


---

## كائن الأسئلة الشائعة (FAQ object)

كل سؤال شائع يتم استرجاعه من واجهة برمجة التطبيقات له هذا الشكل:

| الحقل | النوع | الوصف |
|---|---|---|
| `id` | string | المعرف الفريد للأسئلة الشائعة. |
| `question` | string | سؤال العميل الذي تجيب عليه هذه المدخلة. |
| `answer` | string | الإجابة التي يقدمها روبوت الذكاء الاصطناعي. |
| `category` | string \| null | تسمية فئة اختيارية حرة. |
| `tags` | string[] | تسميات اختيارية لتنظيم الأسئلة الشائعة. |
| `is_active` | boolean | ما إذا كان مسموحاً للروبوت باستخدام هذه الأسئلة الشائعة. القيمة الافتراضية هي `true`. |
| `is_global` | boolean | يحدد أن الأسئلة الشائعة غير مرتبطة بحملة أو وكيل محدد. هذا لا يعني تطبيق الأسئلة الشائعة في كل مكان: تُستخدم الأسئلة الشائعة فقط من قبل الحملات والوكلاء المرتبطين بها. القيمة الافتراضية هي `false`. |
| `usage_count` | integer | عدد المرات التي تم فيها استخدام هذه الأسئلة الشائعة في ردود الذكاء الاصطناعي. |
| `order_index` | integer | موقع عرض هذه الأسئلة الشائعة ضمن حملتها. |
| `campaign_ids` | string[] | معرفات الحملات المرتبطة بهذه الأسئلة الشائعة. |
| `created_at` | string \| null | طابع زمني بتنسيق ISO 8601 يوضح وقت إنشاء الأسئلة الشائعة. |
| `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}`

إرجاع سؤال شائع واحد بواسطة معرفه (ID).

**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`

إنشاء سؤال شائع جديد وربطه بحملة.

**حقول الطلب**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `campaign_id` | نعم | الحملة التي سيتم ربط الأسئلة الشائعة الجديدة بها. |
| `question` | نعم | سؤال العميل الذي تجيب عليه هذه المدخلة. |
| `answer` | نعم | الإجابة التي يجب أن يقدمها البوت. |
| `is_active` | لا | ما إذا كان بإمكان البوت استخدام هذه الأسئلة الشائعة. القيمة الافتراضية هي `true`. |
| `is_global` | لا | ما إذا كانت الأسئلة الشائعة تنطبق على جميع الحملات. القيمة الافتراضية هي `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"
}
```

---

## تحديث الأسئلة الشائعة

`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"
}
```

---

## حذف الأسئلة الشائعة

`DELETE /faqs/{faqId}`

يحذف الأسئلة الشائعة نهائياً. يمكنك اختيارياً تمرير `campaign_id` كمعامل استعلام لإزالة الأسئلة الشائعة أيضاً من قائمة الأسئلة الشائعة الخاصة بتلك الحملة.

**معلمات الاستعلام**

| المعلمة | مطلوبة | الوصف |
|---|---|---|
| `campaign_id` | لا | قم أيضًا بإزالة الأسئلة الشائعة من قائمة الأسئلة الشائعة الخاصة بهذه الحملة. |

**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
}
```

---

## حذف الأسئلة الشائعة بالجملة

`POST /faqs/bulk-delete`

يحذف ما يصل إلى 500 سؤال شائع في طلب واحد. عند توفير `campaign_id`، تتم إزالة الأسئلة الشائعة المحذوفة أيضًا من قائمة الأسئلة الشائعة الخاصة بتلك الحملة.

**حقول الطلب**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `faq_ids` | نعم | مصفوفة غير فارغة من معرفات الأسئلة الشائعة المراد حذفها (بحد أقصى 500). |
| `campaign_id` | لا | قم أيضًا بإزالة الأسئلة الشائعة المحذوفة من قائمة الأسئلة الشائعة الخاصة بهذه الحملة. |

**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
}
```

---

## الأسئلة الشائعة حول الاستيراد

`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`

يمسح مهمة إلغاء التكرار المنتهية حتى تتوقف عن الظهور كنتيجة نشطة. عملية غير مؤثرة (Idempotent) — آمنة للاستدعاء حتى لو لم يكن هناك شيء لتجاهله. يُرجع `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`

يقرأ مستنداً واحداً أو أكثر موجوداً بالفعل في مساحة تخزين الملفات الخاصة بحسابك، ويجعل الذكاء الاصطناعي يصيغ أسئلة شائعة من محتواها، مع مطابقة المسودات مقابل مكتبتك الحالية بحيث يعيد استخدام الإدخالات أو تحديثها بدلاً من إنشاء نسخ مكررة. **لا** تتم كتابة النتائج على الفور، بل يتم تخزينها كمجموعة تغييرات معلقة في الحملة لتراجعها، ثم يتم تطبيقها (أو تجاهلها) باستخدام [تطبيق تغييرات الأسئلة الشائعة المراجعة](#apply-reviewed-faq-changes) أدناه. يكلف هذا رصيداً، نظراً لأنه يمثل عملية توليد بواسطة الذكاء الاصطناعي لنص المستند.

لا يحمل نقطة النهاية هذه الملف: يجب أن تشير `storagePath` إلى ملف موجود بالفعل ضمن مجلد التحميلات الخاص بك (`users/{your user id}/uploads/`)، وهو نفس الاصطلاح المستخدم في [استيراد مستند تم تحميله](knowledge-base.md#import-an-uploaded-document) في واجهة برمجة تطبيقات قاعدة المعرفة.

**حقول الطلب**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `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` بتقسيم ذلك إلى أسئلة شائعة طابقت إدخالاً موجوداً دون تغيير، وأخرى يقترح الذكاء الاصطناعي تعديلها، وأخرى جديدة تماماً. يتم حذف الملفات التي تم تحميلها من التخزين بمجرد انتهاء المعالجة، سواء نجحت أم لا.

### تطبيق تغييرات الأسئلة الشائعة المراجعة

`POST /faqs/apply-optimization`

تطبيق (أو تجاهل) مجموعة معلقة من تغييرات الأسئلة الشائعة المقترحة بواسطة الذكاء الاصطناعي — وهي النوع الذي يتم إنتاجه بواسطة [إنشاء أسئلة شائعة من المستندات](#generate-faqs-from-uploaded-documents) أعلاه، أو بواسطة مراجعة تحسين الأسئلة الشائعة في لوحة التحكم. أنت تختار بالضبط التغييرات المقترحة التي تريد قبولها؛ أي شيء لا تذكره يظل دون تغيير (لا يتم التعامل مع التغيير المحذوف أبداً على أنه رفض يؤدي إلى حذف شيء ما).

**حقول الطلب**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `campaignId` | واحد من هذين | الحملة التي يتم تطبيق تغييرات الأسئلة الشائعة المعلقة الخاصة بها. |
| `agentId` | واحد من هذين | وكيل الذكاء الاصطناعي الذي يتم تطبيق تغييرات الأسئلة الشائعة المعلقة الخاصة به، على حساب أصلي للوكيل. قدم واحداً فقط من `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 عادةً.

### حل مهمة باستخدام أسئلة شائعة موجودة

`POST /faqs/resolve-task`

يحل مهمة فجوة معرفية عن طريق ربطها بأسئلة شائعة لديك بالفعل (بدلاً من كتابة أسئلة جديدة)، ويرسل إجابة تلك الأسئلة الشائعة إلى جهة الاتصال التي أثارت الفجوة، ويضع علامة "مكتملة" على المهمة. استخدم هذا بعد أن يُظهر [البحث عن أسئلة شائعة مشابهة لمهمة](#find-faqs-similar-to-a-task) أسئلة شائعة موجودة تغطي السؤال بالفعل.

مثل نقطة النهاية أعلاه، تستجيب هذه دائمًا بـ `200` — تحقق من `success` في النص الأساسي.

**حقول الطلب**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `taskId` | نعم | مهمة `faq_update` المراد حلها. |
| `faqId` | نعم | الأسئلة الشائعة الموجودة لربطها وإرسالها كإجابة. |

**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` (كان الذكاء الاصطناعي في منتصف الرد على جهة الاتصال تلك، لذا سيتم إرساله لاحقًا)، `skipped_no_contact` (المهمة ليس لها جهة اتصال مرتبطة)، أو `skipped_no_campaign` (لا توجد حملة للإرسال من خلالها).

---

## أخطاء واجهة برمجة تطبيقات الأسئلة الشائعة

تُرجع نقاط نهاية الأسئلة الشائعة غلاف الخطأ القياسي:

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

| الحالة | متى يحدث ذلك في نقطة نهاية الأسئلة الشائعة |
|---|---|
| `400` | حقل مطلوب مفقود أو غير صالح (على سبيل المثال، `question` فارغ، أو `campaign_id` مفقود، أو أكثر من 500 عنصر في طلب مجمع). |
| `404` | لم يتم العثور على الأسئلة الشائعة أو الحملة — إما أنها غير موجودة أو تنتمي إلى حساب آخر. |
| `409` | تم استدعاء `POST /faqs/dedupe` بينما وظيفة إلغاء التكرار لا تزال `queued`/`processing`، أو تم استدعاء `POST /faqs/dedupe/dismiss` بينما لم تنتهِ الوظيفة بعد. |

الرموز المشتركة التي يمكن أن تُرجعها كل نقطة نهاية — `401`، و `403` (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، و `429` (حد المعدل)، و `500` — مدرجة مع إرشادات إعادة المحاولة في [الأخطاء والترقيم](errors-and-pagination.md).

`POST /faqs/similar-for-task` و `POST /faqs/resolve-task` هما الاستثناءان الوحيدان في هذه الصفحة: فهما يستجيبان بـ `200` حتى في حالة الفشل المتوقع (مهمة غير معروفة، نوع مهمة خاطئ) ويضعان الحالة الحقيقية في `error_code` ضمن النص الأساسي بدلاً من ذلك — راجع كل نقطة نهاية أعلاه.

---

## ذات صلة

- [واجهة برمجة تطبيقات الحملات](campaigns.md) — الحملات التي ترتبط بها أسئلتك الشائعة.
- [واجهة برمجة تطبيقات قاعدة المعرفة](knowledge-base.md) — استيراد مواقع الويب والمستندات إلى أسئلة شائعة تلقائيًا، وتجميع الأسئلة الشائعة في مجموعات معرفية قابلة لإعادة الاستخدام.
- [الوصول إلى واجهة برمجة التطبيقات](../integrations/api-access.md) — إنشاء مفتاح واجهة برمجة التطبيقات الخاص بك.
- [المصادقة](authentication.md) — جميع الطرق لتمرير مفتاحك.