REST API · v1

واجهة API لأداة اختصار الروابط كوكلي

باستخدام REST API من كوكلي يمكنك إنشاء الروابط القصيرة وتعديلها والحصول على إحصاءات النقرات من داخل تطبيقك أو موقعك أو بوت تيليجرام أو نظام CRM الخاص بك. المخرجات بصيغة JSON والمصادقة بمفتاح API.

إنشاء مفتاح API الباقات التي تتضمن API OpenAPI (Swagger)

REST وJSON
طلبات واستجابات JSON قياسية عبر HTTPS؛ تعمل مع أي لغة برمجة.
صلاحيات قابلة للضبط
فعّل لكل مفتاح الصلاحيات اللازمة فقط (مثلاً القراءة فقط).
أمان المفتاح
تقييد عناوين IP وتاريخ الانتهاء والإبطال الفوري من لوحة التحكم.
الإحصاءات وQR
النقرات اليومية والدول والأجهزة وصورة QR لكل رابط عبر API.

البدء السريع

1
فعّل باقة تتضمن API
الوصول إلى API متاح في الباقات المعلَّمة بـ«الوصول إلى API» في صفحة الباقات.
2
أنشئ مفتاح API
انتقل إلى قسم «مفاتيح API» في لوحة التحكم واختر اسم المفتاح وصلاحياته. يُعرض المفتاح مرة واحدة فقط.
3
أرسل أول طلب
أرسل المفتاح في ترويسة Authorization: Bearer وأنشئ أول رابط قصير عبر POST /links.

أنشئ رابطًا قصيرًا بلغة البرمجة التي تفضّلها — العنوان الأساسي: https://kok.li/api/v1

curl -X POST https://kok.li/api/v1/links \
  -H "Authorization: Bearer kk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/very/long/url"}'

المصادقة

تتطلب جميع الطلبات (باستثناء صفحة التعريف وملف OpenAPI) مفتاح API. أرسل المفتاح في الترويسة Authorization: Bearer kk_live_… أو X-API-Key. احتفظ بالمفتاح على جانب الخادم فقط، ولا تضعه أبدًا في شيفرة المتصفح أو تطبيق الجوال.

يمكنك تحديد تاريخ انتهاء صلاحية وقائمة بعناوين IP المسموح بها (عنوان IP منفرد أو نطاق CIDR) لكل مفتاح.
يُرفض المفتاح المُبطَل أو المنتهي الصلاحية فورًا بخطأ 401.
يمكن لمدير الموقع تعطيل وصول مفتاح أو حساب في حال إساءة الاستخدام.

الصلاحيات (Scopes)

عند إنشاء المفتاح تحدد الأقسام التي يمكنه الوصول إليها. التزم بمبدأ «أقل صلاحية لازمة»؛ فمثلًا مفتاح لوحة التقارير يحتاج فقط إلى links:read و analytics:read.

Scope	الاستخدام	المسارات
`links:read`	قراءة الروابط	GET /links، GET /links/{code}
`links:write`	إنشاء الروابط وتعديلها	POST /links، POST /links/bulk، PATCH /links/{code}
`links:delete`	حذف الروابط	DELETE /links/{code}
`analytics:read`	عرض إحصاءات النقرات	GET /links/{code}/stats، GET /analytics
`qr:read`	الحصول على رمز QR	GET /links/{code}/qr
`account:read`	معلومات الحساب والاستهلاك	GET /me

مسارات API

جميع المسارات نسبية إلى https://kok.li/api/v1. الاستجابات بصيغة JSON والأوقات بصيغة ISO 8601 (UTC).

POST/api/v1/links

إنشاء رابط قصير

ينشئ رابطاً قصيراً جديداً. يُفحص عنوان الوجهة أمنياً قبل الإنشاء ويُخصم من الحصة الشهرية لباقتك.

الصلاحية المطلوبة: links:write

جسم JSON

