واجهة المسارات والفرص

تقع كل فرصة دائمًا في مرحلة من مسار، وتخص جهة اتصال. ولتفتح فرصة عبر الواجهة اقرأ المسارات لتعرف معرف المرحلة، ثم أنشئ الفرصة. القواعد المشتركة للمفاتيح وJSON والحدود في واجهة REST، وطريقة عمل الفرص في التطبيق في الفرص والمسارات.

عرض المسارات والمراحل

GET /pipelines

curl https://rutbacrm.com/api/v1/pipelines \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": "PIPELINE_ID",
      "name": "Sales",
      "stages": [
        {"id": "STAGE_ID", "name": "New", "position": 1},
        {"id": "STAGE_ID_2", "name": "Qualified", "position": 2}
      ]
    }
  ]
}

تُعرض المسارات والمراحل النشطة فقط، الأقدم أولًا: حتى 20 مسارًا وحتى 12 مرحلة في كل منها. ومعرفات المراحل لا تتغير إن أُعيدت تسميتها، فيمكنك حفظها في إعدادات نظامك.

فتح فرصة

POST /deals

يحتاج مفتاحًا بصلاحية قراءة وكتابة ومنشئه عضو أو مسؤول أو مالك.

تُتجاهل الحقول الأخرى. والفرص المنشأة عبر الواجهة بلا مسؤول وبلا تاريخ إغلاق متوقع، فاضبطهما من التطبيق.

curl -X POST https://rutbacrm.com/api/v1/deals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": "CONTACT_ID", "stage_id": "STAGE_ID", "title": "Espresso machine for the new branch", "amount": "1250.50", "currency": "SAR", "next_step": "Send the quote", "next_step_on": "2026-11-12"}'

الفرصة الجديدة ترد 201:

{
  "data": {
    "id": "DEAL_ID"
  }
}

تُفتح الفرصة بحالة مفتوحة، وتدخل المرحلة المختارة الآن، ويظهر منشئ المفتاح منشئًا لها في سجلها.

الردود

المبلغ المرسل رقمًا، مثل 1250.5، يُرفض. أرسله دائمًا نصًا.

معلومات مفيدة

• كل استدعاء ينشئ فرصة جديدة. فإن انتهت مهلة الطلب فراجع فرص الجهة في التطبيق قبل إعادة المحاولة، وإلا فقد تفتح الفرصة نفسها مرتين.
• لا تُفتح فرصة جديدة لجهة مؤرشفة أو مدمجة أو ممحوة.
• لا يمكن نقل الفرص أو كسبها أو خسارتها أو تعديلها عبر الواجهة. وحين تُكسب فرصة في التطبيق يخبر الحدث كسب فرصة في الإشعارات الصادرة نظامك بذلك.