REST API · v1

توثيق واجهة برمجة التطبيقات

اختصر الروابط، واحصل على التحليلات، وأدر الروابط برمجياً. جميع نقاط النهاية تُرجع JSON وتتطلب رمز Bearer.

احصل على وصول API مجاني

عنوان URL الأساسي: https://urlly.me/api/v1

POST

/api/v1/shorten

اختصار رابط

GET

/api/v1/stats/{hash}

جلب تحليلات الرابط

GET

/api/v1/links

عرض كل روابطك

—

domain_id param

استخدام نطاق مخصص

المصادقة

أرسل رمزك في ترويسة Authorization مع كل طلب

الترويسة	القيمة
Authorization	Bearer <token>
Accept	application/json
Content-Type	application/json (POST فقط)

أنشئ الرموز من إعدادات API. الرموز تظهر مرة واحدة فقط — احفظها بأمان. الرموز المفقودة أو غير الصحيحة تُعيد 401 Unauthorized.

bash

# Save your token in an environment variable
export URLLY_TOKEN="your_token_here"

# Include it in every request
curl https://urlly.me/api/v1/shorten \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

POST /api/v1/shorten 201 Created

اختصار رابط. يمكنك اختياريًا توفير اسم مستعار مخصص (3–20 حرفًا) ونطاق مخصص تم التحقق منه.

جسم الطلب

الحقل	النوع	مطلوب	ملاحظات
long_url	string	نعم	رابط صالح، بحد أقصى 2048 حرفًا
custom_alias	string	لا	[a-z0-9_-]، 3–20 حرفًا
domain_id	integer	لا	معرّف نطاق مخصص تم التحقق منه. احذفه لاستخدام النطاق الافتراضي.

الاستجابة

201 Created

{
  "success": true,
  "short_url": "https://urlly.me/my-link",
  "original_url": "https://example.com/...",
  "hash": "my-link",
  "created_at": "2026-03-19T10:00:00+00:00"
}

مثال على الطلب

bash

# Auto-generated short code
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url":"https://example.com/long-page"}'

# With custom alias
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "custom_alias": "my-link"
  }'

GET /api/v1/stats/{hash} 200 OK

تحليلات النقرات لرابط تمتلكه — إجمالي النقرات، التوزيع اليومي، تقسيم الأجهزة، أهم المتصفحات.

معامل URL

المعامل	الوصف
hash	الرمز المختصر أو الاسم المستعار المخصص للرابط

الاستجابة

200 OK

{
  "success": true,
  "hash": "aBcDeFg",
  "short_url": "https://urlly.me/aBcDeFg",
  "original_url": "https://example.com",
  "is_active": true,
  "stats": {
    "total_clicks": 142,
    "clicks_by_day": [
      { "date": "2026-03-19", "total": 108 }
    ],
    "devices": { "desktop": 80, "mobile": 62 },
    "browsers": { "Chrome": 95, "Safari": 47 }
  }
}

مثال على الطلب

bash

curl -X GET \
  "https://urlly.me/api/v1/stats/aBcDeFg" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

GET /api/v1/links 200 OK · Paginated

قائمة مُقسَّمة بكل روابطك، من الأحدث إلى الأقدم. 20 عنصرًا في الصفحة.

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

المعامل	الافتراضي	الوصف
page	1	رقم الصفحة

الاستجابة

200 OK

{
  "success": true,
  "data": [
    {
      "hash": "aBcDeFg",
      "short_url": "https://urlly.me/aBcDeFg",
      "original_url": "https://example.com",
      "clicks": 142,
      "is_active": true,
      "created_at": "2026-03-19T10:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 58
  }
}

مثال على الطلب

bash

# First page
curl -X GET \
  "https://urlly.me/api/v1/links" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

# Page 2
curl -X GET \
  "https://urlly.me/api/v1/links?page=2" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

النطاقات المخصصة

اعرض الروابط القصيرة من نطاقك الخاص بدلاً من النطاق الافتراضي

يمكن للمستخدمين المصادَق عليهم إضافة نطاقات مخصصة موثّقة. بعد التحقق، مرر domain_id إلى نقطة النهاية POST /shorten لإنشاء روابط قصيرة تحت ذلك النطاق.

كيفية الإعداد

1.اذهب إلى النطاقات المخصصة في لوحة التحكم وأضف نطاقك.
2.أضف سجل DNS CNAME يشير من نطاقك الفرعي إلى urlly.me.
3.أضف سجل التحقق TXT الموضح في لوحة التحكم، ثم انقر تحقق.
4.بعد التحقق، سجّل id النطاق ومرره كـ domain_id في استدعاءات API.

الرموز القصيرة فريدة لكل نطاق. يمكن أن يوجد نفس الاسم المستعار في نطاقك المخصص والنطاق الافتراضي في آنٍ واحد.

مثال: اختصار باستخدام نطاق مخصص

bash

# Shorten using your custom domain (id: 3)
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "domain_id": 3
  }'

# Response — short_url uses your domain
{
  "success": true,
  "short_url": "https://links.yourdomain.com/aBcDeFg",
  "original_url": "https://example.com/long-page",
  "hash": "aBcDeFg",
  "created_at": "2026-03-21T10:00:00+00:00"
}

تحديد معدل الطلبات

2000 طلبًا لكل 1 دقيقة لكل رمز

ترويسة الاستجابة	الوصف
X-RateLimit-Limit	الحد الأقصى للطلبات في النافذة الزمنية (2000)
X-RateLimit-Remaining	الطلبات المتبقية في النافذة الحالية
Retry-After	الثواني حتى إعادة تعيين النافذة (429 فقط)

عند التجاوز، تُعيد الطلبات 429 Too Many Requests. تحقق من Retry-After لمعرفة وقت إعادة المحاولة.

استجابة 429

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 0
Retry-After: 47

{
  "message": "Too Many Attempts."
}

رموز الأخطاء

جميع الأخطاء تُعيد JSON يحتوي على حقل message. أخطاء التحقق (422) تتضمن أيضًا كائن errors.

الحالة	المعنى	السبب الشائع
401	غير مصرح	رمز مفقود أو غير صالح
403	محظور	المورد لا ينتمي إليك
404	غير موجود	رمز الرابط المختصر غير موجود
422	خطأ في التحقق	حقول غير صالحة أو اسم مستعار مكرر
429	طلبات كثيرة جدًا	تجاوز حد معدل الطلبات
500	خطأ في الخادم	حدث خطأ من جانبنا

أمثلة على استجابات الأخطاء

JSON

# 401 Unauthorized
{ "message": "Unauthenticated." }

# 404 Not Found
{
  "error": "not_found",
  "message": "Link not found or does not belong to you."
}

# 422 Validation Error
{
  "message": "The long_url field is required.",
  "errors": {
    "long_url": [ "The long_url field is required." ]
  }
}

# 422 Unsafe URL
{
  "error": "unsafe_url",
  "message": "This URL has been flagged as unsafe."
}

جاهز للبناء؟

أنشئ رمزًا وأجرِ أول استدعاء API في ثوانٍ.

إنشاء حساب مجاني تسجيل الدخول