REST · JSON · v1

Satışkatla API

Satışkatla platformunun API merkezi. Bu sayfa hem doküman hem test arayüzü: her servisi buradan, gerçek sunucuya karşı deneyebilirsin.

Base URL

https://api.satiskatla.com

Sistem durumu

15 dk

Access token
EdDSA · JWT

30 gün

Refresh token
tek kullanımlık

64 bit

Snowflake id
JSON'da string

Hızlı başlangıç

# 1) Kayıt ol: e-postana doğrulama linki gelir
curl -X POST https://api.satiskatla.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "ad@firma.com", "password": "GucluParola123", "full_name": "Ad Soyad"}'

# 2) Linke tıklayıp doğruladıktan sonra giriş yap
curl -X POST https://api.satiskatla.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "ad@firma.com", "password": "GucluParola123"}'

# 3) Dönen access_token ile istek at
curl https://api.satiskatla.com/v1/me -H "Authorization: Bearer $ACCESS_TOKEN"

Kimlik doğrulama

Korunan servisler Authorization: Bearer <access_token> başlığı ister. Access token kısa ömürlüdür; süresi dolunca refresh token ile yenisi alınır.

1 Giriş

login, verify-email veya GlobalTrustID ile access + refresh token alınır.
2 İstek

Her korunan istekte Authorization: Bearer <access_token> gönderilir.
3 Yenileme

401 invalid_token gelince /v1/auth/refresh ile yeni çift alınır; eski refresh token biter.
4 Çıkış

/v1/auth/logout oturumu kapatır; o oturumun tüm token'ları geçersiz olur.

🌐 Tarayıcı (console)

İzinli origin'lerden gelen isteklerde refresh token httpOnly cookie'de tutulur, JavaScript erişemez (XSS ile çalınamaz). fetch(…, {credentials: "include"}) kullan.

📱 Mobil / sunucu

Refresh token yanıt gövdesinde döner; güvenli depoda (Keychain, Keystore) sakla, yenilerken gövdede refresh_token olarak gönder.

Hatalar

Tüm hatalar aynı biçimde döner. request_id her yanıtta X-Request-ID başlığında da vardır; destek isterken bunu ilet.

{"error": {"code": "validation_failed", "message": "Bazı alanlar geçersiz.", "request_id": "b4b3c7ad13f04cda", "fields": {"password": "parola en az 10 karakter olmalı"}}}

code	HTTP	Anlamı
validation_failed	422	Alanlar geçersiz; ayrıntılar fields içinde
invalid_json	400	Gövde çözümlenemedi veya bilinmeyen alan var
unauthorized	401	Authorization başlığı yok
invalid_token	401	Access token geçersiz veya süresi dolmuş: /v1/auth/refresh çağır
session_revoked	401	Oturum kapatılmış; tekrar giriş gerekir
invalid_credentials	401	E-posta veya parola hatalı
email_not_verified	403	E-posta doğrulanmamış
refresh_token_reused	401	Kullanılmış refresh token tekrar geldi; oturum iptal edildi
rate_limited	429	Rate limit aşıldı; Retry-After başlığı kadar bekle
too_many_attempts	429	Bu e-posta için çok fazla hatalı giriş
internal	500	Beklenmeyen hata; request_id ile bildir

Rate limit

Limitler kayan pencereyle uygulanır: genel olarak IP başına dakikada 600 istek, kimlik doğrulama servislerinde her servisin altında yazan daha sıkı limitler. Limit aşılınca 429 rate_limited döner.

X-RateLimit-Limit

Pencere içinde izin verilen istek sayısı

X-RateLimit-Remaining

Bu penceredeki kalan istek

Retry-After

429 durumunda kaç saniye sonra tekrar denenebileceği

Sağlık

GET /v1/health

Servis durumu

Veritabanı, Redis ve dosya deposunun (MinIO) durumunu ve gecikmesini döner. Bir bileşen çalışmıyorsa 503 döner; izleme ve yük dengeleyiciler için uygundur.

Yanıtlar

200Tüm bileşenler çalışıyor
503En az bir bileşen çalışmıyor

curl https://api.satiskatla.com/v1/health

const res = await fetch("https://api.satiskatla.com/v1/health", {
  method: "GET",
  credentials: "include", // refresh token cookie'si için
});
const data = await res.json();

{
  "components": {
    "database": {
      "latency_ms": 1,
      "status": "up"
    },
    "redis": {
      "latency_ms": 0,
      "status": "up"
    },
    "storage": {
      "latency_ms": 3,
      "status": "up"
    }
  },
  "status": "ok",
  "time": "2026-10-08T14:06:12Z"
}

Dene

Kimlik doğrulama

POST /v1/auth/register

⏱ IP başına 10/saat · e-posta başına 3/saat

Kayıt ol

Hesap açar ve e-posta doğrulama linki gönderir; e-posta doğrulanmadan giriş yapılamaz. E-posta zaten kayıtlıysa da aynı yanıt döner (hesap varlığı sızdırılmaz), o adrese 'zaten hesabın var' e-postası gider.

