API üzerinden lead'ler

Bu bölüm, CRM'deki kendi lead'lerinize programlı erişim verir: bir site ya da dış bir form talepleri doğrudan kabine gönderebilir, sisteminiz de onları okuyup durumlar arasında ilerletebilir.

Temel adres: https://developers.grem.capital/api/v1.

Liste

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

Süzgeç parametreleri: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Arşivlenmiş lead'ler olağan listede yer almaz - archived=true ekleyin.

Tek lead

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

expand, durum ve eylem geçmişini (history) ile ekli belgelerin listesini (documents) ekler.

Lead'in yapısı

• id, status, type, priority, source, tags, isArchived
• createdAt, updatedAt, lastActivityAt
• customer - ad, ülke, mesajlaşma uygulaması ve bir contact bloğu (phone, email, messengerHandle, profileUrl)
• budget - { value, currency }
• intent - şehir, semtler, işlem türü ve müşterinin ne aradığı
• comments - müşterinin notu ve sizin notunuz, ayrı ayrı
• object - talebin ilgili olduğu ilan
• deadline, reminder
• agency - yalnızca ajans lead'lerinde bulunur: ajansın kimliği ve lead'in ortak havuzda olup olmadığı

Diğer brokerların iletişim bilgileri, iç puanlama ve hizmet bayrakları hiçbir zaman döndürülmez.

Dışarıdan talep gönderme

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
  }'

Zorunlu: customer.name ve customer.contact içinde en az bir iletişim yolu. type değeri buy (varsayılan) ya da rent'tir. priority ise hot, warm ya da cold olur. Talep belirli bir ilanla ilgiliyse objectId ekleyebilir, tags içinde de en fazla on kendi etiketinizi verebilirsiniz.

pool: true bayrağı talebi kendi CRM'iniz yerine dağıtım için ortak havuza yönlendirir. Varsayılan olarak lead size düşer.

API üzerinden oluşturulan her lead kabinde «API» kaynağıyla işaretlenir; böylece diğerlerinden ayrılır.

Lead'i değiştirme

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

Durum, öncelik, etiketler ve kendi notunuz değiştirilebilir. Tek alan yeterlidir. Kullanılabilir durumlar: new, in progress, processing, agreement, closed, not target, failed.

Lead'i kaldırma

DELETE /leads/{id}

Bu silmez, arşivler: lead olağan listeden düşer ama ?archived=true ile erişilebilir kalır.

Lead'e uygun mülkler

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

Müşterinin talebine yanıt veren ilanları döndürür: tip, şehir ve bütçe lead'in kendisinden ya da ona bağlı ilandan gelir. Bu çağrı ücretsizdir.

Ajans havuzu

Ajans anahtarları havuzla ilgili iki eylem alır:

POST /leads/{id}/claim               havuzdaki lead'i kendine alma
POST /leads/{id}/claim?assignTo=…    lead'i ekip üyesine atama
POST /leads/{id}/return-to-pool      lead'i havuza geri verme

İkisi de ajansta lead dağıtımına izin veren bir rol ister. Kişisel anahtar reddedilir ve başkasının aldığı bir lead'i almak 409 döndürür.

Değişiklikleri izleme

Listeyi yoklamak yerine lead.created ve lead.updated olaylarına abone olun - bkz. Webhook'lar. Olayın kendisi kişisel veri taşımaz: yalnızca hangi lead'in değiştiğini söyler, kartı ayrı bir istekle okursunuz.

İlgili yazılar

• Nesneler (okuma) - lead'lerin işaret ettiği ilan kataloğu.
• Webhook'lar - yeni ve değişen lead'lerin olayları.
• Hatalar - bir reddin nasıl okunacağı.