İstekler ve sınırlar
İstek biçimi, istek sınırları, Idempotency-Key ile güvenli tekrar, tarihler, sayfalama ve tutarlar.
Biçim
- Temel adres:
https://api.hikie.space/v1. - JSON gönderin ve alın (
Content-Type: application/json). Tek istisna görsel yükleme:multipart/form-datakullanır. - Tanımsız JSON alanları
400ile reddedilir. Alan adındaki bir yazım hatası sessizce yok sayılmaz, hata verir. - Tutarlar Türk lirası cinsinden düz sayılardır (
"currency": "TRY"), örneğin149.9. Fiyatlar en çok iki ondalık içerir. - Yanıtlardaki zamanlar UTC ISO 8601 metnidir, örneğin
2026-11-02T09:15:00.000Z. - Hata yanıtındaki
messageTürkçedir ve değişebilir. HTTP durumuna veerrorCode'a göre dallanın.
İstek sınırı
Her anahtarın kendi sınırı vardır: anahtar oluşturulurken seçilen dakikada 1–200 istek (yeni anahtarlarda varsayılan 60). Pencere bir dakikadır. Her yanıt nerede olduğunuzu söyler:
| Başlık | Anlamı |
|---|---|
X-RateLimit-Limit | Bu anahtar için dakikada izin verilen istek |
X-RateLimit-Remaining | İçinde bulunulan dakikada kalan istek |
X-RateLimit-Reset | Pencerenin sıfırlanacağı an, Unix saniyesi |
Retry-After | Yalnızca 429'da: beklenecek saniye |
Sınırı aşarsanız 429 RATE_LIMIT_EXCEEDED alırsınız. Retry-After kadar
saniye bekleyin. Sürekli sorgulamak yerine sayfalayarak okuyun; yeni siparişleri
sipariş listesini tekrar tekrar çağırmak yerine webhook'larla
öğrenin.
Değişiklikleri güvenle tekrar etme
Zaman aşımına uğrayan bir istek uygulanmış da olabilir, uygulanmamış da. Çift ürün
riski olmadan tekrar edebilmek için her POST, PATCH ve DELETE isteğine
Idempotency-Key başlığı ekleyin:
curl -X POST https://api.hikie.space/v1/products \
-H "Authorization: Bearer hks_..." \
-H "Idempotency-Key: rehber-2026-11-001" \
-H "Content-Type: application/json" \
-d '{"name":"Lansman rehberi","price":149.9,"vatRate":20,"paymentType":"one-off","shipmentAdressCollected":false}'- İzinli bir anahtarla yapılan her
POSTiçin zorunludur. Olmazsa400 IDEMPOTENCY_KEY_REQUIREDalırsınız.PATCHveDELETEiçin ve eski anahtarda isteğe bağlıdır, ama yine de gönderin. - Her niyetlenen değişiklik için 1–255 karakterlik yeni bir değer kullanın. Rastgele bir UUID iyi çalışır. Değişiklik başına bir kez üretin ve yalnızca o değişikliği tekrar ederken yeniden kullanın.
- Aynı anahtar ve aynı istekle tekrar ederseniz ilk sonuç geri döner; yanıtta
Idempotent-Replay: truebaşlığı bulunur. Değişiklik yeniden uygulanmaz. - Aynı anahtarla farklı bir istek
422 IDEMPOTENCY_KEY_REUSEDdöner. - İlk istek hâlâ sürüyorsa tekrar
409 IDEMPOTENCY_IN_PROGRESSdöner. Birkaç saniye bekleyip yeniden gönderin. - Yalnızca başarılı sonuç saklanır. İlk deneme hata aldıysa aynı anahtarla tekrar isteği yeniden çalıştırır.
- Sonuçlar 24 saat saklanır ve isteği yapan anahtara aittir.
Sayfalama
Liste endpoint'leri page (1'den başlar) ve limit (1–100, varsayılan 20) alır ve
şunu döner:
{ "items": [], "total": 134, "page": 1, "limit": 20 }GET /products iki tür dijital ürünü (membership ve eski tip digital) birleştirir; bu yüzden
page × limit 5000'i aşamaz (400 PAGE_TOO_DEEP). O kadar derine sayfalamak
yerine bir filtreyle daraltın.
Tarihler
from ve to şunlardan birini kabul eder:
- Bir gün,
2026-11-01. Günler Türkiye saatine (UTC+3) göredir vetoo günün tamamını kapsar; ya da - Saat dilimli tam bir zaman,
2026-11-01T10:00:00Zya da2026-11-01T13:00:00+03:00.totam o anı kapsar.
from, to'dan önce değilse istek 400 DATE_RANGE_INVALID ile başarısız olur.