v1 · Stabil

API Referansı

10.000+ doğrulanmış oto servis kaydına JSON üzerinden programatik erişim. Bearer token kimlik doğrulama, per-key rate limit, temiz versiyonlu uç noktalar.

https://servisbul.app/api/v1

Playground'ı aç OpenAPI spec (JSON)

İçindekiler

→ Hızlı Başlangıç → Kimlik Doğrulama → Rate Limit → Hata Kodları → GET Servis listesi → GET Tek servis → GET Otomatik tamamlama → GET İlçe listesi → GET İstatistikler → POST Lead oluştur

Başlangıç

Üç adımda API'ye bağlanın

Enterprise plana geçin

API erişimi Enterprise planla gelir. Fiyatlandırma

Anahtar oluşturun

Dashboard → API Anahtarları bölümünden.

İstek gönderin

Header: Authorization: Bearer KEY

Güvenlik

Kimlik Doğrulama

Tüm uç noktalar Authorizationheader'ında Bearer token bekler. Anahtarlar sunucuda SHA-256 hash olarak saklanır — düz anahtar sadece oluşturma anında bir kez gösterilir.

bash

curl https://servisbul.app/api/v1/workshops \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Anahtarınızı güvende tutun

Client-side (tarayıcı, mobil uygulama) içinde açıkta bulundurmayın. Server-to-server istekler için kullanın. Sızdırıldığından şüpheleniyorsanız dashboard'dan anında pasifleştirin.

Kota

Rate Limit

Her API anahtarı için varsayılan sınır 100 istek/dakika. Özel limit gerekiyorsa iletişime geçin.

Her yanıtta aşağıdaki header'lar döner:

X-RateLimit-LimitBu pencerede izin verilen toplam istek.
X-RateLimit-RemainingPencerede kalan istek sayısı.
X-RateLimit-ResetSayacın sıfırlanacağı Unix timestamp (ms).

Sınır aşılırsa 429 Too Many Requests döner.

Hata

Hata Kodları

Tüm hatalar tutarlı bir JSON formunda döner:

json

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Geçersiz API anahtarı."
  }
}

401UNAUTHORIZEDAuthorization header eksik veya boş.
401INVALID_API_KEYAnahtar sistemde bulunamadı.
402PLAN_REQUIREDAnahtar sahibinin Enterprise planı yok.
403KEY_INACTIVEAnahtar dashboard'dan devre dışı bırakılmış.
404NOT_FOUNDİstenen kaynak bulunamadı.
429RATE_LIMITEDDakikalık rate limit aşıldı.
500INTERNAL_ERRORSunucu tarafı beklenmedik hata.

Referans

Uç Noktalar

GET/v1/workshops

Servis listesi

Filtrelenmiş, sayfalanmış oto servis kayıtları. En fazla 100 kayıt/sayfa.

Parametreler

Parametre	Tip	Açıklama
city	string	Şehir filtresi (ör: İstanbul).
district	string	İlçe filtresi.
specialization	string	Uzmanlık alanı (ör: Mekanik).
brand	string	Araç markası (ör: BMW).
vehicleCategory	string	PASSENGER \| HEAVY \| MOTORCYCLE.
verified	boolean	Sadece doğrulanmış servisler.
minRating	number	Minimum Google puanı (0-5).
search	string	Ad veya adreste fuzzy arama.
page	integer	Sayfa numarası (varsayılan 1).
pageSize	integer	Sayfa başına kayıt (max 100, varsayılan 20).

Örnek İstek

bash

curl "https://servisbul.app/api/v1/workshops?city=%C4%B0stanbul&specialization=Mekanik&page=1" \
  -H "Authorization: Bearer $SERVISBUL_KEY"

Örnek Yanıt

json

