العملاء المحتملون عبر API

يمنح هذا القسم وصولا برمجيا إلى عملائك المحتملين أنت في CRM: يستطيع موقع أو نموذج خارجي إرسال الطلبات مباشرة إلى لوحة التحكم، ويستطيع نظامك قراءتها ونقلها بين الحالات.

العنوان الأساسي: https://developers.grem.capital/api/v1.

القائمة

GET /leads?status=new&type=buy&priority=hot&page=1&limit=20
Authorization: Bearer gsk_live_...

المرشحات: status، type، priority، source، role، archived، pool، from، to، page، limit، sort. العملاء المؤرشفون ليسوا في القائمة العادية: أضف archived=true. pool=true (لمفاتيح الوكالة فقط): العملاء في المجمع المشترك للوكالة؛ ويتجاهله المفتاح الشخصي.

limit (من 1 إلى 50، الافتراضي 20) وpage (من 1) خارج المدى يُردّان إليه ولا يُرفضان. أما القيم غير الصالحة الأخرى لمعامل معروف (قيمة تعداد غير معروفة، أو page غير صحيح، أو تاريخ غير صالح في from أو to) فتُرفض بـ 400 validation مع اسم الحقل.

عميل محتمل واحد

GET /leads/{id}?expand=history,documents

يضيف expand سجل الحالات والإجراءات (history) والمستندات المرفقة (documents).

شكل العميل المحتمل

• id، status، type، priority، source، tags، isArchived؛ type إحدى القيم buy، rent، viewing، sell، contract، transfer، user
• createdAt، updatedAt، lastActivityAt
• customer: الاسم، والبلد، وتطبيق المراسلة، وكتلة contact (phone، email، messengerHandle، profileUrl)
• budget: { value, currency }
• intent: المدينة، والأحياء، ونوع الصفقة، ونية العميل
• comments: تعليق العميل وتعليقك، كل على حدة
• object: العقار الذي يخصه الطلب
• agency: في عملاء الوكالة فقط، معرّف الوكالة وهل العميل في المجمع المشترك

لا تُعاد أبدا جهات اتصال الوسطاء الآخرين ولا التقييمات الداخلية ولا العلامات الخدمية.

إرسال طلب

curl -X POST https://developers.grem.capital/api/v1/leads \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-07-0001" \
  -d '{
    "customer": {
      "name": "Olena Kovalchuk",
      "country": "UA",
      "contact": { "phone": "+380971234567", "email": "[email protected]" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "تبحث عن شقة من غرفتين قرب المترو",
    "priority": "warm",
    "consent": true
  }'

الإلزامي: customer.name وطريقة واحدة على الأقل للتواصل مع العميل في customer.contact. type: buy (افتراضي) أو rent. priority: hot أو warm أو cold. أضف objectId إذا كان الطلب يخص عقارا محددا، وحتى عشرة tags خاصة بك.

pool: true يرسل الطلب إلى مجمع التوزيع المشترك بدلا من CRM الخاص بك. افتراضيا يصل العميل إليك.

كل عميل محتمل يُنشأ عبر API يحمل في لوحة التحكم المصدر «API» لتميزه.

تعديل عميل محتمل

PATCH /leads/{id}
{ "status": "in progress", "priority": "hot", "tags": ["mortgage"], "brokerComments": "..." }

يمكنك تغيير الحالة والأولوية والوسوم وتعليقك الخاص. يكفي حقل واحد. الحالات: new، in progress، processing، agreement، closed، not target، failed. تنطبق قواعد لوحة التحكم: العميل المرتبط بعقار يُغلق عبر الإنهاء في لوحة التحكم (code: finalize)، والعميل الذي ينتظر العمولة يحتفظ بحالته (fee_pending)، والصفقة المغلقة بموجب عقد لا تتغير إلا في لوحة التحكم (closed): 422 مع السبب في code. أسباب أخرى: sender (مررت العميل لغيرك، ويديره المستلم)، وmodule (عميل Swipe Match، وحالته تتبع الوحدة)، وagreement، وnetwork_readonly، وforbidden.

إزالة عميل محتمل

DELETE /leads/{id}

يُؤرشف العميل ولا يُحذف: يخرج من القائمة العادية لكنه يبقى متاحا مع ?archived=true. لا يُؤرشف العميل الذي له عقد سارٍ أو اتفاق إنهاء، ولا العميل المغلق المرتبط بعقار دون إنهاء، ولا العميل الذي ينتظر العمولة: 422 مع code بقيمة contract_active أو agreement أو finalize أو fee_pending.

عقارات لعميل محتمل

GET /leads/{id}/matches?page=1&limit=20

يعيد العقارات التي تناسب طلب العميل: النوع والمدينة والميزانية تؤخذ من العميل نفسه أو من العقار المرتبط. مجاني.

مجمع الوكالة

لمفاتيح الوكالة إجراءان على المجمع:

POST /leads/{id}/claim               أخذ عميل من المجمع
POST /leads/{id}/claim?assignTo=...  إسناده إلى عضو في الفريق
POST /leads/{id}/return-to-pool      إعادة عميل إلى المجمع

• الأخذ: افتراضيا يذهب العميل إلى مالك الوكالة؛ ويمكن للمالك أو المدير تمرير assignTo (معرّف العضو).
• الإعادة إلى المجمع: من المدير فما فوق، أو الوكيل المسند إليه العميل. جسم اختياري: {"reason": "..."}. العميل الذي أرشفته قواعد المجمع يعطي 422 مع code: pool_archived: استعده أولا من لوحة التحكم.
• المفتاح الشخصي أو الدور غير الكافي: 403 مع title: forbidden؛ وأخذ عميل لم يعد في المجمع: 404.
• كلا الإجراءين يرسل حدث lead.updated.

متابعة التغييرات

بدلا من الاستعلام عن القائمة، اشترك في lead.created وlead.updated: انظر Webhooks. لا يحمل الحدث بيانات شخصية: يذكر فقط أي عميل تغير، وتقرأ البطاقة بطلب منفصل.

مقالات ذات صلة

• العقارات: الكتالوج الذي يشير إليه العملاء.
• Swipe Match: عملاء الوحدة للوسطاء الشركاء.
• Webhooks: أحداث العملاء الجدد والمعدلين.
• الأخطاء: فهم حالات الرفض.