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

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

عنوان URL الأساسي — https://api.youraiconnector.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",
  "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 (راجع خطوط الأنابيب أدناه). معرفات المراحل فريدة عبر جميع خطوط الأنابيب الخاصة بك، لذا فإن pipeline_id مشتق من المرحلة وهو للقراءة فقط: default هو خط الأنابيب الرئيسي الخاص بك، ويكون null عندما لا تعود المرحلة موجودة. الطوابع الزمنية بتنسيق ISO 8601.

تخزن الصفقة الحقول الموضحة أعلاه فقط. عند إنشاء أو تحديث صفقة، يتم رفض أي حقل آخر مع 400 يحدد اسمه، لذا لن يتم فقدان أي شيء ترسله بصمت. احتفظ بالبيانات الإضافية في الحقول المخصصة لجهة الاتصال المرتبطة.

سرد الصفقات

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

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

cURL

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

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

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)

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

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

GET /deals/{dealId}

curl "https://api.youraiconnector.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.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)

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

تحديث صفقة

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

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

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

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

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

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

يحتوي كل حساب على خط أنابيب رئيسي (id: "default")؛ يمكنك إضافة ما يصل إلى تسعة خطوط أخرى، لكل منها مراحله الخاصة. يجب أن تكون معرفات المراحل وعلامات التشغيل فريدة عبر جميع خطوط الأنابيب في الحساب، ويمكن لكل خط أنابيب تحديد مرحلة واحدة كـ won ومرحلة واحدة كـ lost.

سرد خطوط الأنابيب

GET /pipelines — كل خط أنابيب، يبدأ بالرئيسي، مع ترتيب مراحله حسب الموقع.

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

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

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

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).

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

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

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

كائن الصفقة #

سرد الصفقات #

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

إنشاء صفقة #

تحديث صفقة #

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

حذف صفقة #

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

سرد خطوط الأنابيب #

إنشاء خط أنابيب #

تحديث خط أنابيب #

حذف خط أنابيب #

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