İstek gövdesi

email string zorunlu

E-posta adresi

password string zorunlu

En az 10 karakter, harf ve rakam içermeli

full_name string zorunlu

Ad soyad (2-100 karakter)

Yanıtlar

202Kayıt alındı, doğrulama e-postası gönderildi
422Geçersiz alanlar (fields içinde)
429Rate limit

curl -X POST https://api.satiskatla.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "ad@firma.com", "password": "GucluParola123", "full_name": "Ad Soyad"}'

const res = await fetch("https://api.satiskatla.com/v1/auth/register", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"email": "ad@firma.com", "password": "GucluParola123", "full_name": "Ad Soyad"}),
});
const data = await res.json();

{
  "message": "Kayıt alındı. Hesabını etkinleştirmek için e-posta adresine gönderilen linke tıkla."
}

Dene

POST /v1/auth/verify-email

⏱ IP başına 20/saat

E-postayı doğrula

E-postadaki linkte gelen tek kullanımlık token ile hesabı etkinleştirir ve oturum açar. Link 24 saat geçerlidir.

İstek gövdesi

token string zorunlu

Doğrulama linkindeki token

Yanıtlar

200Doğrulandı, token çifti
400Link geçersiz veya süresi dolmuş

curl -X POST https://api.satiskatla.com/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "Qm9…"}'

const res = await fetch("https://api.satiskatla.com/v1/auth/verify-email", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"token": "Qm9…"}),
});
const data = await res.json();

{
  "data": {
    "access_expires_at": "2026-10-08T14:21:12Z",
    "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ims…",
    "expires_in": 900,
    "refresh_expires_at": "2026-11-07T14:06:12Z",
    "refresh_token": "Yk3…(tarayıcıda cookie'de)",
    "token_type": "Bearer",
    "user": {
      "created_at": "2026-10-08T17:06:12+03:00",
      "email": "ad@firma.com",
      "email_verified": true,
      "full_name": "Ad Soyad",
      "gti_linked": false,
      "has_password": true,
      "id": "101681556225003520",
      "phone": "+905xxxxxxxxx"
    }
  }
}

Dene

POST /v1/auth/resend-verification

⏱ IP başına 10/saat · e-posta başına 3/saat

Doğrulamayı yeniden gönder

Doğrulanmamış hesaba yeni bir doğrulama linki gönderir. Hesap olsun olmasın yanıt aynıdır.

İstek gövdesi

email string zorunlu

Kayıtta kullanılan e-posta

Yanıtlar

202Her durumda aynı yanıt

curl -X POST https://api.satiskatla.com/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "ad@firma.com"}'

const res = await fetch("https://api.satiskatla.com/v1/auth/resend-verification", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"email": "ad@firma.com"}),
});
const data = await res.json();

{
  "message": "Bu e-postayla doğrulanmamış bir hesap varsa yeni doğrulama linki gönderildi."
}

Dene

POST

⏱ IP başına 20/dk · e-posta başına 5 hatalı deneme/15 dk

Giriş yap

E-posta ve parola ile access token (15 dk) ve refresh token (30 gün, tek kullanımlık) alır. İzinli bir tarayıcı origin'inden gelen isteklerde refresh token httpOnly cookie'ye konur ve gövdede yer almaz. Bir e-posta için 15 dakikada 5 hatalı denemeden sonra giriş geçici olarak kilitlenir.

İstek gövdesi

email string zorunlu

E-posta adresi

password string zorunlu

Parola

Yanıtlar

200Token çifti
401E-posta veya parola hatalı
403E-posta doğrulanmamış
429Çok fazla deneme

curl -X POST https://api.satiskatla.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "ad@firma.com", "password": "GucluParola123"}'

const res = await fetch("https://api.satiskatla.com/v1/auth/login", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"email": "ad@firma.com", "password": "GucluParola123"}),
});
const data = await res.json();

{
  "data": {
    "access_expires_at": "2026-10-08T14:21:12Z",
    "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ims…",
    "expires_in": 900,
    "refresh_expires_at": "2026-11-07T14:06:12Z",
    "refresh_token": "Yk3…(tarayıcıda cookie'de)",
    "token_type": "Bearer",
    "user": {
      "created_at": "2026-10-08T17:06:12+03:00",
      "email": "ad@firma.com",
      "email_verified": true,
      "full_name": "Ad Soyad",
      "gti_linked": false,
      "has_password": true,
      "id": "101681556225003520",
      "phone": "+905xxxxxxxxx"
    }
  }
}

Dene

POST /v1/auth/refresh

⏱ IP başına 60/dk

Token yenile

Yeni bir token çifti verir; kullanılan refresh token geçersiz olur (rotation). Kullanılmış bir refresh token tekrar gönderilirse token çalınmış sayılır ve oturumun tamamı iptal edilir. Aynı token son 15 saniyede yenilenmişse 409 döner (eşzamanlı sekmeler için).

İstek gövdesi

refresh_token string opsiyonel

