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

الصفقة هي فرصة مبيعات واحدة على لوحة خط مبيعاتك — تتكون من عنوان، وقيمة، والمرحلة التي تقع فيها، واختياريًا جهة الاتصال التي تنتمي إليها وعضو الفريق المخصص لها. يغطي هذا الدليل قراءة وإدارة الصفقات عبر واجهة برمجة التطبيقات.

عنوان URL الأساسي — https://api.dmchamp.com/v1
المصادقة — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع المصادقة)
الأخطاء والترقيم — راجع الأخطاء والترقيم

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

كائن الصفقة

{
  "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

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

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

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)

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

الحصول على صفقة

GET /deals/{dealId}

curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

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

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

الصفقة التي لا وجود لها، أو التي تنتمي إلى حساب آخر، تُرجع 404.

إنشاء صفقة

POST /deals — title و stage مطلوبان؛ يجب أن يكون stage أحد معرفات مراحل خط المبيعات الخاص بك.

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)

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

تحديث صفقة

PUT /deals/{dealId} — أرسل فقط الحقول التي تريد تغييرها (title، description، value، stage، status، priority، contact_id، …). يجب أن يكون value رقمًا.

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 يضع البطاقة في أعلى العمود.

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} — يزيل الصفقة. لا يمكن التراجع عن هذا الإجراء.

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

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

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

خط أنابيب المبيعات — كيفية عمل المراحل، وعلامات المراحل، ولوحة التحكم.
واجهة برمجة تطبيقات المهام — يمكن ربط المهام بصفقة باستخدام deal_id.
الأتمتة — تقرأ خطوات البحث عن صفقات و البحث عن صفقة نفس البيانات داخل سير العمل.

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

كائن الصفقة #

سرد الصفقات #

الحصول على صفقة #

إنشاء صفقة #

تحديث صفقة #

نقل صفقة إلى مرحلة أخرى #

حذف صفقة #

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