API üzerinden lead'ler

Bu bölüm, CRM'deki kendi lead'lerinize programla erişim sağlar: bir web sitesi veya harici bir form talepleri doğrudan panele gönderebilir, sisteminiz de bunları 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_...

Filtreler: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Arşivlenmiş lead'ler normal listede yoktur: archived=true ekleyin. pool=true (yalnızca ajans anahtarları): ajansın ortak havuzundaki lead'ler; kişisel anahtar bunu yok sayar.

Aralık dışındaki limit (1-50, varsayılan 20) ve page (1'den başlar) reddedilmez, aralığa çekilir. Bilinen bir parametrenin diğer geçersiz değerleri (bilinmeyen bir enum değeri, tam sayı olmayan page, from veya to içinde geçersiz tarih) alan adını belirten 400 validation ile reddedilir.

Tek lead

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

expand, durum ve işlem geçmişini (history) ve ekli belgeleri (documents) ekler.

Lead'in biçimi

• id, status, type, priority, source, tags, isArchived; type: buy, rent, viewing, sell, contract, transfer veya user
• 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 niyeti
• comments: müşterinin yorumu ve sizin yorumunuz, ayrı ayrı
• object: talebin ilgili olduğu ilan
• agency: yalnızca ajans lead'lerinde, ajans kimliği ve lead'in ortak havuzda olup olmadığı

Diğer emlakçıların iletişim bilgileri, iç puanlar ve hizmet işaretleri asla döndürülmez.

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": "[email protected]" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Metroya yakın 2 odalı daire arıyor",
    "priority": "warm",
    "consent": true
  }'

Zorunlu: customer.name ve customer.contact içinde müşteriye ulaşmanın en az bir yolu. type: buy (varsayılan) veya rent. priority: hot, warm veya cold. Talep belirli bir ilanla ilgiliyse objectId ve en fazla on kendi tags değerinizi ekleyin.

pool: true, talebi CRM'iniz yerine ortak dağıtım havuzuna gönderir. Varsayılan olarak lead size gelir.

API üzerinden oluşturulan her lead, ayırt edebilmeniz için panelde «API» kaynağıyla işaretlenir.

Lead'i değiştirme

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

Durumu, önceliği, etiketleri ve kendi yorumunuzu değiştirebilirsiniz. Tek bir alan yeterlidir. Durumlar: new, in progress, processing, agreement, closed, not target, failed. Panelin kuralları geçerlidir: ilanlı bir lead paneldeki sonlandırmayla kapatılır (code: finalize), komisyon bekleyen lead durumunu korur (fee_pending), sözleşmeli kapalı bir anlaşma yalnızca panelde değişir (closed): nedeni code içinde olan 422. Diğer nedenler: sender (lead'i başkasına verdiniz, onu alıcı yönetir), module (Swipe Match lead'i, durumu modül yönetir), agreement, network_readonly, forbidden.

Lead'i kaldırma

DELETE /leads/{id}

Lead silinmez, arşivlenir: normal listeden çıkar ancak ?archived=true ile erişilebilir kalır. Geçerli sözleşmesi veya sonlandırma anlaşması olan, sonlandırılmamış ilanlı kapalı ve komisyon bekleyen lead arşivlenmez: code contract_active, agreement, finalize veya fee_pending ile 422.

Lead için ilanlar

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

Müşterinin talebine uyan ilanları döndürür: tür, şehir ve bütçe lead'in kendisinden veya bağlı ilandan alınır. Ücretsiz.

Ajans havuzu

Ajans anahtarlarının iki havuz işlemi vardır:

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

• Alma: varsayılan olarak lead ajans sahibine gider; assignTo (üye kimliği) değerini sahip veya bir yönetici verebilir.
• Havuza geri verme: yöneticiden itibaren veya lead'in atandığı temsilci. İsteğe bağlı gövde: {"reason": "..."}. Havuz kurallarının arşivlediği bir lead: code: pool_archived ile 422; önce panelde geri yükleyin.
• Kişisel bir anahtar veya yetersiz bir rol title: forbidden ile 403; artık havuzda olmayan bir lead'i almak 404.
• İki işlem de bir lead.updated olayı gönderir.

Değişiklikleri izleme

Listeyi sorgulamak yerine lead.created ve lead.updated olaylarına abone olun: bkz. Webhook'lar. Olayda kişisel veri yoktur: yalnızca hangi lead'in değiştiğini söyler; kartı ayrı bir istekle okursunuz.

İlgili makaleler

• İlanlar: lead'lerin atıfta bulunduğu katalog.
• Swipe Match: ortak emlakçılar için modül lead'leri.
• Webhook'lar: yeni ve değişen lead'lerle ilgili olaylar.
• Hatalar: retleri anlama.