# API עסקאות

עסקה היא הזדמנות מכירה אחת בלוח ה-[Sales Pipeline](../deals/sales-pipeline.md) שלך — כותרת, ערך, השלב שבו היא נמצאת, ובאופן אופציונלי איש הקשר שאליו היא שייכת וחבר הצוות שאליו היא מוקצית. מדריך זה מכסה קריאה וניהול של עסקאות באמצעות ה-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": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}
```

`stage` הוא המזהה של אחד משלבי הצינור (pipeline) שלך — קרא אותם באמצעות `GET /pipelines` (ראה [צינורות](#pipelines) להלן). מזהי שלבים הם ייחודיים בכל הצינורות שלך, לכן `pipeline_id` נגזר מהשלב והוא לקריאה בלבד: `default` הוא הצינור הראשי שלך, והוא `null` כאשר השלב אינו קיים עוד. חותמות זמן הן בתקן ISO 8601.

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

---

## רשימת עסקאות

`GET /deals` — מחזיר את העסקאות בחשבון שלך, מהחדשה ביותר לישנה ביותר.

**פרמטרי שאילתה** (כולם אופציונליים): `stage` (מזהה שלב), `pipeline_id` (רק העסקאות בצינור זה), `contact_id`, `limit` (ברירת מחדל 50, מקסימום 200), `cursor` (מה-`next_cursor` של הדף הקודם).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]
```

**תגובה** (`200`)

```json
{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }
```

---

## קבלת עסקה

`GET /deals/{dealId}`

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

**תגובה** (`200`)

```json
{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }
```

עסקה שאינה קיימת, או ששייכת לחשבון אחר, תחזיר `404`.

---

## יצירת עסקה

`POST /deals` — `title` ו-`stage` הם שדות חובה; `stage` חייב להיות אחד ממזהי השלבים של ה-pipeline שלך.

```bash
curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'
```

**תגובה** (`201`)

```json
{ "success": true, "deal_id": "deal_abc123" }
```

---

## עדכון עסקה

`PUT /deals/{dealId}` — שלח רק את השדות שברצונך לשנות (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` חייב להיות מספר.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'
```

**תגובה** (`200`): `{ "success": true, "deal_id": "deal_abc123" }`

---

## העברת עסקה לשלב אחר

`POST /deals/{dealId}/move` — גוף `{ "new_stage_id": "stage-3", "new_position": 0 }`. מיקום `0` מציב את הכרטיס בראש העמודה.

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

**תגובה** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }`

---

## מחיקת עסקה

`DELETE /deals/{dealId}` — מסיר את העסקה. **לא ניתן לבטל פעולה זו.**

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

**תגובה** (`200`): `{ "success": true }`

---

## צינורות (Pipelines)

לכל חשבון יש צינור ראשי (`id: "default"`); ניתן להוסיף עד תשעה נוספים, כל אחד עם השלבים שלו. מזהי שלבים ותגיות הפעלה חייבים להיות ייחודיים בכל הצינורות בחשבון, וכל צינור יכול לסמן שלב אחד כ-`won` שלו ואחד כתוצאה `lost`.

### רשימת צינורות

`GET /pipelines` — כל צינור, הראשי ראשון, כל אחד עם השלבים שלו ממוינים לפי מיקום.

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

**תגובה** (`200`):

```json
{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}
```

### יצירת צינור

`POST /pipelines` — גוף `{ "id"?, "name", "stages"?, "settings"? }`. השאר את `id` ריק כדי ליצור אחד באופן אוטומטי. כל שלב מקבל את אותם שדות כמו בתיבת הדו-שיח שלבים: `id`, `name`, `color`, `position`, `trigger_tag` אופציונלי (נתיב תגית, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (שלב באותו צינור) ו-`outcome` (`"won"` או `"lost"`).

```bash
curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'
```

**תגובה** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. מזהה שלב או תגית הפעלה שכבר נמצאים בשימוש על ידי צינור אחר הם `400` המציינים את הצינור ההוא; מזהה שכבר קיים הוא `409`.

### עדכון צינור

`PUT /pipelines/{pipelineId}` — גוף `{ "name"?, "stages"?, "settings"? }`. `stages` מחליף את כל הרשימה, בדומה לתיבת הדו-שיח שלבים. השתמש ב-`default` עבור הצינור הראשי. לא ניתן לשנות את מזהה הצינור עצמו.

### מחיקת צינור

`DELETE /pipelines/{pipelineId}` — מסיר צינור נוסף (לא ניתן למחוק את הראשי). אם עדיין יש עסקאות בשלבים שלו, הקריאה תענה ב-`409` עם `deal_count`; הוסף את `?delete_deals=true` כדי למחוק את העסקאות הללו יחד עם הצינור. **לא ניתן לבטל פעולה זו.**

**תגובה** (`204`).

---

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

- [צינור מכירות](../deals/sales-pipeline.md) — כיצד פועלים שלבים, תגיות שלבים, מספר צינורות מכירה והלוח.
- [API של משימות](tasks.md) — ניתן לקשר משימות לעסקה באמצעות `deal_id`.
- [אוטומציות](../automations/automations.md) — השלבים **מצא עסקאות** ו-**מצא עסקה** קוראים את אותם הנתונים בתוך תהליך עבודה.