راهنمای API

هر کاری که در پنل می‌کنی، از راه API هم شدنی است. API روی پلن‌های پولی فعال است و کلیدت را از تنظیمات حساب برمی‌داری.

احراز هویت

کلید را در هدر Authorization بفرست:

curl https://linkest4.ir/api/links \
  -H "Authorization: Bearer lk_xxxxxxxxxxxx_..."

ساخت لینک

curl -X POST https://linkest4.ir/api/links \
  -H "Authorization: Bearer $LK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example.com/winter-sale",
    "slug": "yalda",
    "maxClicks": 5000,
    "expiresAt": "2027-01-20"
  }'

پاسخ موفق کد 201 دارد و لینک کوتاه و نشانی کد QR را برمی‌گرداند:

{
  "slug": "yalda",
  "short": "https://linkest4.ir/yalda",
  "qr": "https://linkest4.ir/qr/yalda",
  "clicks": 0
}

اگر نشانه قبلاً گرفته شده باشد پاسخ 409 است و هیچ چیزی تغییر نمی‌کند.

عوض کردن مقصد

نشانه‌ی کوتاه ثابت می‌ماند و فقط مقصد عوض می‌شود — یعنی هر کد QR که از قبل چاپ شده، از این به بعد به جای تازه می‌رود. فقط همان فیلدهایی که می‌فرستی تغییر می‌کنند:

curl -X PATCH https://linkest4.ir/api/links/yalda   -H "Authorization: Bearer $LK_KEY"   -H "Content-Type: application/json"   -d '{"url": "https://shop.example.com/nowruz-sale"}'

همه‌ی مسیرها

متد	مسیر	کار
POST	/api/links	ساخت لینک
GET	/api/links	فهرست لینک‌ها
GET	/api/links/{slug}	یک لینک
PATCH	/api/links/{slug}	ویرایش مقصد یا تنظیمات
DELETE	/api/links/{slug}	حذف لینک
GET	/api/stats/{slug}?days=30	آمار کلیک

کد QR

کد QR هر لینک روی /qr/{slug} است و به کلید نیاز ندارد. با پارامترها اندازه و رنگش را تنظیم کن:

پارامتر	پیش‌فرض	توضیح
scale	۸	پیکسل به ازای هر خانه (۱ تا ۲۴)
margin	۴	حاشیه‌ی سفید برحسب خانه
ec	M	تصحیح خطا: L، M، Q یا H
fg و bg	000000 / ffffff	رنگ خطوط و زمینه

برای چاپ، ec=H و scaleِ بزرگ بگذار؛ تصحیح خطای بالا استیکر خط‌وخش‌افتاده را هم نجات می‌دهد.

محدودیت‌ها

سقف تعداد لینک و طول تاریخچه‌ی آمار به پلنت بستگی دارد و در صفحه‌ی تعرفه نوشته شده. اگر با API حجم زیادی درخواست می‌فرستی، قبلش به ما خبر بده تا هماهنگ کنیم.