hikiehikieDeveloper Documentation
Başlangıç

İ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-data kullanır.
  • Tanımsız JSON alanları 400 ile 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ğin 149.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 message Türkçedir ve değişebilir. HTTP durumuna ve errorCode'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ıkAnlamı
X-RateLimit-LimitBu anahtar için dakikada izin verilen istek
X-RateLimit-Remainingİçinde bulunulan dakikada kalan istek
X-RateLimit-ResetPencerenin sıfırlanacağı an, Unix saniyesi
Retry-AfterYalnı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 POST için zorunludur. Olmazsa 400 IDEMPOTENCY_KEY_REQUIRED alırsınız. PATCH ve DELETE iç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: true başlığı bulunur. Değişiklik yeniden uygulanmaz.
  • Aynı anahtarla farklı bir istek 422 IDEMPOTENCY_KEY_REUSED döner.
  • İlk istek hâlâ sürüyorsa tekrar 409 IDEMPOTENCY_IN_PROGRESS dö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 ve to o günün tamamını kapsar; ya da
  • Saat dilimli tam bir zaman, 2026-11-01T10:00:00Z ya da 2026-11-01T13:00:00+03:00. to tam o anı kapsar.

from, to'dan önce değilse istek 400 DATE_RANGE_INVALID ile başarısız olur.

Bu sayfada