API Endpoint Listesi

Tüm endpoint'ler JWT authentication gerektirir (aksi belirtilmedikçe).

Auth

Method	Path	Açıklama	Auth
POST	/api/auth/login	Email/password ile giriş	Hayır
POST	/api/auth/refresh	Token yenileme	Hayır
GET	/api/auth/me	Mevcut kullanıcı profili	Evet

Users & Roles

Method	Path	Açıklama
GET	/api/users	Kiracı kullanıcıları
POST	/api/users	Yeni kullanıcı
GET/POST	/api/roles	Rol listele/oluştur

Regions & Subregions

Method	Path	Açıklama
GET/POST	/api/regions	Bölge listele/oluştur
GET/PUT/DELETE	/api/regions/{id}	Bölge detay/güncelle/sil
GET/POST	/api/subregions	Alt bölge listele/oluştur
GET/PUT/DELETE	/api/subregions/{id}	Alt bölge detay/güncelle/sil

Gateways

Method	Path	Açıklama
GET	/api/gateways	Gateway listesi
GET	/api/gateways/mqtt	Lightweight MQTT gateway listesi
POST	/api/gateways	Yeni gateway
PUT/DELETE	/api/gateways/{id}	Gateway güncelle/sil
POST	/api/gateways/{id}/rawconfig/sync	Raw config push
GET	/api/gateways/{id}/rawconfig/preview	Config önizleme

Devices

Method	Path	Açıklama
GET/POST	/api/devices	Cihaz listele/oluştur
GET/PUT/DELETE	/api/devices/{id}	Cihaz detay/güncelle/sil
GET	/api/devices/{id}/hierarchy	Cihaz ağacı
GET	/api/devices/{id}/children	Alt cihazlar
GET	/api/devices/{id}/energy-consumption	Enerji tüketimi
GET	/api/devices/device-templates	Template listesi
GET	/api/devices/device-templates/{id}	Template detay
GET	.../register-map/download	Register map indir
PUT	.../register-map	Register map yükle

Measurements

Method	Path	Açıklama
GET	/api/measurements/map-data	Harita snapshot
GET	/api/measurements/aggregated	Aggregated veri (hourly/daily/weekly/monthly)
GET	/api/measurements/reactive-ratio	Reaktif oran
POST	/api/measurements/export	CSV/Excel/PDF export

Alarms

Method	Path	Açıklama
GET/POST	/api/alarms	Alarm policy listele/oluştur
GET/PUT/DELETE	/api/alarms/{id}	Policy detay/güncelle/sil
GET	/api/alarms/incidents	Tetiklenen alarmlar
GET	/api/alarms/incidents/count	Aktif alarm sayıları
GET	/api/alarms/incidents/{id}	Alarm detay
POST	/api/alarms/incidents/{id}/ack	Alarm onayla
POST	/api/alarms/incidents/{id}/snooze	Alarm ertele
POST	/api/alarms/incidents/{id}/close	Alarm kapat
GET	/api/alarms/incidents/{id}/events	Alarm audit trail

Firmware & OTA

Method	Path	Açıklama
POST	/api/firmware/versions	Firmware upload
GET	/api/firmware/versions	Firmware listesi
GET	/api/firmware/versions/{id}	Firmware detay
GET	/api/firmware/versions/{id}/download	Firmware indir
PATCH	/api/firmware/versions/{id}	Metadata güncelle
POST	/api/firmware/versions/{id}/release	Release
POST	/api/firmware/versions/{id}/deprecate	Deprecated işaretle
POST	/api/ota/updates	Tekil OTA başlat
POST	/api/ota/updates/batch	Batch OTA
GET	/api/ota/updates	OTA listesi
GET	/api/ota/updates/{id}	OTA detay
POST	/api/ota/updates/{id}/cancel	OTA iptal
POST	/api/ota/updates/{id}/retry	OTA tekrar dene

LOTO

