شروع سریع
اول از پنل کاربری وارد شو، برو بخش «دسترسی API» توی داشبورد و یه کلید بساز. کلید فقط همون یهبار کامل نشون داده میشه — جایی امن نگهش دار.
کلید API فقط برای کاربرهای پلن پایه و حرفهای فعاله. با پلن رایگان میتونی کلید بسازی، ولی
محدودیتهای همون پلن (تعداد لینک، کلیک ماهانه) رو داری.
آدرس پایه
https://k4l.ir/api/v1
احراز هویت
هر درخواست باید هدر زیر رو داشته باشه:
Authorization: Bearer YOUR_API_KEY
اگه کلید نامعتبر باشه یا نباشه، پاسخ 401 با این ساختار برمیگرده:
{
"ok": false,
"message": "کلید API نامعتبر یا وارد نشده — هدر Authorization: Bearer <کلید> رو بفرست"
}
ساخت لینک کوتاه
| Method | POST |
|---|---|
| Path | /api/v1/shortlinks |
بدنهی درخواست (JSON):
{
"main_url": "https://example.com/a-very-long-page",
"custom_slug": "my-link",
"expires_in": "30d",
"password": "",
"ios_link": "",
"android_link": ""
}
فقط main_url الزامیه. بقیه اختیاریان و بسته به پلنت اعمال میشن (اسلاگ دلخواه و انقضا از پلن پایه به بالا، رمز عبور فقط پلن حرفهای).
پاسخ موفق:
{
"ok": true,
"short": "https://k4l.ir/xR9mTq",
"short_url": "https://k4l.ir/xR9mTq"
}
مثال با curl:
curl -X POST https://k4l.ir/api/v1/shortlinks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"main_url":"https://example.com"}'
لیست لینکها
| Method | GET |
|---|---|
| Path | /api/v1/shortlinks |
curl https://k4l.ir/api/v1/shortlinks \
-H "Authorization: Bearer YOUR_API_KEY"
پاسخ:
{
"ok": true,
"links": [
{ "id": 12, "short_code": "xR9mTq", "main_url": "https://example.com", "clicks": 34, "created_at": "2026-08-01 10:00:00" }
]
}
حذف لینک
| Method | POST |
|---|---|
| Path | /api/v1/shortlinks/delete |
curl -X POST https://k4l.ir/api/v1/shortlinks/delete \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id": 12}'
آمار پیشرفته یک لینک
| Method | GET |
|---|---|
| Path | /api/v1/stats?id=12 |
فقط پلن حرفهای — روی پلنهای دیگه پیام «ارتقا بده» با
upgrade: true برمیگرده.{
"ok": true,
"stats": {
"daily": [{ "day": "2026-08-15", "cnt": 12 }],
"devices": [{ "device": "mobile", "cnt": 30 }],
"browsers": [{ "browser": "Chrome", "cnt": 25 }],
"countries": [{ "country": "ایران", "country_code": "IR", "cnt": 28 }]
}
}
محدودیتها و نکات مهم
- در حال حاضر Rate Limit سختگیرانهای اعمال نمیشه، ولی استفادهی غیرمتعارف میتونه باعث غیرفعال شدن کلید بشه.
- هر کاربر فقط یک کلید فعال داره — ساخت کلید جدید، کلید قبلی رو بیاثر میکنه.
- محدودیت تعداد لینک و کلیک ماهانهی پلنت، برای درخواستهای API هم دقیقاً مثل پنل اعمال میشه.