API Referansı

Hotspot Yönetim Sistemi API v1 için tüm endpoint'lerin detaylı referansı.

Base URL

http://localhost:3000/api/v1

Endpoint'ler

API Durum Kontrolü

GET /api/v1

API'nin aktif olup olmadığını kontrol eder.

Kimlik Doğrulama: Gerekli (Bearer Token)

Yanıt:

{
  "success": true,
  "message": "Server API aktif"
}

---

Hotspot Kullanıcıları

GET /api/v1/hotspot-users

Hotspot kullanıcılarını listeler.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: read

Query Parametreleri:

• venueId (string, zorunlu): Venue ID
• status (string, opsiyonel): Kullanıcı durumu (active, blocked, expired)
• macAddress (string, opsiyonel): MAC adresi filtresi
• page (integer, opsiyonel): Sayfa numarası (varsayılan: 1)
• limit (integer, opsiyonel): Sayfa başına kayıt sayısı (varsayılan: 20, maksimum: 100)

Yanıt:

{
  "success": true,
  "data": [HotspotUser],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

---

GET /api/v1/hotspot-users/:id

Tek bir hotspot kullanıcısının detaylarını getirir.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: read

Path Parametreleri:

• id (string): Kullanıcı ID

Query Parametreleri:

• venueId (string, opsiyonel): Venue ID

Yanıt:

{
  "success": true,
  "data": HotspotUser
}

---

POST /api/v1/hotspot-users

Yeni bir hotspot kullanıcısı oluşturur.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: write

Request Body:

{
  "name": "string (zorunlu)",
  "loginMethod": "username_password | guest (zorunlu)",
  "venueIds": ["string"] (zorunlu),
  "username": "string (username_password için zorunlu)",
  "password": "string (username_password için zorunlu)",
  "email": "string (opsiyonel)",
  "phone": "string (opsiyonel)",
  "macAddress": "string (opsiyonel)",
  "expiresAt": "string ISO 8601 (opsiyonel)",
  "metadata": "object (opsiyonel)"
}

Yanıt:

{
  "success": true,
  "message": "Hotspot kullanıcısı başarıyla oluşturuldu",
  "data": HotspotUser
}

---

PUT /api/v1/hotspot-users/:id

Mevcut bir hotspot kullanıcısını günceller.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: write

Path Parametreleri:

• id (string): Kullanıcı ID

Query Parametreleri:

• venueId (string, opsiyonel): Venue ID

Request Body: (Tüm alanlar opsiyonel)

{
  "name": "string",
  "username": "string",
  "email": "string",
  "phone": "string",
  "venueIds": ["string"],
  "expiresAt": "string ISO 8601 | null",
  "status": "active | blocked | expired",
  "metadata": "object"
}

Yanıt:

{
  "success": true,
  "message": "Kullanıcı başarıyla güncellendi",
  "data": HotspotUser
}

---

DELETE /api/v1/hotspot-users/:id

Belirtilen ID'ye sahip hotspot kullanıcısını siler.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: delete

Path Parametreleri:

• id (string): Kullanıcı ID

Query Parametreleri:

• venueId (string, opsiyonel): Venue ID

Yanıt:

{
  "success": true,
  "message": "Kullanıcı başarıyla silindi"
}

---

POST /api/v1/hotspot-users/:id/expire

Belirtilen kullanıcının aktif session'larını expire eder ve kullanıcıyı expired durumuna alır.

Kimlik Doğrulama: Gerekli (Bearer Token)
İzin: write

Path Parametreleri:

• id (string): Kullanıcı ID

Request Body (Opsiyonel):

{
  "venueId": "string"
}

Yanıt:

{
  "success": true,
  "message": "Kullanıcı ve session'lar başarıyla expire edildi",
  "data": {
    "expiredSessions": 3,
    "user": HotspotUser
  }
}

---

Veri Modelleri

HotspotUser

interface HotspotUser {
  _id: string;
  name: string;
  username?: string;
  email?: string;
  phone?: string;
  loginMethod: "username_password" | "guest" | "social" | "sms";
  venueIds: string[];
  status: "active" | "blocked" | "expired";
  expiresAt?: string; // ISO 8601
  devices: Device[];
  metadata: Record<string, any>;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

Device

interface Device {
  macAddress: string;
  name?: string;
  status: "active" | "expired";
  firstSeenAt: string; // ISO 8601
  lastSeenAt: string; // ISO 8601
}

Pagination

interface Pagination {
  page: number;
  limit: number;
  total: number;
  pages: number;
}

Error Response

interface ErrorResponse {
  success: false;
  message: string;
  errors?: Array<{
    field: string;
    message: string;
  }>;
}

HTTP Durum Kodları

Kod	Açıklama
200	OK - İstek başarılı
201	Created - Kaynak başarıyla oluşturuldu
400	Bad Request - Hatalı istek veya validasyon hatası
401	Unauthorized - Yetkilendirme hatası
403	Forbidden - İzin hatası
404	Not Found - Kaynak bulunamadı
500	Internal Server Error - Sunucu hatası

Hata Mesajları

400 Bad Request

{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "field": "username",
      "message": "Kullanıcı adı gereklidir"
    }
  ]
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthorized"
}

403 Forbidden

{
  "success": false,
  "message": "Forbidden"
}

404 Not Found

{
  "success": false,
  "message": "Kullanıcı bulunamadı"
}

500 Internal Server Error

{
  "success": false,
  "message": "Internal server error"
}

İlgili Dokümantasyon

• API v1 Giriş - Temel bilgiler ve başlangıç
• Kimlik Doğrulama - Token yönetimi
• Hotspot Kullanıcıları - Detaylı kullanım örnekleri