API Authentication

Bearer token, refresh akışı, X-Tenant-Id header — Qando REST API'yi kullanma.

Geliştirici kullanımı

Qando REST API ile kendi sisteminizden Qando verilerine erişebilirsiniz: ürün listele, sipariş çek, stok güncellemesi yap, vs.

Base URL

https://api.qando.com.tr/api

Tüm endpoint'ler bu prefix altındadır.

Authentication

Tüm korunan endpoint'ler Bearer token ister:

Authorization: Bearer <accessToken>

Token nasıl alınır?

Login akışı

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "..."
}

Yanıt:

{
  "accessToken": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "you@example.com",
    "fullName": "Ad Soyad",
    "tenants": [
      { "tenantId": "uuid", "name": "Mağaza", "role": "OWNER" }
    ]
  }
}

accessToken'i sonraki isteklerde kullanın.

Access token süresi

Access token: 15 dakika geçerli
Refresh token: 7 gün geçerli — HttpOnly cookie olarak set edilir

15 dakika dolunca 401 Unauthorized alırsınız.

Token yenileme

POST /api/auth/refresh
Cookie: refreshToken=...

Yanıt yeni accessToken döner.

X-Tenant-Id header

Korunan endpoint'lerde tenant belirtmek zorundasınız:

GET /api/products
Authorization: Bearer <token>
X-Tenant-Id: <tenantId>

Tenant ID login yanıtındaki user.tenants[].tenantId değerinden alınır.

Bir kullanıcının birden fazla tenant'ı varsa her istekte hangisi için olduğunu belirtmelisiniz.

Logout

POST /api/auth/logout
Cookie: refreshToken=...

Refresh token sunucuda invalidate edilir.

Tipik istek örneği

curl -X GET https://api.qando.com.tr/api/products \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Tenant-Id: 5e6f7a8b-..."

SDK / kütüphane?

Şu an Qando resmi SDK sunmaz. REST API'yi doğrudan kullanın. Aşağıdaki örnekler kolaylaştırır:

Axios (JS) — Authorization + X-Tenant-Id interceptor ekleyin
Python requests — headers parametresi ile
PHP cURL — CURLOPT_HTTPHEADER ile

Rate limit

API rate limit'leri:

Auth endpoint'leri: dakikada 10 istek
Diğer korunan endpoint'ler: dakikada 60 istek (tenant başına)
Public endpoint'ler (CMS): dakikada 100

Aşıldığında 429 Too Many Requests alırsınız. Retry-After header'ı bekleme süresini belirtir.

CORS

Web tarayıcıdan API'ye doğrudan istek yapılırsa CORS aktif olur. Şu domain'lerden istek kabul edilir:

https://app.qando.com.tr
https://qando.com.tr
https://admin.qando.com.tr

Diğer domain'lerden istek atmak için kendi backend'inizden API'ye gidin (server-to-server).

Yaygın sorunlar

401 Unauthorized → Token süresi dolmuş; refresh akışını çalıştır
403 Forbidden → Tenant yetkiniz yok veya yanlış tenantId
400 Bad Request: tenantId required → X-Tenant-Id header eklenmemiş
429 Too Many Requests → Rate limit; Retry-After ile bekle