# واجهة برمجة تطبيقات المهام (Tasks API)

المهام هي بنود العمل والمتابعات المرتبطة بحسابك — والتي يمكن ربطها اختيارياً بجهة اتصال، أو صفقة، أو حملة. تنتقل هذه المهام عبر **مراحل** لوحة المهام الخاصة بك (أعمدة كانبان) ولها **نوع** و**أولوية**. يغطي هذا الدليل كيفية إدارتها عبر واجهة برمجة التطبيقات.

- **عنوان URL الأساسي** — `https://api.youraiconnector.com/v1`
- **المصادقة** — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع [المصادقة](authentication.md))
- **الأخطاء والترقيم** — راجع [الأخطاء والترقيم](errors-and-pagination.md)

توضح جميع الأمثلة أدناه نموذج الاستعلام `?apiKey=` في cURL ورأس `X-API-Key` في JavaScript وPython — كلاهما يعمل على كل نقطة نهاية.

---

## كائن المهمة

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`، `faq_update`، أو أنواع المهام التي قمت بتكوينها (راجع [قائمة أنواع المهام](#list-task-types)).
- **`priority`** — `none`، أو `low`، أو `normal`، أو `high`، أو `urgent`.
- **`stage`** — معرف المرحلة في لوحة المهام الخاصة بك (راجع [قائمة مراحل المهام](#list-task-stages)). عند حذفه أثناء الإنشاء، يتم وضع المهمة في مرحلتك الأولى.
- **`remind_before_minutes`** — عدد الدقائق قبل `due_date` لإرسال تذكير. `0` تعني في وقت الاستحقاق؛ احذفه أو أرسل `null` لعدم وجود تذكير. يجب أن يكون رقماً صحيحاً من `0` إلى `1440` (يوم واحد) — سيتم رفض أي قيمة أكبر. يحتاج التذكير إلى `due_date` ليتم إطلاقه، وتؤدي إعادة جدولة المهمة إلى نقل التذكير معها.

---

## إنشاء مهمة

`POST /tasks` — الحقل `title` فقط هو المطلوب.

::: note
**ملاحظة:** يقبل `due_date` طابعاً زمنياً بتنسيق ISO 8601، بما في ذلك وقت اليوم. قم بإقرانه بـ `remind_before_minutes` ليتم تسليم التذكير وفقاً لإعدادات إشعارات **المهام** الخاصة بك. تربط `contact_id` و `deal_id` و `campaign_id` المهمة بتلك السجلات. `assigned_to` هو معرف المستخدم الخاص بعضو الفريق.
:::


> **ضبط `assigned_to` بشكل صحيح.** يجب أن يكون هذا هو معرف المستخدم (user id) الخاص بمالك الحساب أو أحد أعضاء الفريق النشطين في نفس الحساب. لا تتحقق نقطة النهاية هذه حاليًا من ذلك، لذا يتم قبول المعرف الذي لا ينتمي لأحد وتخزينه تمامًا كما أرسلته — وستظل تحصل على `201`. انسخ المعرف بدلاً من إعادة كتابته: فهذه المعرفات تخلط بين `l` و `L` وبين الحرف `O` والرقم `0`، ويكفي حرف واحد خاطئ لإفساد الأمر. للتحقق مما أرسلته فعليًا، افتح المهمة في لوحة التحكم: يعود حقل **المسؤول (Assignee)** في سجل المهمة إلى عرض المعرف الخام عندما لا يطابق أي شخص، ويظهر منتقي المسؤول في **تحرير المهمة (Edit task)** الحالة **غير معين (Unassigned)**.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**الاستجابة** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## سرد المهام

`GET /tasks` — تُرجع المهام الخاصة بحسابك، مع فلاتر اختيارية.

**معلمات الاستعلام** (جميعها اختيارية): `stage`، `priority`، `contact_id`، `deal_id`، `assigned_to`، `due_before`، `due_after` (طوابع زمنية بتنسيق ISO).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**الاستجابة** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## البحث عن المهام

`POST /tasks/search` — مطابقة النص الكامل في العنوان والوصف، مع نفس عوامل التصفية الاختيارية المتاحة في القائمة.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

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

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## الحصول على مهمة

`GET /tasks/{taskId}`

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

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

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

المهمة غير الموجودة في حسابك تُرجع `404`.

---

## تحديث مهمة

`PUT /tasks/{taskId}` — أرسل فقط الحقول التي تريد تغييرها (`title`، `description`، `type`، `priority`، `stage`، `due_date`، `remind_before_minutes`، `contact_id`، `deal_id`، `assigned_to`، `tags`، `notes`).

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## إكمال مهمة

`POST /tasks/{taskId}/complete` — تنقل المهمة إلى مرحلة المهام المكتملة في لوحتك. حقل اختياري `notes` يسجل ملاحظة ختامية.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## النقل وإعادة الترتيب (كانبان)

**نقل مهمة إلى مرحلة أخرى** — `POST /tasks/{taskId}/move` مع `new_stage_id` (المرحلة الوجهة) و `new_position` (الموضع المعتمد على الصفر داخل تلك المرحلة؛ مطلوب، يجب أن يكون عدداً صحيحاً غير سالب):

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**إعادة ترتيب المهام داخل مرحلة** — `POST /tasks/reorder` مع `stage_id` ومعرفات المهام بترتيبها الجديد:

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## مهام جهة اتصال

`GET /tasks/contact/{contactId}` — كل مهمة مرتبطة بجهة اتصال واحدة.

```bash
curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"
```

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

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## إعداد لوحة المهام

### سرد مراحل المهام

`GET /tasks/stages` — أعمدة لوحتك، بالترتيب. استخدم `id` المرحلة كحقل `stage` عند إنشاء المهام أو نقلها.

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

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### تحديث مراحل المهمة

`PUT /tasks/stages` — استبدل إعدادات مراحل لوحتك. أرسل مصفوفة `stages` المرتبة بالكامل.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### سرد أنواع المهام

`GET /tasks/types` — أنواع المهام المكونة في حسابك (تُستخدم كحقل `type`).

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

---

## الموافقة على اقتراح الأسئلة الشائعة

عندما يقترح روبوت الذكاء الاصطناعي سؤالاً شائعاً (FAQ) جديداً، فإنه ينشئ مهمة من النوع `faq_update`. تقوم `POST /tasks/{taskId}/approve-faq` بتحويل هذا الاقتراح إلى سؤال شائع حقيقي في قاعدة معارف وكيل الذكاء الاصطناعي الذي طرحه وتكمل المهمة. يمكنك تجاوز السؤال/الإجابة في النص الأساسي.

أضف `"send_follow_up": true` لجعل الذكاء الاصطناعي يرسل الإجابة أيضاً إلى جهة الاتصال المرتبطة بالمهمة على الفور، كرسالة طبيعية في تلك الدردشة (وهو نفس ما يفعله مفتاح التبديل **إرسال الإجابة إلى جهة الاتصال الآن** في التطبيق). يتم إرسال الرد من خلال وكيل الذكاء الاصطناعي الذي يتعامل مع جهة الاتصال تلك.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status` يخبرك بما حدث للرسالة: `not_requested` (العلامة غير محددة)، `published` (تم الإرسال)، `queued` (كان الروبوت في منتصف الرد على جهة الاتصال تلك، وسيتم إرسال الإجابة بمجرد انتهائه)، `skipped_no_contact` (المهمة ليس لديها جهة اتصال مرتبطة)، `skipped_no_campaign` (لا يمكن لأي وكيل أو حملة الرد على جهة الاتصال تلك) أو `skipped_error`. يتم إنشاء السؤال الشائع (FAQ) في كل حالة.

راجع [واجهة برمجة تطبيقات الأسئلة الشائعة](faqs.md) لإدارة الأسئلة الشائعة الناتجة.

---

## حذف مهمة

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## الخطوات التالية

- [واجهة برمجة تطبيقات جهات الاتصال](contacts.md) — ربط المهام بجهة الاتصال الصحيحة
- [واجهة برمجة تطبيقات خطافات الويب](webhooks.md) — تلقي إشعارات حول `Task Created` و `Task Updated` و `Task Completed`
- [مرجع واجهة برمجة التطبيقات](reference.md) — مستكشف نقاط النهاية التفاعلي الكامل