Limitler & Kotalar

Rate limit'ler (per-install)

• DEV sıkıdır (test ortamı): manuel test için yeterlidir — otomatik/yük testi yapma. PROD'da limitler boldur.
• Yetenek kovası ortaktır: tüm capability'ler (messaging.send/notify.staff/invoice.issue) install başına tek cap:<id> kovasını paylaşır — legacy /messaging/* ve jenerik /capabilities/* uçları AYNI kovaya sayılır (çift-yol kota bypass'ı yok). Sağlayıcının durum raporu (/status) da bu kovada.

// 429 → Retry-After'a uy; yoksa üstel backoff + jitter
async function callWithRetry(fn, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await fn();
    if (res.status !== 429 || attempt === maxAttempts) return res;
    const retryAfter = Number(res.headers.get('Retry-After')); // saniye — sunucunun söylediği süre
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : Math.min(30_000, 1000 * 2 ** (attempt - 1)) * (1 + Math.random() * 0.3); // fallback
    await new Promise((r) => setTimeout(r, waitMs));
  }
}

const res = await callWithRetry(() =>
  fetch(BASE + '/plugin-api/products/list', { headers: { Authorization: 'Bearer ' + apiKey } }),
);

Rate-limit yanıt başlıkları

Tüm /plugin-api/* yanıtları kota durumunu başlıklarla bildirir:

429 gövdesi: { success:false, message:"plugin.rateLimited" }.

• Yazma uçlarında başlıklar ayrı (ve daha sıkı) write kovasını yansıtır — okuma kotasından bağımsız.
• Başlıklar yoksa o istekte limit uygulanmadı demektir (geçici fail-open) — yanıltıcı sayı verilmez; istemcin başlıkların varlığına toleranslı olmalı.

Webhook teslimi (event'ler + lifecycle)

Endpoint'in hızlı + idempotent + imza-doğrulamalı olmalı. Yavaş/hatalı endpoint → retry → en sonunda teslim düşer. Bkz. /webhook alıcısı, imza şeması, lifecycle.

Senkron yanıt timeout'ları (action / hook)

Bu sürede { success, message, level, display } dön. Detay: Action ucu · Hook'lar.

Liste yanıtları & cap'ler

Çoğu liste ucunda sayfalama (cursor/offset) parametresi yoktur — uç, tüm listeyi tek yanıtta, uca özel bir üst sınıra (cap) kadar döner. İstisna: customers/list cursor sayfalaması kullanır (after/nextCursor, sayfa başına max 500):

• Tam senkron için listeyi pollama — listeyi bir kez çek + cache'le, sonra event'lerle güncel tut (product.*, category.*, user.* oluşturma/güncelleme/silmede gelir).
• Tekil kayıt için liste yerine */get?id= uçlarını kullan (API Genel Bakış).
• Parser'ını yeni alanlara toleranslı yaz — bkz. Versiyonlama & Deprecation.

Development store kotaları (yalnız DEV)

Özet — geliştirici kontrol listesi

• 429 → backoff + retry; dev'de testleri ölçülü tetikle (5/dk + 200/gün).
• Webhook endpoint'in: hızlı 2xx, imza doğrula, id ile idempotent.
• Action/hook: 8/5 sn içinde yanıt; geç = timeout/iptal.
• Dev store: 3 adet, 30 gün (login'de uzar), yalnız kendi eklentilerin.