Entegrasyonu tahminle değil, sözleşmeyle kurun.

Kimlik doğrulama

Tenant her istekte açık olmalı

Paylaşılan API hostunda X-Tenant-Slug mağazayı seçer; erişim JWT’si Authorization: Bearer ile gönderilir. Access token 15 dakika geçerlidir. Refresh token yedi günlük oturuma bağlıdır ve yenilemede döndürülür. Üretim parolalarını istemci koduna, mobil pakete veya Git deposuna koymayın.

curl --request POST \
  'https://ticibu-api-staging.kolibu.workers.dev/auth/login' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Slug: YOUR_TENANT_SLUG' \
  --data '{"email":"developer@example.com","password":"••••••••"}'

curl --request POST \
  'https://ticibu-api-staging.kolibu.workers.dev/graphql' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Tenant-Slug: YOUR_TENANT_SLUG' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { webhookEventCatalog { name category } }"}'

Rate limit

Limiti yanıttan okuyun

Kotalı yüzeyler X-RateLimit-Limit ve X-RateLimit-Remaining döndürür. 429 yanıtında Retry-After saniyesine uyun. Aşağıdaki değerler bugün kodda uygulanan başlangıç bütçeleridir; sözleşmesel kapasite garantisi değildir.

Idempotency

Aynı niyet, aynı anahtar

• Anahtarı iş niyetinden üretin; ağ denemesi veya timestamp’ten üretmeyin.
• Aynı anahtarı farklı payload için yeniden kullanmayın.
• Diğer write mutasyonlarında belirsiz yanıttan sonra önce durumu okuyun; kör tekrar yapmayın.

Webhook

Ham gövdeyi imzadan önce değiştirmeyin

Ticibu JSON gövdesini HMAC-SHA256 ile imzalar. X-Ticibu-Signature değeri sha256=<hex> biçimindedir; ayrıca X-Ticibu-Event ve tekrarlar boyunca sabit kalan X-Ticibu-Delivery-Id gönderilir. Endpoint 10 saniye içinde 2xx dönmelidir. Teslimat en fazla beş kez denenir; tüketici delivery ID ile dedupe etmelidir. Aşağıdaki liste bugün dispatcher’a bağlı, fiilen yayımlanan olaylardır.

const rawBody = await request.text()
const received = request.headers.get('X-Ticibu-Signature')
const expected = 'sha256=' + hmacSha256Hex(WEBHOOK_SECRET, rawBody)

if (!timingSafeEqual(received, expected)) {
  return new Response('invalid signature', { status: 401 })
}

Pagination

Sayfa numarası ve opaque cursor ayrıdır

Klasik katalog uçları page ve limit kullanır. Değişen kataloğu ardışık okuyan agent feed, kayıp/tekrar riskini azaltmak için opaque keyset cursor döndürür. Cursor’ı çözümlemeyin veya üretmeyin; nextCursor boşalana kadar aynen taşıyın.

GET /cdn/v1/products?page=1&limit=24

{
  "products": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 24,
    "total": 132,
    "totalPages": 6
  }
}

GET /cdn/v1/agent-feed.json?limit=100&cursor=OPAQUE_CURSOR

Retry

Yalnız güvenli çağrıları otomatik tekrarlayın

Query/GET çağrılarında 429, 502, 503 ve 504 için jitter’lı exponential backoff uygulayın. 400/401/403/422 yanıtlarını tekrar etmeyin. Write çağrısını ancak mutasyon belgelenmiş bir idempotency anahtarı taşıyorsa otomatik tekrar edin.

async function ticibuRequest(url, init, attempt = 0) {
  const response = await fetch(url, init)
  if (![429, 502, 503, 504].includes(response.status) || attempt >= 4) return response

  const retryAfter = Number(response.headers.get('Retry-After'))
  const waitMs = Number.isFinite(retryAfter)
    ? retryAfter * 1000
    : Math.min(1000 * 2 ** attempt + Math.random() * 250, 8000)

  await new Promise(resolve => setTimeout(resolve, waitMs))
  return ticibuRequest(url, init, attempt + 1)
}

Sandbox fixtures

Gerçek müşteri verisi olmadan geliştirin

Aşağıdaki dosyalar sentetiktir ve sözleşme testi için sabit tutulur. Public katalog okumaları staging hostunda açıktır. Admin write sandbox tenant’ı ve kısa ömürlü giriş bilgileri yalnızca davet edilen entegrasyon ekibine güvenli kanaldan verilir; bu sayfada ortak parola yayınlanmaz. Fixture gövdeleri teslimatta gönderildiği haliyle verilir; event adı ve delivery ID HTTP header’larındadır.

App ve extension politikası

Önce izin sınırı, sonra SDK

Ticibu app platformu henüz self-service token veya mağaza kurulumu açmıyor. Hazır olan kısım; tenant sahipliği, granular scope sözlüğü, merchant grant sınırı, HTTPS redirect ve secret kurallarını machine-tested bir manifest politikasıyla sabitlemek. Write, müşteri verisi ve webhook erişimi insan güvenlik incelemesine gider.

Uygulama kurulum/OAuth uçları açılana kadar bu bir yayınlanmış güvenlik sözleşmesidir; çalışan app marketplace iddiası değildir.