Müşteri

Müşteri API'si, Sherlock müşteri kayıtlarınızı kendi sistemlerinizden yönetmenizi sağlar. Bu uç noktalarla yeni müşteri oluşturabilir, mevcut kayıtları sorgulayabilir (telefon veya e-posta üzerinden mükerrer kontrolü dâhil) ve müşteri bilgilerini güncelleyebilirsiniz.

Tüm istekler X-API-Key başlığı ile kimlik doğrulaması gerektirir ve yalnızca kendi firmanızın müşterilerine erişim sağlar.

Taban URL

https://sherlock.sanalsantral.com.tr/api/v1

Bu bölümdeki uç noktalar

Metot	Uç Nokta	Açıklama
POST	/customers	Yeni müşteri oluştur
GET	/customers	Müşterileri listele / ara
GET	/customers/{id}	Tek müşteri getir
PUT	/customers/{id}	Müşteri güncelle

Müşteri Veri Modeli

Bir müşteri kaydı aşağıdaki alanlardan oluşur:

Alan	Tip	Zorunlu	Açıklama
id	integer	(otomatik)	Müşteri ID
company	string	Evet	Ünvan / firma adı
name	string	Hayır	Yetkili kişi adı
phone	string	Hayır	Telefon numarası (normalize edilir)
mail	string	Hayır	E-posta adresi
address	string	Hayır	Adres
status	enum	Hayır	bekliyor
assignedTo	integer	Hayır	Atanan kullanıcı (userId)
stageId	integer	Hayır	Müşteri aşaması
customValue1	string	Hayır	Serbest özel alan 1
customValue2	string	Hayır	Serbest özel alan 2
customValue3	string	Hayır	Serbest özel alan 3
createdAt	datetime	(otomatik)	Oluşturulma tarihi

> companyId alanı API anahtarınızdan otomatik çözülür; istek gövdesinde gönderilmez.

1. Müşteri Oluşturma

Yeni bir müşteri kaydı oluşturur. Telefon numarası verilirse, aynı firmada daha önce eklenip eklenmediği kontrol edilir ve mükerrer kayıt engellenir.

POST /api/v1/customers

İstek Gövdesi

json

{
  "company": "Acme Yazılım A.Ş.",
  "name": "Ahmet Yılmaz",
  "phone": "05321234567",
  "mail": "[email protected]",
  "address": "Maslak, İstanbul",
  "status": "aktif",
  "assignedTo": 12,
  "stageId": 3,
  "customValue1": "Web sitesinden geldi"
}

Alan	Zorunlu	Açıklama
company	Evet	Boşsa 400 döner
phone	Hayır	Normalize edilir; 7 haneden kısaysa hata. Aynı firmada mükerrer telefon reddedilir
mail	Hayır	Ayrı iletişim kaydı olarak eklenir
Diğerleri	Hayır	Bkz. Veri Modeli

Örnek İstek

bash

curl -X POST "https://firma.sanalsantral.com/api/v1/customers" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Acme Yazılım A.Ş.",
    "name": "Ahmet Yılmaz",
    "phone": "05321234567",
    "mail": "[email protected]"
  }'

Başarılı Yanıt (201)

json

{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": 8842,
    "company": "Acme Yazılım A.Ş.",
    "name": "Ahmet Yılmaz",
    "phone": "905321234567",
    "mail": "[email protected]",
    "status": "aktif",
    "companyId": 4213,
    "createdAt": "2026-07-07T09:15:00.000Z"
  }
}

Hatalar

HTTP	Durum	Yanıt
400	Ünvan eksik	{ "success": false, "error": "company is required" }
409	Telefon mükerrer	{ "success": false, "error": "Bu telefon numarası daha önce eklenmiş." }
422	Telefon hatalı	{ "success": false, "error": "Telefon numarası hatalı" }

2. Müşteri Sorgulama / Kontrol

a) Tek müşteri getir

GET /api/v1/customers/{id}

bash

curl "https://firma.sanalsantral.com/api/v1/customers/8842" \
  -H "X-API-Key: sk_live_xxx"

Kayıt başka bir firmaya aitse veya bulunamazsa 404 döner.

json

{
  "success": true,
  "data": {
    "id": 8842,
    "company": "Acme Yazılım A.Ş.",
    "name": "Ahmet Yılmaz",
    "phone": "905321234567",
    "mail": "[email protected]",
    "status": "aktif",
    "stageId": 3,
    "companyId": 4213,
    "contacts": [
      { "id": 1, "type": 0, "value": "905321234567", "name": "Ahmet Yılmaz" },
      { "id": 2, "type": 1, "value": "[email protected]", "name": "Ahmet Yılmaz" }
    ],
    "createdAt": "2026-07-07T09:15:00.000Z"
  }
}

b) Listele / Ara

GET /api/v1/customers

Firmanızın müşterilerini sayfalı olarak listeler. Mükerrer kontrolü için search ile telefon, e-posta veya ünvan üzerinden arama yapabilirsiniz.

Parametre	Zorunlu	Varsayılan	Açıklama
search	Hayır	-	Ünvan, ad, adres, özel alanlar ve telefon/e-posta içinde arar
status	Hayır	all	bekliyor
page	Hayır	1	Sayfa numarası
limit	Hayır	10	Sayfa başına kayıt (max 10000)

bash

# Telefonla mükerrer kontrolü
curl "https://firma.sanalsantral.com/api/v1/customers?search=05321234567" \
  -H "X-API-Key: sk_live_xxx"

json

{
  "success": true,
  "data": [
    {
      "id": 8842,
      "company": "Acme Yazılım A.Ş.",
      "name": "Ahmet Yılmaz",
      "phone": "905321234567",
      "mail": "[email protected]",
      "status": "aktif"
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 }
}

> data: [] (boş dizi) → eşleşen müşteri yok; yeni kayıt oluşturulabilir.

3. Müşteri Düzenleme

Var olan bir müşteriyi günceller. Yalnızca gönderilen alanlar değişir; gönderilmeyen alanlar mevcut değerini korur.

PUT /api/v1/customers/{id}

İstek Gövdesi

json

{
  "company": "Acme Yazılım A.Ş. (Güncel)",
  "status": "iptal",
  "assignedTo": 15,
  "customValue1": "Sözleşme yenilendi"
}

Alan	Zorunlu	Açıklama
company	Evet	Boş gönderilemez
name, status, assignedTo, address, stageId, customValue1..3	Hayır	Verilmeyen alan mevcut değerini korur

Örnek İstek

bash

curl -X PUT "https://firma.sanalsantral.com/api/v1/customers/8842" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "company": "Acme Yazılım A.Ş.", "status": "iptal" }'

Başarılı Yanıt (200)

json

{
  "success": true,
  "message": "Customer updated successfully",
  "data": { "id": 8842, "company": "Acme Yazılım A.Ş.", "status": "iptal", "companyId": 4213 }
}

Hatalar

HTTP	Durum	Yanıt
400	ID veya ünvan eksik	{ "success": false, "error": "company cannot be empty" }
404	Müşteri yok / başka firmaya ait	{ "success": false, "error": "Customer not found" }

Ortak Hata Kodları

HTTP	Anlam
400	Geçersiz istek (eksik/hatalı alan)
401	API anahtarı eksik/geçersiz
404	Kayıt bulunamadı (veya erişim dışı)
409	Çakışma (mükerrer telefon)
422	İşlenemeyen içerik (örn. telefon formatı)
429	Hız limiti aşıldı
500	Sunucu hatası
503	Kimlik doğrulama servisi erişilemez