شعار Zagl

توثيق API

اختصر الروابط مباشرة من كودك. نقطة نهاية واحدة ورمز bearer واحد.

نقطة النهاية

POSThttps://za.gl/api/shorten
RESTجسم JSONمصادقة Bearer

المصادقة

مرّر رمز API الخاص بك في ترويسة Authorization كرمز bearer. احصل عليه من لوحة حسابك بعد إنشاء أول رابط لك.

الترويسة
Authorization: Bearer YOUR_API_TOKEN

لا تملك رمزًا بعد؟ يمكنك استدعاء نقطة النهاية بدونه. ينشئ Za.gl حسابًا مجهولًا فورًا ويعيد رمزًا جديدًا في data.newAuthToken. احفظه لإدارة روابطك لاحقًا.

جسم الطلب

originalUrlمطلوب

string

الرابط الطويل المراد اختصاره. إذا أغفلت البروتوكول تُضاف https:// تلقائيًا.

customAlias

string

نهايتك الخاصة، مثل za.gl/my-link. يجب أن تكون فريدة، وإلا ستحصل على 409.

password

string

احمِ الرابط بحيث يحتاج الزوار إلى كلمة مرور للمتابعة.

expiresAt

string (ISO date)

متى يتوقف الرابط عن العمل. يجب أن يكون في المستقبل.

expiresInMinutes / expiresInHours / expiresInDays

number

بديل عن expiresAt، ينتهي بعد مدة زمنية نسبية.

waitTimer

number (0-300)

عدد الثواني التي ينتظرها الزائر في صفحة المعاينة قبل إعادة التوجيه.

customGtmId

string

معرّف Google Tag Manager الخاص بك (GTM-XXXXXXX) يُطلق في صفحة المعاينة.

title / description

string

بيانات وصفية اختيارية تُحفظ مع الرابط.

generateQR

boolean

أعد أيضًا رمز QR للرابط القصير.

مثال طلب

POSTcURL
curl -X POST https://za.gl/api/shorten \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://example.com/a-very-long-link",
    "customAlias": "my-link",
    "password": "optional-secret",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "waitTimer": 5
  }'

مثال استجابة

الاستدعاء الناجح يعيد 200 OK مع الرابط القصير في data.shortUrl.

200 OKJSON
{
  "success": true,
  "message": "URL shortened successfully",
  "data": {
    "id": "123",
    "alias": "my-link",
    "shortUrl": "https://za.gl/my-link",
    "originalUrl": "https://example.com/a-very-long-link",
    "customAlias": "my-link",
    "domain": "za.gl",
    "title": "",
    "description": null,
    "hasPassword": true,
    "isActive": true,
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "hits": 0,
    "waitTimer": 5,
    "created": "2026-06-25T10:00:00.000Z",
    "modified": "2026-06-25T10:00:00.000Z",
    "authToken": "your-account-token"
  }
}

حدود المعدل والأخطاء

10 req/minحتى 10 طلبات في الدقيقة لكل عميل.
409الاسم المخصص محجوز بالفعل.
400رابط غير صالح أو تاريخ انتهاء في الماضي.
429تجاوزت حد المعدل أو حصتك الشهرية.