API Kuralları

FriSay Web API v1 için ortak kurallar: URL, JSON zarfı, hata biçimi, HTTP kodları, hız limiti, sayfalama ve alan takma adları.

Temel URL ve içerik tipi

Canlı: https://yoursite.com/api/v1/
Yerel örnek: http://localhost/fshop/api/v1/
İstek / yanıt: UTF-8 JSON
POST / PUT / PATCH gövdelerinde Content-Type: application/json gönderin
Kimlik doğrulama: X-API-Key (önerilen), Bearer veya ?api_key= — bkz. Kimlik Doğrulama

Üretim: Canlı ortamda her zaman HTTPS kullanın. API anahtarını istemci tarafı kodda asla ifşa etmeyin.

Başarı zarfı

Çoğu yanıt şu yapıya yakındır:

{
  "success": true,
  "data": { },
  "content": [ ],
  "message": "",
  "meta": { }
}

Sipariş listesi Trendyol benzeri alanlar da döndürebilir (totalElements, content[]). Ürün oluşturma gibi işlemlerde HTTP durumu 201 olabilir.

Hata gövdesi

{
  "success": false,
  "message": "Açıklayıcı hata metni"
}

HTTP durum kodları

Kod	Anlam
`200`	Başarılı
`201`	Oluşturuldu (ürün, görsel vb.)
`400`	Geçersiz istek
`403`	API kapalı veya geçersiz / yetkisiz anahtar
`404`	Kayıt bulunamadı
`405`	Yöntem desteklenmiyor
`422`	Doğrulama hatası
`429`	Hız limiti aşıldı
`503`	API anahtarı yapılandırılmamış / servis kullanılamıyor

Hız limiti

300 başarılı istek / 15 dakika / IP
Başarısız kimlik doğrulama kilidi: yaklaşık 30 başarısız deneme / 15 dakika

429 aldığınızda geri çekilip yeniden deneyin; anahtarı agresifçe denemeyin.

Sayfalama

Kritik:

Ürünler (GET /products): sayfa numarası 1 tabanlıdır (ilk sayfa page=1).
Siparişler, kategoriler, markalar: sayfa numarası 0 tabanlıdır (ilk sayfa page=0).

Yanlış tabanı kullanmak boş sayfa veya tekrarlayan kayıtlara yol açar.

`_method` geçersiz kılma

Bazı istemciler veya proxy'ler PUT / PATCH / DELETE gönderemez. Gerektiğinde POST gövdesinde veya form alanında _method=PUT, _method=PATCH veya _method=DELETE kullanarak gerçek HTTP yöntemini belirtebilirsiniz.

Alan takma adları

Özellikle kargo alanlarında hem camelCase hem snake_case kabul edilir:

cargoCompany / cargo_company
trackingNumber / tracking_number

Sipariş tarih filtrelerinde date_from / date_to veya milisaniye cinsinden startDate / endDate kullanılabilir.

Webhook yok

Web API v1 webhook göndermez. Yeni veya güncellenen siparişleri almak için siparişleri periyodik olarak sorgulayın (poll). Önerilen yaşam döngüsü için Sipariş Yaşam Döngüsü sayfasına bakın.

İlgili sayfalar

Başarılı yanıt (ürünler)

{
  "success": true,
  "data": [],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "pages": 1
  }
}

Hata yanıtı

{
  "success": false,
  "message": "Geçersiz API anahtarı"
}