Kısa bağlantılarınızın üzerine inşa edin

Hızlı başlangıç

1. Çalışma alanınızın API anahtarları sayfasında gizli bir API anahtarı oluşturun.
2. Anahtarı https://qoslink.cloud/api/v1 adresine bearer token olarak gönderin.
3. İlk bağlantınızı oluşturun:

curl -X POST https://qoslink.cloud/api/v1/links \
  -H "Authorization: Bearer ps_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://example.com/spring-sale", "alias": "spring"}'

Kapsamlar

Her anahtarın kapsamları vardır. Bir anahtar asla onu oluşturan üyenin rolünden fazlasını yapamaz.

• links.read Bağlantıları okuma
• links.write Bağlantı oluşturma, değiştirme ve silme
• qr.read QR kodlarını okuma
• qr.write QR kodu oluşturma, değiştirme ve silme
• bio.read Bio sayfalarını okuma
• bio.write Bio sayfası oluşturma, değiştirme ve silme
• analytics.read İstatistikleri okuma ve dışa aktarma
• analytics.write Bağlantı istatistiklerini sıfırlama
• conversions.write Dönüşüm kaydetme (sunucu tarafı)
• domains.read Alan adlarını okuma
• domains.write Alan adı ekleme, doğrulama ve kaldırma
• webhooks.read Webhook'ları ve gönderimleri okuma
• webhooks.write Webhook'ları ve Zapier aboneliklerini yönetme
• track Tarayıcıda dönüşüm takibi (yayınlanabilir anahtarlar)
• billing.read Planı, kullanımı, faturaları ve ödemeleri görüntüleme
• billing.write Ödeme başlatma, aboneliği iptal etme veya sürdürme, kupon kullanma
• members.read Ekip üyelerini ve davetleri görüntüleme
• members.write Ekip üyelerini davet etme, değiştirme ve çıkarma
• audit.read Çalışma alanı denetim kaydını görüntüleme

Hatalar ve hız sınırları

Hatalar, sabit ve makine tarafından okunabilir bir kod içeren tek bir yapıyla döner:

{"error": {"code": "insufficient_scope", "message": "...", "scope": "links.write"}}

Dakika başına istek sayısı planınıza bağlıdır; her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını içerir. Yeniden deneyebileceğiniz POST isteklerinde Idempotency-Key başlığını kullanın.

Webhook'lar

Olaylar uç noktanıza JSON olarak POST edilir:

{
  "id": "01JC5Z1Q9Y7J1K3M2N4P6R8T0V",
  "type": "link.created",
  "created_at": "2026-11-01T10:00:00.000Z",
  "workspace_id": 42,
  "data": { "id": 123, "alias": "spring", "short_url": "https://sho.rt/spring" }
}

İmzaları doğrulama

"<zaman damgası>.<ham gövde>" değerinin imzalama anahtarınızla HMAC-SHA256 özetini hesaplayıp v1 ile sabit sürede karşılaştırın; 5 dakikadan eski zaman damgalarını reddedin.

Shortener-Signature: t=1793527200,v1=5f2b...e9
Shortener-Event: link.created
Shortener-Delivery: 9812

$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_SHORTENER_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts);
$expected = hash_hmac('sha256', $parts['t'].'.'.$payload, $secret);
$valid = hash_equals($expected, $parts['v1'] ?? '') && abs(time() - (int) $parts['t']) <= 300;

const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) <= 300;

8 saniye içinde herhangi bir 2xx durumuyla yanıt verin. Başarısız gönderimler 1 dakika, 5 dakika, 30 dakika, 2, 6, 12 ve 24 saat sonra yeniden denenir; art arda 15 hatadan sonra webhook kapatılır. Tekrarları yok saymak için olay kimliğini kullanın.

Olaylar

Araçlar

POST https://qoslink.cloud/api/v1/hooks   {"target_url": "...", "event": "link.created"}
DELETE https://qoslink.cloud/api/v1/hooks/{id}
GET https://qoslink.cloud/api/v1/hooks/samples/link.created