# API משימות

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

- **כתובת בסיס (Base URL)** — `https://api.youraiconnector.com/v1`
- **אימות (Authentication)** — מפתח ה-API שלך (ראו [אימות](authentication.md))
- **שגיאות ועימוד (Errors & paging)** — ראו [שגיאות ועימוד](errors-and-pagination.md)

כל הדוגמאות להלן מציגות את טופס השאילתה `?apiKey=` ב-cURL ואת הכותרת `X-API-Key` ב-JavaScript וב-Python — שתי הדרכים עובדות בכל נקודת קצה (endpoint).

---

## אובייקט המשימה

```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`** — המזהה (id) של שלב בלוח המשימות שלך (ראו [רשימת שלבי משימות](#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` הוא מזהה המשתמש (user id) של חבר צוות.
:::


> **הגדרת `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`. השאלה הנפוצה נוצרת בכל מקרה.

עיין ב-[API של שאלות נפוצות](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"})
```

---

## צעדים הבאים

- [API אנשי קשר](contacts.md) — קישור משימות לאיש הקשר הנכון
- [API Webhooks](webhooks.md) — קבלת התראות על `Task Created`, `Task Updated`, ו-`Task Completed`
- [תיעוד API](reference.md) — סייר נקודות הקצה האינטראקטיבי המלא