{
  "success": true,
  "data": [
    {
      "id": "clxxxxxx...",
      "name": "Öz Usta Otomotiv",
      "city": "İstanbul",
      "district": "Kadıköy",
      "address": "Bağdat Cad. No:123",
      "phone": "0216 555 12 34",
      "email": "info@ozusta.com",
      "website": "https://ozusta.com",
      "lat": 40.9812,
      "lng": 29.0456,
      "specializations": ["Mekanik", "Boya-Kaporta"],
      "brands": ["BMW", "Mercedes"],
      "vehicleCategories": ["PASSENGER"],
      "verified": true,
      "rating": 4.7,
      "reviewCount": 142,
      "workingHours": "Pzt-Cmt 09:00-19:00",
      "createdAt": "2025-11-12T10:04:21.000Z",
      "updatedAt": "2026-04-12T08:15:03.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 847,
    "totalPages": 43,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

GET/v1/workshops/{id}

Tek servis

Tek bir servisin tüm detayları (AI review özeti, kalite skoru dahil).

Parametreler

Parametre	Tip	Açıklama
id*	string	Servis ID (path parametresi).

Örnek İstek

bash

curl https://servisbul.app/api/v1/workshops/clxxxxxx \
  -H "Authorization: Bearer $SERVISBUL_KEY"

Örnek Yanıt

json

{
  "success": true,
  "data": {
    "id": "clxxxxxx",
    "name": "Öz Usta Otomotiv",
    "city": "İstanbul",
    "district": "Kadıköy",
    "address": "Bağdat Cad. No:123",
    "phone": "0216 555 12 34",
    "email": "info@ozusta.com",
    "website": "https://ozusta.com",
    "lat": 40.9812,
    "lng": 29.0456,
    "specializations": ["Mekanik", "Boya-Kaporta"],
    "brands": ["BMW", "Mercedes"],
    "vehicleCategories": ["PASSENGER"],
    "verified": true,
    "rating": 4.7,
    "reviewCount": 142,
    "reviewSummary": "Müşteriler iletişim ve fiyatlandırmayı takdir ediyor...",
    "workingHours": "Pzt-Cmt 09:00-19:00",
    "qualityScore": 87,
    "createdAt": "2025-11-12T10:04:21.000Z",
    "updatedAt": "2026-04-12T08:15:03.000Z"
  }
}

GET/v1/workshops/suggest

Otomatik tamamlama

Servis adı, il ve ilçe için fuzzy önerileri. Arama kutularına uygundur.

Parametreler

Parametre	Tip	Açıklama
q*	string	En az 2 karakterlik sorgu.

Örnek İstek

bash

curl "https://servisbul.app/api/v1/workshops/suggest?q=kad" \
  -H "Authorization: Bearer $SERVISBUL_KEY"

Örnek Yanıt

json

{
  "success": true,
  "data": {
    "workshops": [
      { "id": "cl...", "name": "Kaplan Servis", "city": "İstanbul", "district": "Kadıköy" }
    ],
    "cities": [],
    "districts": [
      { "district": "Kadıköy", "city": "İstanbul", "count": 312 }
    ]
  }
}

GET/v1/workshops/districts

İlçe listesi

Belirli bir ildeki ilçeler ve her birinin servis sayısı.

Parametreler

Parametre	Tip	Açıklama
city*	string	Şehir adı.

Örnek İstek

bash

curl "https://servisbul.app/api/v1/workshops/districts?city=%C4%B0stanbul" \
  -H "Authorization: Bearer $SERVISBUL_KEY"

Örnek Yanıt

json

{
  "success": true,
  "data": [
    { "name": "Kadıköy", "count": 312 },
    { "name": "Şişli", "count": 289 }
  ]
}

GET/v1/workshops/stats

İstatistikler

Veritabanı geneli toplu sayılar, en yoğun iller ve uzmanlık dağılımı.

Örnek İstek

bash

curl https://servisbul.app/api/v1/workshops/stats \
  -H "Authorization: Bearer $SERVISBUL_KEY"

Örnek Yanıt

json

{
  "success": true,
  "data": {
    "totalWorkshops": 10631,
    "verifiedCount": 8412,
    "verificationRate": 79.1,
    "uniqueCities": 81,
    "recentlyAddedLast30d": 214,
    "topCities": [
      { "city": "İstanbul", "count": 2847 }
    ],
    "topSpecializations": [
      { "name": "Mekanik", "count": 7812 }
    ]
  }
}

POST/v1/leads

Lead oluştur

Bir servis kaydına müşteri talebi iletir. Servis sahibi dashboard'da görür. Telefon numarası bazlı spam koruması: dakikada 3 istek.

Parametreler

Parametre	Tip	Açıklama
workshopId*	string	Hedef servis ID.
customerName*	string (2-80)	Müşteri adı.
customerPhone*	string (7-20)	Telefon (0532 555 12 34 gibi).
description*	string (5-1000)	Talep açıklaması.
vehicleBrand	string	Araç markası (ops.).
vehicleModel	string	Araç modeli (ops.).
vehicleYear	integer	Model yılı 1950-2100 (ops.).

Örnek İstek

bash

curl -X POST https://servisbul.app/api/v1/leads \
  -H "Authorization: Bearer $SERVISBUL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workshopId": "clxxxxxx",
    "customerName": "Ahmet Yılmaz",
    "customerPhone": "0532 555 12 34",
    "vehicleBrand": "BMW",
    "vehicleModel": "320i",
    "vehicleYear": 2019,
    "description": "Motor yağı değişimi ve genel bakım randevusu."
  }'

Örnek Yanıt

json

{
  "success": true,
  "data": {
    "id": "clxxlead",
    "workshopId": "clxxxxxx",
    "customerName": "Ahmet Yılmaz",
    "customerPhone": "05325551234",
    "vehicleBrand": "BMW",
    "vehicleModel": "320i",
    "vehicleYear": 2019,
    "description": "Motor yağı değişimi ve genel bakım randevusu.",
    "status": "PENDING",
    "createdAt": "2026-04-15T10:04:21.000Z"
  }
}

Entegrasyona hazır mısınız?

Enterprise plan ile API, sınırsız export, CRM entegrasyonu ve dedike hesap yöneticisi. Özel fiyatlandırma için iletişime geçin.

Planları İncele İletişime Geç