API vasitəsilə lidlər

Bu bölmə CRM-dəki öz lidlərinizə proqram vasitəsilə giriş verir: sayt və ya xarici forma müraciətləri birbaşa kabinetə göndərə bilər, sisteminiz isə onları oxuya və statuslar üzrə irəlilədə bilər.

Baza URL: https://developers.grem.capital/api/v1.

Siyahı

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

Filtrlər: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Arxivləşdirilmiş lidlər adi siyahıda yoxdur - archived=true əlavə edin. pool=true (yalnız agentlik açarları) - agentliyin ümumi siyahısındakı lidlər; şəxsi açar bu parametri nəzərə almır.

Diapazondan kənar limit (1-50, defolt 20) və page (1-dən) rədd edilmir, diapazona uyğunlaşdırılır. Məlum parametrin digər yanlış dəyərləri (naməlum enum dəyəri, tam ədəd olmayan page, from və ya to sahəsində yanlış tarix) sahənin adı göstərilməklə 400 validation ilə rədd edilir.

Bir lid

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

expand status və əməliyyatlar tarixçəsini (history) və əlavə edilmiş sənədləri (documents) əlavə edir.

Lidin strukturu

• id, status, type, priority, source, tags, isArchived; type - buy, rent, viewing, sell, contract, transfer və ya user
• createdAt, updatedAt, lastActivityAt
• customer - ad, ölkə, messencer və contact bloku (phone, email, messengerHandle, profileUrl)
• budget - { value, currency }
• intent - şəhər, rayonlar, əməliyyat növü və müştərinin niyyəti
• comments - müştərinin şərhi və sizin şərhiniz, ayrı-ayrılıqda
• object - müraciətin aid olduğu obyekt
• agency - yalnız agentlik lidlərində: agentliyin identifikatoru və lidin ümumi siyahıda olub-olmaması

Digər brokerlərin kontaktları, daxili qiymətləndirmələr və xidməti bayraqlar heç vaxt qaytarılmır.

Müraciətin göndərilməsi

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 2-room flat near the metro",
    "priority": "warm",
    "consent": true
  }'

Məcburidir: customer.name və customer.contact daxilində müştəri ilə əlaqənin ən azı bir üsulu. type - buy (defolt) və ya rent. priority - hot, warm və ya cold. Müraciət konkret obyekt haqqındadırsa, objectId əlavə edin, həmçinin on ədədə qədər öz tags etiketinizi.

pool: true müraciəti CRM-inizə deyil, ümumi paylama siyahısına göndərir. Defolt olaraq lid sizə gəlir.

API vasitəsilə yaradılmış hər lid kabinetdə «API» mənbəyi ilə işarələnir ki, onu fərqləndirə biləsiniz.

Lidin dəyişdirilməsi

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

Statusu, prioriteti, etiketləri və öz şərhinizi dəyişə bilərsiniz. Bir sahə kifayətdir. Statuslar: new, in progress, processing, agreement, closed, not target, failed. Kabinetin qaydaları tətbiq olunur: obyekti olan lid kabinetdə yekunlaşdırma ilə bağlanır (code: finalize), komissiya gözləyən lid statusunu saxlayır (fee_pending), müqavilə üzrə bağlanmış əməliyyat yalnız kabinetdə dəyişdirilir (closed) - səbəbi code sahəsində olan 422. Digər səbəblər: sender (lidi ötürmüsünüz - onunla alan şəxs işləyir), module (Swipe Match lidi, onun statusu modulu izləyir), agreement, network_readonly, forbidden.

Lidin silinməsi

DELETE /leads/{id}

Bu, lidi silmir, arxivləşdirir: o, adi siyahıdan çıxır, lakin ?archived=true ilə əlçatan qalır. Aktiv müqaviləsi və ya yekunlaşdırma razılaşması olan lid, yekunlaşdırılmamış obyekti olan bağlanmış lid və komissiya gözləyən lid arxivləşdirilmir: code contract_active, agreement, finalize və ya fee_pending ilə 422.

Lid üçün obyektlər

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

Müştərinin sorğusuna uyğun obyektləri qaytarır: növ, şəhər və büdcə lidin özündən və ya ona bağlı obyektdən götürülür. Pulsuzdur.

Agentliyin ümumi siyahısı

Agentlik açarlarının ümumi siyahı ilə iki əməliyyatı var:

POST /leads/{id}/claim               take a lead from the pool
POST /leads/{id}/claim?assignTo=...  assign it to a team member
POST /leads/{id}/return-to-pool      return a lead to the pool

• Götürmək: defolt olaraq lid agentliyin sahibinə keçir; assignTo (üzvün identifikatoru) parametrini sahib və ya menecer ötürə bilər.
• Ümumi siyahıya qaytarmaq: menecer və daha yuxarı rol, yaxud lidin təyin olunduğu agent. Məcburi olmayan gövdə: {"reason": "..."}. Ümumi siyahı qaydalarının arxivləşdirdiyi lid - code: pool_archived ilə 422: əvvəlcə onu kabinetdə bərpa edin.
• Şəxsi açar və ya kifayət etməyən rol - title: forbidden ilə 403; artıq ümumi siyahıda olmayan lidi götürmək - 404.
• Hər iki əməliyyat lead.updated hadisəsini göndərir.

Dəyişikliklərin izlənməsi

Siyahını sorğulamaq əvəzinə lead.created və lead.updated hadisələrinə abunə olun - bax: Vebhuklar. Hadisədə şəxsi məlumat yoxdur: o, yalnız hansı lidin dəyişdiyini bildirir; kartı ayrıca sorğu ilə oxuyursunuz.

Əlaqəli

• Obyektlər - lidlərin istinad etdiyi kataloq.
• Swipe Match - partnyor brokerlər üçün modul lidləri.
• Vebhuklar - yeni və dəyişdirilmiş lidlər haqqında hadisələr.
• Xətalar - imtinaların oxunması.