Method	Path	Açıklama
GET/POST	/api/loto/points	İzolasyon noktaları
GET/POST	/api/loto/sessions	LOTO oturumları
GET/PUT	/api/loto/sessions/{id}	Oturum detay/güncelle
POST	/api/loto/sessions/{id}/approve	Onayla
POST	/api/loto/sessions/{id}/reject	Reddet
POST	/api/loto/sessions/{id}/apply	Uygula
POST	/api/loto/sessions/{id}/release	Serbest bırak
POST	/api/loto/locks	Kilit uygula
DELETE	/api/loto/locks/{id}	Kilit kaldır

Zigbee

Method	Path	Açıklama
POST	/api/v1/zigbee/claims/generate	Claim code oluştur
GET	/api/v1/zigbee/claims/pending	Bekleyen claim'ler
DELETE	/api/v1/zigbee/claims/{id}	Claim iptal
GET	/api/v1/zigbee/gateways	Zigbee gateway'ler
GET/PUT/DELETE	/api/v1/zigbee/gateways/{id}	Gateway CRUD
GET	/api/v1/zigbee/gateways/{id}/devices	Gateway cihazları

Widgets

Method	Path	Açıklama
GET	/api/subregions/{id}/widgets	Widget listesi
POST	/api/widgets	Widget oluştur
PUT/DELETE	/api/widgets/{id}	Widget güncelle/sil

WebSocket

Protocol	Path	Açıklama
WS	/ws/telemetry?token=JWT&devices=id1,id2	Gerçek zamanlı ölçüm
GET	/ws/stats	Hub istatistikleri

Sistem

Method	Path	Açıklama	Auth
GET	/health	Sağlık kontrolü	Hayır
GET	/readiness	DB hazırlık	Hayır
GET	/api/config/public	Frontend config	Hayır
POST	/api/internal/gateway/connected	EMQX webhook	Hayır*
POST	/api/internal/gateway/disconnected	EMQX webhook	Hayır*

*Internal endpoint'ler firewall/network seviyesinde korunmalıdır.

---

API Kullanım Örnekleri

1. Auth Akışı (Login ve Authenticated Request)

Adım 1 — Giriş yaparak token al:

curl -X POST https://api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "operator@firma.com", "password": "GucluSifre123!"}'

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl...",
  "token_type": "bearer"
}

Adım 2 — Token ile authenticated request gönder:

curl -X GET https://api.example.com/api/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBl..."

2. POST /api/auth/login

Request:

