← بازگشت به خانه

مستندات API

با استفاده از API می‌توانید از سایت‌ها و سرویس‌های خود (مثل پنل پیامکی) لینک کوتاه بسازید. ابتدا از بخش «کلیدهای API» در داشبورد یک کلید بسازید.

احراز هویت

کلید API را در هدر X-Api-Key یاAuthorization: Bearer ارسال کنید. هر کلید می‌تواند به یک دامنه خاص محدود شده باشد؛ در این صورت همه لینک‌ها روی همان دامنه ساخته می‌شوند.

آدرس پایه (Base URL): https://nxal.ir

ساخت لینک کوتاه

POST /api/v1/shorten

curl -X POST https://nxal.ir/api/v1/shorten \
  -H "X-Api-Key: nxal_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very/long/page",
    "slug": "promo",            // اختیاری — اسلاگ دلخواه
    "domain": "nx.al",          // اختیاری — انتخاب دامنه
    "expiresAt": "2026-12-31T00:00:00.000Z", // اختیاری
    "maxClicks": 1000,          // اختیاری
    "utmSource": "sms",         // اختیاری — پارامتر UTM
    "iosUrl": "https://apps.apple.com/...",  // اختیاری
    "androidUrl": "https://play.google.com/..." // اختیاری
  }'

پاسخ موفق:

{
  "success": true,
  "data": {
    "id": "clx...",
    "slug": "promo",
    "shortUrl": "https://nx.al/promo",
    "domain": "nx.al",
    "destinationUrl": "https://example.com/very/long/page"
  }
}

پارامترهای ورودی

پارامترنوعتوضیح
urlstringآدرس مقصد (الزامی) — معادل destinationUrl
destinationUrlstringآدرس مقصد (جایگزین url)
slugstringاسلاگ دلخواه (اختیاری)
domainstringهاست دامنه کوتاه‌کننده (اختیاری)
expiresAtISO dateتاریخ انقضا (اختیاری)
maxClicksnumberحداکثر تعداد کلیک مجاز (اختیاری)
utmSourcestringپارامتر UTM source (اختیاری)
utmMediumstringپارامتر UTM medium (اختیاری)
utmCampaignstringپارامتر UTM campaign (اختیاری)
utmTermstringپارامتر UTM term (اختیاری)
utmContentstringپارامتر UTM content (اختیاری)
iosUrlstringریدایرکت اختصاصی برای کاربران iOS (اختیاری)
androidUrlstringریدایرکت اختصاصی برای کاربران اندروید (اختیاری)

محدودیت نرخ

هر کلید به‌صورت پیش‌فرض ۱۲۰ درخواست در دقیقه دارد (قابل تنظیم). در صورت عبور، کد وضعیت429 برمی‌گردد.

پاسخ خطا

در صورت بروز خطا، پاسخ با کد وضعیت مناسب و ساختار زیر برمی‌گردد. کلیدsuccess برابرfalse و پیام خطا درerror قرار دارد.

{
  "success": false,
  "error": "این اسلاگ قبلاً استفاده شده است"
}
کدتوضیح
400ورودی نامعتبر (آدرس، اسلاگ یا دامنه)
401کلید API ارسال نشده یا نامعتبر است
409اسلاگ تکراری است
429عبور از محدودیت نرخ

دریافت آمار کلیک

همه‌ی کلیک‌ها به‌صورت خودکار توسط nxal ثبت می‌شوند (تعداد کل، یکتا، کشور، دستگاه، مرورگر، سیستم‌عامل و منبع ورود). برای دریافت آمار، از همان کلید API استفاده کنید.

GET /api/v1/links/{id} — خلاصه و شمارش کلیک یک لینک

curl https://nxal.ir/api/v1/links/clx123abc \
  -H "X-Api-Key: nxal_xxxxxxxxxxxx"

{ "success": true, "data": {
    "id": "clx123abc",
    "slug": "promo",
    "shortUrl": "https://nxal.ir/promo",
    "clicks": 1280,
    "uniqueClicks": 940,
    "lastClickedAt": "2026-06-27T10:11:12.000Z"
}}

GET /api/v1/links/{id}/stats?days=30 — آمار کامل و تفکیکی

{ "success": true, "data": {
    "totalClicks": 1280,
    "uniqueClicks": 940,
    "byDay":     [ { "date": "2026-06-27", "clicks": 64 } ],
    "byCountry": [ { "name": "IR", "count": 1100 } ],
    "byDevice":  [ { "name": "mobile", "count": 820 } ],
    "byBrowser": [ { "name": "Chrome", "count": 700 } ],
    "byOs":      [ { "name": "Android", "count": 610 } ],
    "byReferer": [ { "name": "instagram.com", "count": 300 } ]
}}

GET /api/v1/links?slug=promo — فهرست لینک‌های همین کلید (صفحه‌بندی با page و limit)

نکته: هنگام ساخت لینک با /api/v1/shorten مقدار data.id را ذخیره کنید تا بعداً آمار همان لینک را بگیرید.

برای دریافت کلید API وارد داشبورد شوید.

ساخت کلید API