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

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

- **عنوان URL الأساسي** — `https://api.dmchamp.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",
  "stage": "stage-2",
  "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 /users/me/pipeline-settings`). الطوابع الزمنية بتنسيق ISO 8601.

---

## سرد الصفقات

`GET /deals` — تُرجع الصفقات الموجودة في حسابك، بدءاً من الأحدث.

**معلمات الاستعلام** (جميعها اختيارية): `stage` (معرف المرحلة)، `contact_id`، `limit` (القيمة الافتراضية 50، الحد الأقصى 200)، `cursor` (من `next_cursor` للصفحة السابقة).

**cURL**

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

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.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.dmchamp.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.dmchamp.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.dmchamp.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`، `value`، `stage`، `status`، `priority`، `contact_id`، ...). يجب أن يكون `value` رقمًا.

```bash
curl -X PUT "https://api.dmchamp.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.dmchamp.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.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

**الاستجابة** (`200`): `{ "success": true }`

---

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

- [خط أنابيب المبيعات](../deals/sales-pipeline.md) — كيفية عمل المراحل، وعلامات المراحل، ولوحة التحكم.
- [واجهة برمجة تطبيقات المهام](tasks.md) — يمكن ربط المهام بصفقة باستخدام `deal_id`.
- [الأتمتة](../automations/automations.md) — تقرأ خطوات **البحث عن صفقات** و **البحث عن صفقة** نفس البيانات داخل سير العمل.