Qando API'si nedir?
Qando API'si, kendi yazılımınızı Qando'ya bağlamanızı sağlayan bir REST arayüzüdür.
Ürünlerinizi, siparişlerinizi ve stoklarınızı program aracılığıyla okuyup güncelleyebilir;
kendi entegrasyonlarınızı geliştirebilirsiniz. Tüm istekler HTTPS üzerinden yapılır ve
istek/yanıt gövdeleri JSON biçimindedir.
Bu doküman, API'ye bağlanmanın ilk adımı olan kimlik doğrulamayı anlatır.
Temel kavramlar
Her korunan API isteğinde iki başlık (header) zorunludur:
- Authorization: Bearer <erişim_jetonu> — kim olduğunuzu doğrular.
- X-Tenant-Id: <workspace_kimliği> — hangi çalışma alanı (mağaza) adına işlem yaptığınızı
belirtir. Bir kullanıcı birden çok çalışma alanına üye olabildiği için bu başlık şarttır.
Adım 1 — Giriş yaparak erişim jetonu alma
E-posta ve parolanızla giriş yapıp bir erişim jetonu (access token) alırsınız:
```
POST /auth/login
Content-Type: application/json
{
"email": "kullanici@ornek.com",
"password": "parolaniz"
}
```
Başarılı yanıt, jetonu ve üyesi olduğunuz çalışma alanlarını içerir:
```
{
"accessToken": "eyJ...",
"user": {
"id": "...",
"email": "kullanici@ornek.com",
"tenants": [
{ "tenantId": "abc-123", "name": "Mağazam", "role": "OWNER", "status": "ACTIVE" }
]
}
}
```
Yanıttaki accessToken'ı ve işlem yapacağınız çalışma alanının tenantId değerini not
edin.
Adım 2 — Korunan bir isteği çağırma
Aldığınız jeton ve çalışma alanı kimliğini her isteğe başlık olarak ekleyin. Örneğin ürün
listesini almak için:
```
GET /products
Authorization: Bearer eyJ...
X-Tenant-Id: abc-123
```
Aynı kalıp tüm korunan uç noktalar için geçerlidir (siparişler, stok, kategoriler vb.).
Başlıklardan biri eksik veya geçersizse istek reddedilir.
Adım 3 — Jeton süresi dolunca yenileme
Erişim jetonu güvenlik için kısa ömürlüdür. Süresi dolduğunda istekler 401 Unauthorized
döner. Bu durumda yeni bir jeton alın:
```
POST /auth/refresh
```
Yenileme başarılıysa yanıtta yeni bir accessToken gelir; onunla başarısız isteği
tekrarlarsınız. Yenileme de başarısız olursa (oturum geçersizse) yeniden /auth/login
ile giriş yapmanız gerekir.
Önerilen akış
1. Giriş yap, jetonu ve tenantId'yi sakla.
2. Her isteğe Authorization ve X-Tenant-Id başlıklarını ekle.
3. 401 alırsan bir kez /auth/refresh dene, yeni jetonla isteği tekrarla.
4. Yenileme de başarısızsa oturumu kapat ve baştan giriş yap.
Para birimi ve tarih biçimleri
- Fiyatlar en küçük birim (kuruş) cinsinden tam sayı döner. Örneğin
12500= 125,00 TL.
Görüntülemek için 100'e bölün.
- Tüm tarih/saat değerleri ISO 8601 (UTC) biçimindedir (örn.
2026-01-01T00:00:00Z).
Güvenlik notları
- Jetonlar ve parolalar gizli bilgidir; istemci tarafında güvenli saklayın, kod deposuna
koymayın.
- Yanlış çalışma alanı kimliğiyle başka bir mağazanın verisine erişemezsiniz; her istek
yalnızca X-Tenant-Id ile belirtilen çalışma alanının verisini döndürür.