وثائق REST API

البداية السريعة

1. احصل على مفتاح API من /account → API Keys
2. أرسل أول طلب باستخدام أحد الأمثلة أدناه
3. احصل على ردك بسرعة من Cloudflare Edge في جدة والرياض (≈ 20-40ms)

المصادقة

كل طلب يجب أن يحمل مفتاحك في رأس HTTP:

X-API-Key: zlk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

بديل: Authorization: Bearer zlk_...

Base URL

https://zaye.cc/api/v1

حدود المعدل

عند تجاوز الحد: 429 Too Many Requests. استخدم header X-RateLimit-Remaining

نقاط النهاية (Endpoints)

POST /api/v1/links

إنشاء رابط مختصر جديد.

الجسم (JSON):

{
  "url": "https://example.com/long-url",       // مطلوب
  "alias": "my-link",                           // اختياري — اسم مخصص
  "expires_at": "2026-06-01T00:00:00Z",         // اختياري
  "password": "secret123",                      // اختياري
  "tags": ["campaign-2026", "ramadan"],         // اختياري
  "utm": {                                       // اختياري — يُضاف للرابط
    "source": "newsletter",
    "medium": "email",
    "campaign": "ramadan"
  }
}

الرد (201):

{
  "ok": true,
  "data": {
    "id": "lnk_a1b2c3d4",
    "short_url": "https://zaye.cc/my-link",
    "long_url": "https://example.com/long-url",
    "created_at": "2026-05-19T11:30:00Z",
    "expires_at": "2026-06-01T00:00:00Z"
  }
}

GET /api/v1/links/:id

قراءة بيانات رابط معيَّن.

GET /api/v1/links

قائمة كل روابطك (مع pagination).

معاملات الاستعلام:

• page — افتراضي 1
• limit — افتراضي 20، أقصى 100
• tag — فلتر حسب وسم

PATCH /api/v1/links/:id

تحديث رابط (الوجهة، تاريخ الانتهاء، كلمة المرور، الوسوم).

DELETE /api/v1/links/:id

حذف رابط (soft delete — يمكن استعادته خلال 14 يوم).

GET /api/v1/links/:id/analytics

تحليلات تفصيلية لرابط.

الرد:

{
  "ok": true,
  "data": {
    "total_clicks": 1247,
    "unique_clicks": 892,
    "by_country": [
      { "code": "SA", "clicks": 850 },
      { "code": "AE", "clicks": 180 }
    ],
    "by_device": { "mobile": 920, "desktop": 280, "tablet": 47 },
    "by_referrer": [...],
    "by_day": [...],
    "by_hour": [...]
  }
}

أمثلة كاملة

cURL

curl -X POST https://zaye.cc/api/v1/links \
  -H "X-API-Key: zlk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/long", "alias": "promo"}'

JavaScript (Node / Browser)

const res = await fetch('https://zaye.cc/api/v1/links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ZLK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/long',
    alias: 'promo',
  }),
});
const { data } = await res.json();
console.log(data.short_url); // https://zaye.cc/promo

Python

import os, requests

res = requests.post(
    'https://zaye.cc/api/v1/links',
    headers={'X-API-Key': os.environ['ZLK_API_KEY']},
    json={'url': 'https://example.com/long', 'alias': 'promo'},
)
data = res.json()['data']
print(data['short_url'])  # https://zaye.cc/promo

PHP

$ch = curl_init('https://zaye.cc/api/v1/links');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: ' . getenv('ZLK_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://example.com/long',
    'alias' => 'promo',
  ]),
]);
$result = json_decode(curl_exec($ch), true);
echo $result['data']['short_url'];

رموز الخطأ

كل رد خطأ يحمل الصيغة:

{ "ok": false, "error": "Human readable AR/EN", "message_en": "English version", "code": "ERROR_CODE", "field": "optional" }

Webhooks (قريباً)

سنطلق webhooks للأحداث: نقرة على الرابط، انتهاء صلاحية، تجاوز الحد. سجّل اهتمامك من /contact.