Base API Dokümantasyonu (v3)

Lojimod API, RESTful mimariye dayalı, JSON formatında iletişim kuran bir web servisidir. Tüm isteklerinizde aşağıdaki standartlara uymanız gerekmektedir.

1. Authentication & Authorization

API güvenliği Client Secret ve JWT (JSON Web Token) tabanlı yetkilendirme ile sağlanır.

Client Secret

Tüm isteklerde (Auth gerektirmeyen uçlar dahil), uygulamanızı veya firmanızı tanımlayan x-client-secret header'ı gönderilmelidir. Bu değer size özel olarak tanımlanır.

x-client-secret: YOUR_CLIENT_SECRET_KEY

User Authorization (JWT)

Kullanıcı oturumu gerektiren uç noktalarda (çoğu endpoint), Authorize servisinden alınan access_token değeri Authorization header'ında Bearer şemasıyla gönderilmelidir.

Authorization: Bearer <access_token>

• Token Alma: /v3/authorize/verify-otp veya /v3/authorize/password uç noktaları ile alınır.
• Token Yenileme: Access token süresi dolduğunda, /v3/authorize/refresh-token ucu ile yeni bir access token alınabilir.

---

2. Idempotency (Tekrarlanan İstek Kontrolü)

Kritik işlem yapan POST ve PUT uç noktalarında (Örn: Sipariş oluşturma, Ödeme alma), ağ hataları veya timeout durumlarında işlemin mükerrer (iki kez) yapılmasını önlemek için Idempotency Key mekanizması kullanılır.

Bu uçlara istek atarken idempotency-key header'ı göndermelisiniz.

idempotency-key: benzersiz-bir-uuid-veya-string

• Eğer aynı idempotency-key ile 20 saniye içinde ikinci bir istek gelirse, sistem işlemi tekrar etmez ve önbellekteki hatayı veya başarılı sonucu döner (veya 400 hatası verebilir).
• Her yeni (farklı) işlem için yeni bir key üretilmelidir.
• Bir işlem hata (network error) alırsa, aynı key ile tekrar denenebilir (retry).

---

3. Response Structure (Yanıt Yapısı)

Tüm API yanıtları standart bir JSON zarfı (envelope) içinde döner.

Başarılı Yanıt

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Example"
    // ... endpoint'e özgü veriler
  },
  "error": null
}

Hatalı Yanıt

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Hata açıklaması"
  }
}

Yaygın HTTP Durum Kodları

• 200 OK: İşlem başarılı.
• 400 Bad Request: Geçersiz parametre veya validasyon hatası.
• 401 Unauthorized: Geçersiz token veya client secret.
• 403 Forbidden: Yetkisiz erişim (Yetki seviyesi yetersiz).
• 404 Not Found: Kaynak bulunamadı.
• 500 Internal Server Error: Sunucu hatası.

---

4. Query Parameters (Listeleme Parametreleri)

Liste dönen uç noktalar (List endpointleri) aşağıdaki standart sorgu parametrelerini kabul eder:

Sayfalama (page)

GET /resource?page[index]=0&page[size]=20

• page[index]: Sayfa numarası (0'dan başlar).
• page[size]: Sayfa başına kayıt sayısı.

Arama (search)

GET /resource?search=aranacak_metin

• Genellikle başlık, ad, soyad, telefon gibi ana alanlarda arama yapar.

Sıralama (sort)

GET /resource?sort[id]=created_at&sort[type]=desc

• sort[id]: Sıralanacak alan adı.
• sort[type]: asc (artan) veya desc (azalan).

Filtreleme (filter)

Her uç nokta kendine özgü filtreleri destekler.

GET /resource?filter[status]=active&filter[type]=delivery

• Birden fazla değer için (destekleyen alanlarda): ?filter[status]=active,pending veya parametre tekrarı ile gönderilebilir.

Derin Arama (deep_search)

İlişkili tablolarda arama yapmak için kullanılır.

GET /resource?deep_search[customer]=Ali

• Örn: Fatura listelerken müşteri adında arama yapmak için.

---

5. Tarih Formatları

Tüm tarih ve saat alanları aksi belirtilmedikçe ISO 8601 formatında veya YYYY-MM-DD (tarih) / HH:mm (saat) string formatlarında kullanılır.

• created_at: 2024-02-15T14:30:00.000Z
• issue_date: 2024-02-15
• start_time: 08:30