> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supportly.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# API'nin Temelleri

> Supportly API temel adresi, standart yanıt biçimi, anahtar türleri, hata kodları, hız limitleri ve plan limitleri.

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:

```text theme={null}
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:

```json theme={null}
{
  "success": true,
  "message": "Success",
  "data": { }
}
```

Hata durumlarında yanıt şöyledir:

```json theme={null}
{
  "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

> [accordion] 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.

> [accordion] 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.

> [accordion] Ö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](https://docs.supportly.com.tr/widget/ozellestirme) 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ı

> [card] GET /api/health
>
> Hizmetin ayakta olup olmadığını denetler; yanıt `200` ve `{ "ok": true }` gövdesidir.

> [card] 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:

```json theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.