وثائق 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

حدود المعدل

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

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

POST /api/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": {
    "link": {
      "id": "a1b2c3d4...",
      "code": "my-link",
      "alias": "my-link",
      "original_url": "https://example.com/long-url",
      "is_active": 1,
      "clicks_total": 0,
      "created_at": "2026-05-19T11:30:00Z",
      "expires_at": "2026-06-01T00:00:00Z"
      // ... remaining zl_links columns
    }
  }
}

ملاحظة: لا يوجد حقل short_url جاهز — الرابط المختصر هو https://zaye.cc/ + code (أو alias إن وُجد).

GET /api/links/:id

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

GET /api/links

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

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

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

PATCH /api/links/:id

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

DELETE /api/links/:id

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

GET /api/links/:id/stats

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

الرد:

{
  "ok": true,
  "data": {
    "link": { "id": "...", "code": "promo", "clicks_total": 1247, ... },
    "total_clicks": 1247,
    "unique_clicks": 892,
    "clicks_by_day":      [ { "date": "2026-07-01", "clicks": 40 }, ... ],
    "clicks_by_hour":     [ { "hour": 14, "clicks": 12 }, ... ],
    "clicks_by_country":  [ { "country": "SA", "clicks": 850 }, ... ],
    "clicks_by_device":   [ { "device": "mobile", "clicks": 920 }, ... ],
    "clicks_by_platform": [ { "platform": "instagram", "clicks": 300 }, ... ],
    "peak_hour": 20
  }
}

أمثلة كاملة

cURL

curl -X POST https://zaye.cc/api/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/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('https://zaye.cc/' + data.link.code); // https://zaye.cc/promo

Python

import os, requests

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

PHP

$ch = curl_init('https://zaye.cc/api/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 'https://zaye.cc/' . $result['data']['link']['code'];

رموز الخطأ

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

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

Webhooks (قريباً)

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