يبحث Swipe Match عن وسيط للعميل ويعرض العميل المحتمل على الوسطاء بالتناوب. عبر API يرى الوسيط الشريك (أو الوكالة) العملاء المعروضين عليه والمسندين إليه، ويبلغ عن خطواته مع العميل. القراءة تتطلب النطاق leads:read، والأحداث تتطلب leads:write. لا تُخصم.
العملاء المحتملون
curl "https://developers.grem.capital/api/v1/match/leads?view=active&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /match/leads:
| المعامل | الوصف |
|---|---|
view | active (افتراضي): العملاء المسندون إليك؛ inbox: العروض المفتوحة لك. مفتاح الوكالة يرى عملاء وعروض وكلاء الوكالة |
stage | تصفية حسب المرحلة |
page، limit | الصفحة؛ limit حتى 50، والافتراضي 20؛ وlimit أو page أقل من 1، أو limit أكبر من 50، أو page أكبر من 1000 يعطي 400 |
GET /match/leads/{id}: عميل واحد، وGET /match/leads/{id}/events: سجله (أحداثك والعروض؛ دون أحداث مالية أو خدمية ودون تقييمات العميل). العميل الذي لا يخصك: 404.
إلى أن يُفتح Swipe Match للوصول عبر API في حسابك، تجيب هذه الطلبات بـ 409 مع code: not_available.
حقول العميل المحتمل:
| الحقل | الوصف |
|---|---|
id، stage | المعرّف والمرحلة |
clientType | buyer أو seller |
country، objectId، objectIds | البلد والعقارات التي يخصها الطلب |
budget | min، max، currency |
answers | إجابات العميل: budget، timeline، payment |
qualScore، qualBand | تقييم جودة العميل |
clientInitial | الحرف الأول من اسم العميل |
offer | عرضك المفتوح: id، wave، offeredAt، deadline |
contactDeadline، meetingDeadline | موعد التواصل والاجتماع |
deal، reservation، dealObjects | بيانات الصفقة والحجز |
client | name وphone للعميل: فقط بعد إسناد العميل إليك وكشف جهة الاتصال |
brokerId | الوسيط الذي يُعرض منظوره |
fee | رسوم المنصة على هذا العميل المحتمل بالنسبة لك: none أو percent (هذه النسبة من العمولة التي تتلقاها، في percent) أو contract (حسب الاتفاق)؛ دون مبالغ أبدا |
المراحل (stage): new، offered، intro، match، contact، meeting_scheduled، meeting_held، contract، deal، closed، lost.
خطواتك مع العميل المحتمل
POST /match/leads/{id}/events: فقط لعميل مسند إليك. تتحقق الوحدة من أن الخطوة مسموحة في المرحلة الحالية.
event | الحقول | المعنى |
|---|---|---|
FIRST_CONTACT | channel: phone (افتراضي) أو messenger | تواصلت مع العميل |
RESERVATION | amount، currency (3 أحرف)، date؛ documentFileId اختياري | دفع العميل حجزا |
STAGE_ROLLBACK | reasonCode: client_withdrew، seller_withdrew، financing_failed، documents، other؛ text حتى 500 | إعادة العميل مرحلة إلى الوراء |
LEAD_LOST | reasonCode: client_refused، client_unreachable، bought_elsewhere، not_target، other؛ text. وأي سبب آخر يعطي 400 | فُقد العميل |
DEAL_CLOSED | objectId، amount، currency، date، documentFileId؛ commissionReceived، commissionCurrency اختياريان | أُغلقت الصفقة |
documentFileId: معرّف ملف مرفوع عبر POST /uploads (الملفات). وreasonCode خارج قائمته يعطي 400؛ ومع LEAD_LOST والسبب other يكون text إلزاميا (ودونه 400)؛ أما مع STAGE_ROLLBACK فلا يُحفظ text إلا مع other.
curl -X POST https://developers.grem.capital/api/v1/match/leads/LEAD_ID/events \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fc-LEAD_ID-1" \
-d '{"event":"FIRST_CONTACT","channel":"phone"}'
الرد: lead العميل بعد الانتقال، وreplay: true إذا كانت إعادة بالمفتاح Idempotency-Key نفسه. خطوات العميل لا تُرسل عبر API. يتكون Idempotency-Key هنا من 8 إلى 128 حرفا: حروف وأرقام و_ . : -؛ وأي صيغة أخرى تعطي 400 validation.
تصل حالات الرفض بـ 409 مع title: business_rule والسبب في code:
| السبب | code |
|---|---|
| الخطوة غير متاحة في المرحلة الحالية | invalid_transition |
| حدث خاص بالعميل لا يرسله الوسطاء | client_event_rejected |
| الوحدة غير مفتوحة لـ API بعد | not_available |
الأحداث
match.lead.offered، match.lead.offer_closed، match.lead.matched، match.lead.updated، match.lead.unassigned: انظر Webhooks. لا تحتوي الأحداث أبدا على جهات اتصال العميل.
مقالات ذات صلة
- العملاء المحتملون: CRM الخاص بك.
- Webhooks