{
  "email": "operator@firma.com",
  "password": "GucluSifre123!"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Response (401 Unauthorized):

{
  "detail": "E-posta veya şifre hatalı",
  "error_code": "INVALID_CREDENTIALS"
}

3. GET /api/devices

Request:

curl -X GET "https://api.example.com/api/devices?skip=0&limit=10&sort_by=name&sort_order=asc" \
  -H "Authorization: Bearer <access_token>"

Response (200 OK):

{
  "items": [
    {
      "id": "d1a2b3c4-...",
      "name": "Entes RG3-12CS #01",
      "device_type": "energy_analyzer",
      "gateway_id": "gw-uuid-...",
      "slave_id": 1,
      "template_id": "tpl-uuid-...",
      "is_online": true,
      "last_seen": "2026-04-07T12:30:00Z",
      "created_at": "2025-11-01T08:00:00Z"
    },
    {
      "id": "e5f6a7b8-...",
      "name": "Sofar HYD 5K",
      "device_type": "inverter",
      "gateway_id": "gw-uuid-...",
      "slave_id": 2,
      "template_id": "tpl-uuid-...",
      "is_online": false,
      "last_seen": "2026-04-07T11:15:00Z",
      "created_at": "2025-12-15T10:00:00Z"
    }
  ],
  "total": 24,
  "skip": 0,
  "limit": 10
}

4. GET /api/measurements/aggregated

Request:

curl -X GET "https://api.example.com/api/measurements/aggregated?device_id=d1a2b3c4-...&start=2026-04-01T00:00:00Z&end=2026-04-07T23:59:59Z&interval=daily" \
  -H "Authorization: Bearer <access_token>"

Response (200 OK):

{
  "device_id": "d1a2b3c4-...",
  "interval": "daily",
  "start": "2026-04-01T00:00:00Z",
  "end": "2026-04-07T23:59:59Z",
  "data": [
    {
      "timestamp": "2026-04-01T00:00:00Z",
      "voltage_avg": 231.4,
      "current_avg": 12.8,
      "power_avg": 2.96,
      "energy_kwh": 71.04,
      "power_factor_avg": 0.97
    },
    {
      "timestamp": "2026-04-02T00:00:00Z",
      "voltage_avg": 229.8,
      "current_avg": 13.1,
      "power_avg": 3.01,
      "energy_kwh": 72.24,
      "power_factor_avg": 0.96
    }
  ]
}

---

Error Model

Tüm API hataları aşağıdaki standart yapıda döner:

{
  "detail": "Hata mesajı açıklaması",
  "error_code": "HATA_KODU"
}

HTTP Durum Kodları

Kod	Ad	Açıklama	Örnek error_code
400	Bad Request	İstek gövdesi veya parametrelerde doğrulama hatası	VALIDATION_ERROR
401	Unauthorized	Token eksik, süresi dolmuş veya geçersiz	TOKEN_EXPIRED, INVALID_CREDENTIALS
403	Forbidden	Yetki yetersiz (rol/izin kontrolü)	PERMISSION_DENIED
404	Not Found	İstenen kaynak bulunamadı	RESOURCE_NOT_FOUND
409	Conflict	Kaynak çakışması (duplicate, state conflict)	DUPLICATE_ENTRY, STATE_CONFLICT
422	Unprocessable Entity	Sözdizimi doğru fakat iş mantığı kuralı ihlali	BUSINESS_RULE_VIOLATION
429	Too Many Requests	Rate limit aşıldı	RATE_LIMITED
500	Internal Server Error	Sunucu tarafı beklenmeyen hata	INTERNAL_ERROR

Doğrulama Hatası Detaylı Yapısı (422)

Pydantic doğrulama hataları FastAPI tarafından şu formatta döner:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

Pagination Kuralları

Tüm liste endpoint'leri (GET /api/devices, GET /api/alarms, vb.) ortak pagination parametreleri kullanır.

Query Parametreleri

Parametre	Tip	Varsayılan	Açıklama
skip	int	0	Atlanacak kayıt sayısı (offset)
limit	int	50	Döndürülecek maksimum kayıt (max: 200)
sort_by	string	created_at	Sıralama alanı
sort_order	string	desc	Sıralama yönü: asc veya desc

Response Yapısı

{
  "items": [ ... ],
  "total": 142,
  "skip": 0,
  "limit": 50
}

• items: Kayıt dizisi
• total: Filtrelere uyan toplam kayıt sayısı
• skip: Kullanılan offset değeri
• limit: Kullanılan limit değeri

Filtreleme

Alan bazlı filtreleme query parametreleri ile yapılır:

GET /api/devices?device_type=inverter&is_online=true
GET /api/alarms/incidents?severity=critical&status=active

Sıralama

GET /api/devices?sort_by=name&sort_order=asc
GET /api/alarms/incidents?sort_by=triggered_at&sort_order=desc

---

Rate Limiting

API istekleri Nginx seviyesinde rate limit ile korunmaktadır.

Endpoint Grubu	Limit	Açıklama
/api/auth/login, /api/auth/refresh	5 istek/dakika	Brute-force koruması
/api/* (genel)	30 istek/saniye	Genel API koruması

Aşım Durumunda

Rate limit aşıldığında HTTP 429 Too Many Requests döner:

{
  "detail": "Çok fazla istek gönderildi. Lütfen bekleyin.",
  "error_code": "RATE_LIMITED"
}

Retry-After header'ı ile beklenmesi gereken süre (saniye) belirtilir. Client tarafında bu header kontrol edilerek yeniden deneme stratejisi uygulanmalıdır.