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

الصفقة هي فرصة مبيعات واحدة على لوحة [خط مبيعاتك](../deals/sales-pipeline.md) — تتكون من عنوان، وقيمة، والمرحلة التي تقع فيها، واختياريًا جهة الاتصال التي تنتمي إليها وعضو الفريق المخصص لها. يغطي هذا الدليل قراءة وإدارة الصفقات عبر واجهة برمجة التطبيقات.

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

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

---

## كائن الصفقة

```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` هو معرف إحدى مراحل خط الأنابيب الخاصة بك — يمكنك قراءتها باستخدام `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` أحد معرفات مراحل خط المبيعات الخاص بك.

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

---

## خطوط الأنابيب

يحتوي كل حساب على خط أنابيب رئيسي (`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) — كيفية عمل المراحل، وعلامات المراحل، وخطوط الأنابيب المتعددة، ولوحة التحكم.
- [واجهة برمجة تطبيقات المهام](tasks.md) — يمكن ربط المهام بصفقة باستخدام `deal_id`.
- [الأتمتة](../automations/automations.md) — تقرأ خطوات **البحث عن صفقات** و **البحث عن صفقة** نفس البيانات داخل سير العمل.