Hız sınırı ve tekrar kuralları
siparis.app API isteklerini https://api.siparis.app/v1 adresine Bearer anahtarıyla gönderirsiniz. Okuma bütçesi API bağlantısı başına 60 saniyede 600 puandır. Anahtar döndürmek bütçeyi yenilemez. Her ucun x-read-cost değeri OpenAPI içindedir: çoğu tek kayıt 1, liste 2, desteklenen include toplam +1, dışa aktarma hazırlama 60 ve dosyasını indirme 5 puan; kargo fiyatı sorma, gönderi açma ve etiket indirme 10 puandır.
RateLimit başlığında r kalan puan, t pencerenin uzunluğudur (kayan pencere, saniye; bütçe dolduysa en geç bu kadar bekleyin). RateLimit-Policy içindeki q=600, w=60 puan ve saniye sınırını verir. Hatalı anahtar denemesi için ayrı IP sınırı 60 saniyede 30 denemedir; geçerli anahtarla yapılan istekler bu sayaçtan etkilenmez.
Kargo fiyat sorgusu için ayrıca işletme başına 60 saniyede 20 sorgu sınırı vardır; bütün API bağlantıları ve markalar ortak sayılır. Aşımda 429 quote_rate_limited ve beklenecek saniyeyi veren Retry-After döner. Gönderi açma ve panel/AI kargo işlemleri bu sayaca girmez. Fiyat sorgusundaki bakiye en çok 60 saniyelik önbellektendir; gönderi açılışında taze okunur.
Hangi isteği ne zaman tekrarlamalı?
| Durum | Davranış |
|---|---|
| 400, 401, 403, 404, 422 | Önce code ve errors alanlarına göre girdiyi/anahtarı/kapsamı düzeltin |
| 429 | Retry-After başlığındaki saniye kadar bekleyin; eşzamanlı istekleri azaltın |
| GET ağ hatası veya 5xx | Retry-After varsa en az o kadar; yoksa 1, 2, 4, 8… en çok 60 saniye artan bekleme ve rastgele gecikme; deneme sayısını sınırlayın |
| POST/PATCH ağ hatası veya 5xx | Sakladığınız aynı Idempotency-Key, yöntem, yol, gövde ve varsa If-Match ile tekrar deneyin |
| 409 idempotency_in_progress | Bekleyip aynı anahtar ve gövdeyle yeniden deneyin |
| 409 export_in_progress | İşletmedeki hazırlama bitene kadar bekleyin; yeni denemede yeni anahtar kullanın |
| Webhook oluşturma/döndürmede belirsiz sonuç | Aynı anahtarla tekrar durumunu okuyun; sır tekrar gösterilmez. Sır kaybolduysa uygun geçiş süresinde yeni anahtarla sır döndürün |
POST /v1/orders/{id}/shipments/quote yan etkisiz fiyat sorgusudur; tekrar anahtarı istemez, ağ hatasında okuma gibi yeniden sorulabilir. Gönderi açma/iptal 202 yanıtından sonra aynı shp_ kaydından izlenir; belirsiz sonuçta aynı anahtar ve gövde korunur. Kargoya vermek.
Tekrar anahtarı bütün API yazmalarında (POST, PATCH) zorunludur; sipariş, webhook ve dışa aktarma buna dahildir. En çok 200 karakterdir; yeni işte benzersiz değer, aynı işin tekrarında aynı değer kullanılır. Ad alanı API bağlantısıdır; anahtar döndürmek bunu değiştirmez. Aynı tekrar anahtarını farklı yöntem, yol, gövde veya If-Match ile kullanmak 422 idempotency_key_reused üretir.
Aynı Idempotency-Key ile tekrarlanan istek, ilk isteğin sonucunu (hata dahil) döndürür; yeni deneme için yeni anahtar kullanın. Kaydedilen 4xx iş hatası, koşullar sonradan düzelmiş olsa da aynı anahtarla tekrar verilir; yalnız hata kodu ve sabit açıklaması saklanır. İstek işleme alınmadan verilen kimlik, kapsam, giriş doğrulaması, hız sınırı ve idempotency_in_progress hataları makbuz oluşturmaz.
Tekrarda Idempotent-Replayed: true eklenir. Başarılı işlemin HTTP durumu ve Location başlığı korunur; yanıt gövdesi güncel kayıttan, bağlantının güncel kapsam ve maskelemesiyle üretilir. Siparişin ETag değeri güncel içerik özetidir. Kaynağa artık erişilemiyorsa 403/404 dönebilir. Yanıt gövdesi makbuzda tutulmaz; anonimleşmiş müşteri bilgisi geri gelmez. Webhook sırrı yalnız ilk oluşturma/döndürme yanıtında gösterilir, tekrar kaydında saklanmaz. Makbuzlar en az 30 gün korunur; 90 gün sonrası teknik temizlik ayrı işte yürütülür.
Olay okuyucusunda has_more=false sonrasında bekleme ekleyin; boş sayfa ile has_more=true ise ilerleyin. Çok işçide bütçeyi ortak yönetin, süresiz tekrar döngüsü kurmayın. Tekrarın ERP’de çift kayıt oluşturmaması için dış kaynak ve olay kimliklerini kalıcı tekilleştirin. Webhook alıcısının teslim tekrarları Webhook rehberinde açıklanır.