API'nin Temelleri - Supportly

Bu sayfa Supportly API’nin tüm uçlarında geçerli olan temelleri kapsar: temel adres, standart yanıt biçimi, anahtar türleri, hız limitleri ve plan limitleri. Uç detayları için yan menüdeki API sayfalarına bakın.

Temel adres

Tüm API uçları şu temel adresin altında çalışır:

https://api.supportly.com.tr/api

İstekler yalnızca HTTPS üzerinden kabul edilir; düz HTTP istekleri kalıcı yönlendirmeyle HTTPS’e yönlendirilir.
İstek gövdesi biçimi application/json.
/health, /api/health ve /api/heartbeat uçları genel hız limitinden muaftır.

Standart yanıt biçimi

Başarılı cevaplar şu biçimde döner:

{
  "success": true,
  "message": "Success",
  "data": { }
}

Hata durumlarında yanıt şöyledir:

{
  "success": false,
  "error": "Mesaj içeriği boş olamaz.",
  "code": "VALIDATION_ERROR",
  "details": null
}

data alanı uçlara özel içerik taşır; code değeri hatayı programatik olarak tanımlar.

Anahtar türleri ve kimlik doğrulama

Anahtar	Biçim	Kullanım
Public widget key	`sp_pub_...`	Widget uçlarında siteyi tanımlar; panelde görülebilir.
Kurumsal API anahtarı	`sup_live_...`	Sohbet isteklerinde `api_key` alanı olarak kullanılır; domain ve IP kilidi uygulanabilir. Yalnızca oluşturulduğu anda tam haliyle gösterilir.
JWT oturum token’ı	Uzun token	Panel uçlarında `Authorization: Bearer <token>`; alternatif olarak `X-Auth-Token` üstbilgisi ya da `supportly_token` çerezi kabul edilir.
Konuşma token’ı	JWT	Ziyaretçinin geçmişini okumak için `Authorization: Bearer <token>`; yedi gün geçerlidir.

Panel uçları için e-posta doğrulaması zorunludur; doğrulanmamış hesaplar EMAIL_NOT_VERIFIED hatası alır (403).

Hız limitleri

Kapsam	Sınır
Tüm API (genel)	300 istek / 15 dakika / IP
`/api/widget` ve `/api/telemetry`	30 istek / 1 dakika / IP
`POST /api/chat/send`	20 istek / 1 dakika (IP + anahtar + ziyaretçi)
`/api/chat` (tüm uçları)	100 istek / 10 dakika (IP + site)
Ek bot koruması	10 istek / 10 saniye; aşımında `ABUSE_DETECTED` döner
`POST /api/leads`	5 istek / 10 dakika / IP
`POST /api/integrations/order-status`	10 istek / 1 dakika / IP
Sağlık uçları	İstisna: hız limiti uygulanmaz

Limit aşıldığında 429 durum kodu döner; gövdede TOO_MANY_REQUESTS, CHAT_RATE_LIMIT veya RATE_LIMITED kodu görülebilir.

Plan limitleri

Günlük mesaj limitleri

Plan	Günlük mesaj
Free ve Basic	20
Growth	500
Pro	Sınırsız

Limit dolduğunda sohbet istekleri RATE_LIMITED (429) ya da LIMIT_REACHED (403) hatasıyla reddedilir. Kullanım %80’e ulaştığında widget quota_warning işaretiyle döner.

Site sayısı limitleri

Plan	Maksimum site
Free	1
Basic	1
Growth	3
Pro	10
Enterprise	Sınırsız

Sınır aşıldığında site oluşturma LIMIT_EXCEEDED_SITES (403) hatasıyla reddedilir.

Özelleştirme sınırları

Free ve Basic planlarda özelleştirme kayıt hakkı toplam 3 keredir ve özel CSS kaydedilmez; beyaz etiket yalnızca Pro planda açılır. Ayrıntılar için Widget Özelleştirme sayfasına bakın.

Sık görülen hata kodları

Kod	HTTP	Anlam
`MISSING_WIDGET_KEY`	400	Widget anahtarı eksik.
`VALIDATION_ERROR`	400	Gövde alanları doğrulamadan geçmedi.
`MESSAGE_TOO_LONG`	400	Mesaj 2.000 karakteri aştı.
`PAYLOAD_TOO_LARGE`	400	İstek gövdesi çok büyük.
`UNAUTHORIZED` / `INVALID_TOKEN`	401	Oturum token’ı eksik veya geçersiz.
`CAPTCHA_REQUIRED`	403	Güvenlik doğrulaması istendi.
`SITE_INACTIVE`	403	Site pasif durumda.
`ORIGIN_DENIED`	403	Origin, izinli origin listesinde yok.
`UNAUTHORIZED_DOMAIN` / `UNAUTHORIZED_IP`	403	Kurumsal anahtarın domain veya IP kilidine takıldı.
`LIMIT_REACHED`	403	Günlük mesaj kotası doldu.
`PLAN_LIMIT_REACHED`	403	Özelleştirme kayıt hakkı doldu.
`EMAIL_NOT_VERIFIED`	403	Panel istekleri için e-posta doğrulanmamış.
`SITE_NOT_FOUND`	404	Site yok ya da pasif.
`TOO_MANY_REQUESTS` / `RATE_LIMITED`	429	Hız veya günlük kota aşımı.
`HANDLER_TIMEOUT`	503	Sunucu istek süresi içinde yanıt vermedi.

Sağlık ve durum uçları

GET /api/health

Hizmetin ayakta olup olmadığını denetler; yanıt 200 ve { "ok": true } gövdesidir.

GET /api/system/status

Sürüm, veritabanı durumu ve bakım modu da dahil genel durum bilgilerini döner.

Sistem durumu yanıtı örneği:

{
  "success": true,
  "status": "online",
  "timestamp": "2026-10-30T09:00:00.000Z",
  "version": "1.0.0",
  "db": "connected",
  "env": "production",
  "persistence": "d1",
  "maintenance_mode": "false",
  "debug_mode": "false"
}

​Temel adres

​Standart yanıt biçimi

​Anahtar türleri ve kimlik doğrulama

​Hız limitleri

​Plan limitleri

​Sık görülen hata kodları

​Sağlık ve durum uçları