Mobil/sunucu istemcileri gövdede gönderir; tarayıcıda cookie kullanılır

Yanıtlar

200Yeni token çifti
401Geçersiz, süresi dolmuş veya iptal edilmiş
409Az önce yenilendi

curl -X POST https://api.satiskatla.com/v1/auth/refresh

const res = await fetch("https://api.satiskatla.com/v1/auth/refresh", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
});
const data = await res.json();

{
  "data": {
    "access_expires_at": "2026-10-08T14:21:12Z",
    "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ims…",
    "expires_in": 900,
    "refresh_expires_at": "2026-11-07T14:06:12Z",
    "refresh_token": "Yk3…(tarayıcıda cookie'de)",
    "token_type": "Bearer",
    "user": {
      "created_at": "2026-10-08T17:06:12+03:00",
      "email": "ad@firma.com",
      "email_verified": true,
      "full_name": "Ad Soyad",
      "gti_linked": false,
      "has_password": true,
      "id": "101681556225003520",
      "phone": "+905xxxxxxxxx"
    }
  }
}

Dene

POST /v1/auth/logout

Çıkış yap

Oturumun tüm refresh token'larını iptal eder; o oturumun access token'ları da süresi dolmadan reddedilir. İdempotenttir.

İstek gövdesi

refresh_token string opsiyonel

Tarayıcıda cookie kullanılır

Yanıtlar

204Çıkış yapıldı

curl -X POST https://api.satiskatla.com/v1/auth/logout

const res = await fetch("https://api.satiskatla.com/v1/auth/logout", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
});
const data = await res.json();

Dene

GlobalTrustID

GET /v1/auth/login_with_gti

⏱ IP başına 30/dk

GlobalTrustID ile giriş

Kullanıcıyı GlobalTrustID'ye yönlendirir (PKCE). Onaydan sonra redirect_uri adresine #code=… ile dönülür; bu tek kullanımlık kod 60 saniye içinde exchange servisiyle token çiftine çevrilir. Hesap yoksa GlobalTrustID'nin doğruladığı e-postayla otomatik açılır.

Query parametreleri

redirect_uri url opsiyonel

Dönüş adresi; izin listesindeki bir origin olmalı. Boşsa bu doküman sayfası.

Yanıtlar

302GlobalTrustID'ye yönlendirme
400redirect_uri izin listesinde değil

# Tarayıcıyı bu adrese yönlendir:
https://api.satiskatla.com/v1/auth/login_with_gti?redirect_uri=https%3A%2F%2Fconsole.satiskatla.com%2Fauth%2Fcallback

location.href = "https://api.satiskatla.com/v1/auth/login_with_gti?redirect_uri=" +
  encodeURIComponent(location.origin + "/auth/callback");

Dene

POST /v1/auth/login_with_gti/exchange

⏱ IP başına 30/dk

GTI kodunu token'a çevir

Dönüş adresindeki #code değerini token çiftine çevirir. Kod tek kullanımlıktır ve 60 saniye geçerlidir.

İstek gövdesi

code string zorunlu

Dönüş adresindeki #code değeri

Yanıtlar

200Token çifti
400Kod geçersiz, kullanılmış veya süresi dolmuş

curl -X POST https://api.satiskatla.com/v1/auth/login_with_gti/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "…"}'

const res = await fetch("https://api.satiskatla.com/v1/auth/login_with_gti/exchange", {
  method: "POST",
  credentials: "include", // refresh token cookie'si için
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"code": "…"}),
});
const data = await res.json();

{
  "data": {
    "access_expires_at": "2026-10-08T14:21:12Z",
    "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ims…",
    "expires_in": 900,
    "refresh_expires_at": "2026-11-07T14:06:12Z",
    "refresh_token": "Yk3…(tarayıcıda cookie'de)",
    "token_type": "Bearer",
    "user": {
      "created_at": "2026-10-08T17:06:12+03:00",
      "email": "ad@firma.com",
      "email_verified": true,
      "full_name": "Ad Soyad",
      "gti_linked": false,
      "has_password": true,
      "id": "101681556225003520",
      "phone": "+905xxxxxxxxx"
    }
  }
}

Dene

Kullanıcı

GET /v1/me

🔒 Bearer token

Oturumdaki kullanıcı

Access token sahibinin profilini döner. Yanıt 60 saniye önbelleklenir.

Yanıtlar

200Profil
401Token yok, geçersiz veya oturum kapatılmış

curl https://api.satiskatla.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch("https://api.satiskatla.com/v1/me", {
  method: "GET",
  credentials: "include", // refresh token cookie'si için
  headers: { Authorization: `Bearer ${accessToken}` },
});
const data = await res.json();

{
  "data": {
    "created_at": "2026-10-08T17:06:12+03:00",
    "email": "ad@firma.com",
    "email_verified": true,
    "full_name": "Ad Soyad",
    "gti_linked": false,
    "has_password": true,
    "id": "101681556225003520",
    "phone": "+905xxxxxxxxx"
  }
}

Dene Önce giriş yap: token otomatik eklenir