العملاء المحتملون عبر 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.

عميل واحد

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

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

بنية العميل المحتمل

• id وstatus وtype وpriority وsource وtags وisArchived
• createdAt وupdatedAt وlastActivityAt
• customer - الاسم والبلد وتطبيق المراسلة وكتلة contact (phone وemail وmessengerHandle وprofileUrl)
• budget - { value, currency }
• intent - المدينة والأحياء ونوع الصفقة وما يبحث عنه العميل
• comments - ملاحظة العميل وملاحظتك أنت، كل على حدة
• object - الإعلان الذي يتعلق به الطلب
• deadline وreminder
• 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": "olena@example.com" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Looking for a two-room flat near the metro",
    "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.

إزاحة عميل جانبا

DELETE /leads/{id}

وهذا يؤرشف ولا يحذف: يخرج العميل من القائمة العادية لكنه يبقى متاحا عبر ?archived=true.

عقارات مناسبة للعميل

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

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

مجمع الوكالة

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

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

ويتطلب كلاهما دورا في الوكالة يسمح بتوزيع العملاء. أما المفتاح الشخصي فيرفض، وأخذ عميل أخذه غيرك يعيد 409.

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

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

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

• الكائنات (قراءة) - كتالوج الإعلانات التي يشير إليها العملاء.
• Webhooks - أحداث العملاء الجدد والمتغيرين.
• الأخطاء - كيف تقرأ الرفض.