`longUrl`مطلوب	string	عنوان الوجهة (http أو https)
`alias`	string	رمز مخصص من ٦ إلى ٣٢ حرفاً (أحرف إنجليزية وأرقام و- و_)
`utmSource / utmMedium / utmCampaign / utmTerm / utmContent`	string	معلمات تتبع الحملة التي تُضاف إلى عنوان الوجهة
`expireIn`	string	مدة الصلاحية: 1d أو 3d أو 7d أو 14d أو 30d أو 90d أو never
`expiresAt`	string	تاريخ الانتهاء بصيغة ISO 8601
`password`	string	كلمة مرور فتح الرابط

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

{
  "longUrl": "https://example.com/products/summer-sale",
  "alias": "summer-sale",
  "utmSource": "telegram",
  "expireIn": "30d"
}

مثال على الاستجابة

{
  "code": "summer-sale",
  "shortUrl": "https://kok.li/summer-sale",
  "longUrl": "https://example.com/products/summer-sale?utm_source=telegram",
  "clicks": 0,
  "scanStatus": "clean",
  "expiresAt": "2026-10-25T08:30:00.000Z",
  "createdAt": "2026-09-25T08:30:00.000Z"
}

POST/api/v1/links/bulk

إنشاء روابط دفعة واحدة

ينشئ حتى ٥٠ رابطاً في طلب واحد. لكل عنصر حقول «إنشاء رابط قصير» نفسها، وتُعاد نتيجة كل عنصر بشكل منفصل؛ فشل عنصر لا يمنع إنشاء البقية.

الصلاحية المطلوبة: links:write

جسم JSON

linksمطلوب array مصفوفة من ١ إلى ٥٠ كائناً بحقول إنشاء الرابط

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

{
  "links": [
    { "longUrl": "https://example.com/a" },
    { "longUrl": "https://example.com/b", "alias": "promo-b" }
  ]
}

مثال على الاستجابة

{
  "created": 1,
  "failed": 1,
  "results": [
    { "index": 0, "ok": true, "link": { "code": "x7Kp2q", "shortUrl": "https://kok.li/x7Kp2q" } },
    { "index": 1, "ok": false, "status": 409, "code": "alias_taken", "error": "هذا الرمز المخصص مستخدم مسبقاً." }
  ]
}

GET/api/v1/links

قائمة الروابط

يعيد روابط الحساب مرتبة من الأحدث مع ترقيم الصفحات.

الصلاحية المطلوبة: links:read

معاملات query

`page`	integer	رقم الصفحة (الافتراضي ١)
`limit`	integer	العدد في كل صفحة، بحد أقصى ١٠٠ (الافتراضي ٥٠)
`q`	string	البحث في عنوان الوجهة والرمز والوسوم
`status`	string	active \| paused \| archived \| blocked
`tag`	string	الروابط التي تحمل هذا الوسم فقط
`folder`	string	روابط هذا المجلد فقط

مثال على الاستجابة

{
  "links": [
    {
      "id": "66f3…",
      "code": "summer-sale",
      "shortUrl": "https://kok.li/summer-sale",
      "longUrl": "https://example.com/products/summer-sale",
      "clicks": 128,
      "status": "active",
      "tags": ["campaign"],
      "passwordProtected": false,
      "utm": { "source": "telegram", "medium": null, "campaign": null, "term": null, "content": null },
      "expiresAt": null,
      "createdAt": "2026-09-25T08:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}

GET/api/v1/links/{code}

الحصول على رابط

يعيد التفاصيل الكاملة لرابط (الوجهة والحالة وعدد النقرات والوسوم والانتهاء…).

الصلاحية المطلوبة: links:read

PATCH/api/v1/links/{code}

تعديل رابط

تتغير الحقول المرسلة فقط. يُقبل أسلوب PUT بالسلوك نفسه. لإزالة كلمة المرور أرسل password بقيمة null.

الصلاحية المطلوبة: links:write

جسم JSON

`longUrl`	string	عنوان وجهة جديد (يُفحص أمنياً مرة أخرى)
`tags`	string[]	الوسوم (بحد أقصى ٢٠)
`folder`	string \| null	المجلد
`maxClicks`	integer \| null	حد النقرات؛ يتوقف الرابط بعده
`fallbackUrl`	string \| null	عنوان بديل بعد الانتهاء أو الإيقاف
`password`	string \| null	كلمة مرور جديدة أو null لإزالتها
`expireIn / expiresAt`	string	تغيير وقت الانتهاء
`deviceTargets`	object	وجهة منفصلة لكل من ios وandroid وdesktop

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

{
  "tags": ["campaign", "autumn"],
  "maxClicks": 1000
}

DELETE/api/v1/links/{code}

حذف رابط

يحذف الرابط وجميع إحصاءات نقراته نهائياً.

الصلاحية المطلوبة: links:delete

مثال على الاستجابة

{ "ok": true }

GET/api/v1/links/{code}/stats

إحصاءات نقرات رابط

سلسلة يومية للنقرات والزوار الفريدين، ومجموع النطاق، ومقارنة بالنطاق السابق. وفي الباقات ذات الإحصاءات المتقدمة يتضمن breakdown أيضاً الدول والأجهزة والمتصفحات وأنظمة التشغيل ومصادر الإحالة.

الصلاحية المطلوبة: analytics:read

معاملات query

`range`	integer	7 \| 10 \| 14 \| 30 \| 90 \| 180 \| 365 يوماً (الافتراضي ١٠)
`from / to`	YYYY-MM-DD	نطاق مخصص بتوقيت إيران (بدلاً من range)

مثال على الاستجابة

{
  "link": { "code": "summer-sale", "shortUrl": "https://kok.li/summer-sale", "clicks": 128 },
  "range": 10,
  "from": "2026-09-16",
  "to": "2026-09-25",
  "daily": [{ "date": "2026-09-25", "label": "٢٥ سبتمبر", "clicks": 14, "uniques": 11 }],
  "totals": { "clicks": 128, "uniques": 97 },
  "totalsPrev": { "clicks": 90, "uniques": 70 },
  "breakdown": null
}

GET/api/v1/analytics

إحصاءات الحساب

نفس مخرجات إحصاءات الرابط ولكن لمجموع روابط الحساب كلها. يقبل range أو from/to.

الصلاحية المطلوبة: analytics:read

GET/api/v1/links/{code}/qr

صورة رمز QR

يعيد صورة PNG أو SVG لرمز QR الخاص بالرابط القصير (الاستجابة صورة وليست JSON).

الصلاحية المطلوبة: qr:read

معاملات query

`format`	string	png (الافتراضي) أو svg
`size`	integer	عرض الصورة بين ٦٤ و١٠٢٤ بكسل (الافتراضي ٣٢٠)
`color / bgColor`	hex	لون الرسم والخلفية، مثل 000000 وffffff
`margin`	integer	الهامش من ٠ إلى ١٠
`ecc`	string	مستوى تصحيح الخطأ: L أو M أو Q أو H

GET/api/v1/me

الحساب والمفتاح والاستهلاك

يعيد معلومات الحساب والباقة وصلاحيات المفتاح الحالي وحد معدّله واستهلاك الشهر الجاري.

الصلاحية المطلوبة: account:read

مثال على الاستجابة

{
  "user": { "id": "66f1…", "name": "أحمد" },
  "plan": { "tier": "pro", "label": "احترافية" },
  "key": { "prefix": "kk_live_3fa9c1", "scopes": ["links:read", "links:write"], "rateLimitPerMinute": 60 },
  "limits": { "maxKeys": 10, "maxLinks": -1, "monthlyLinkLimit": 1000 },
  "usage": { "period": "2026-09", "monthlyLinksCreated": 42, "totalLinks": 318 }
}

حدود المعدل والحصة

لكل مفتاح حدّ أقصى للطلبات في الدقيقة (60 افتراضيًا). يُعاد العدد المتبقي في الترويسات RateLimit-Limit، RateLimit-Remaining و RateLimit-Reset.
عند تجاوز الحد ستتلقى استجابة 429 بالرمز rate_limited؛ انتظر بضع ثوانٍ ثم أعد المحاولة.
تُحتسب الروابط المُنشأة عبر API من الحد الإجمالي والحصة الشهرية لباقتك.
يقبل الإنشاء الجماعي 50 رابطًا كحد أقصى في كل طلب.

الأخطاء

تتضمن استجابة الخطأ دائمًا رسالة مقروءة (بلغة ترويسة Accept-Language: الفارسية أو الإنجليزية أو العربية) في error ورمزًا إنجليزيًا ثابتًا في code؛ ابنِ منطق تطبيقك على أساس code.

{ "error": "مفتاح API هذا لا يملك الصلاحية «links:write».", "code": "insufficient_scope", "requiredScope": "links:write" }

الرمز	HTTP	المعنى
`missing_api_key`	401	لم يُرسل المفتاح في ترويسة Authorization أو X-API-Key.
`invalid_api_key`	401	المفتاح غير صالح أو تم إبطاله.
`key_expired`	401	انتهت صلاحية المفتاح؛ أنشئ مفتاحاً جديداً.
`key_disabled`	403	عطّل مدير الموقع المفتاح مؤقتاً.
`ip_not_allowed`	403	عنوان IP الخاص بك ليس ضمن العناوين المسموح بها لهذا المفتاح.
`api_access_denied`	403	باقتك أو حسابك لا يملك وصولاً إلى API (يوضح الحقل reason السبب).
`insufficient_scope`	403	المفتاح لا يملك الصلاحية اللازمة لهذا المسار (الحقل requiredScope).
`validation_error`	400	جسم الطلب غير صالح (يحدد الحقل field اسم الحقل المعني).
`not_found`	404	الرابط أو المسار غير موجود.
`alias_taken`	409	الرمز المخصص مستخدم مسبقاً.
`url_rejected`	422	رُفض عنوان الوجهة لأسباب أمنية.
`limit_reached`	403	بلغت الحد الإجمالي لروابط باقتك.
`quota_exceeded`	429	نفدت الحصة الشهرية لإنشاء الروابط في باقتك.
`rate_limited`	429	تجاوز عدد الطلبات في الدقيقة حد المفتاح.

الأسئلة الشائعة حول API

إجابات موجزة عن الأسئلة الشائعة للمطورين.

هل API كوكلي مجاني؟

الوصول إلى API متاح في الباقات المعلَّمة بـ«الوصول إلى API» في صفحة الباقات. وتُخصم الروابط التي تنشئها عبر API من حصة باقتك نفسها.

أين أنشئ مفتاح API وماذا أفعل إذا تسرّب؟

أنشئ المفاتيح من قسم «مفاتيح API» في لوحة التحكم. يُعرض المفتاح مرة واحدة ونحتفظ فقط بقيمة الهاش. إذا تسرّب المفتاح فأبطله من هناك وأنشئ مفتاحاً جديداً؛ يسري الإبطال فوراً.

ما حد معدل طلبات API؟

لكل مفتاح افتراضياً ٦٠ طلباً في الدقيقة. ويظهر الحد الدقيق لمفتاحك في استجابة GET /me وفي الترويستين RateLimit-Limit وRateLimit-Remaining لكل استجابة. وعند ظهور rate_limited انتظر قليلاً وأعد المحاولة.

كيف أقيّد صلاحيات مفتاح؟

عند إنشاء المفتاح أو تعديله اختر الصلاحيات اللازمة فقط (مثلاً links:read للتقارير فقط). ويمكنك أيضاً تقييد المفتاح بعناوين IP لخوادمك وتحديد تاريخ انتهاء له.

هل لديكم مواصفات OpenAPI (Swagger)؟

نعم. ملف OpenAPI 3 متاح على العنوان https://kok.li/api/v1/openapi.json ويمكن استيراده في Postman أو Insomnia أو Swagger UI.

هل أنت مستعد؟

أنشئ أول مفتاح API وأنشئ رابطًا قصيرًا في أقل من دقيقة.

الانتقال إلى مفاتيح API