مستندات 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"
}
}پارامترهای ورودی
| پارامتر | نوع | توضیح |
|---|---|---|
| url | string | آدرس مقصد (الزامی) — معادل destinationUrl |
| destinationUrl | string | آدرس مقصد (جایگزین url) |
| slug | string | اسلاگ دلخواه (اختیاری) |
| domain | string | هاست دامنه کوتاهکننده (اختیاری) |
| expiresAt | ISO date | تاریخ انقضا (اختیاری) |
| maxClicks | number | حداکثر تعداد کلیک مجاز (اختیاری) |
| utmSource | string | پارامتر UTM source (اختیاری) |
| utmMedium | string | پارامتر UTM medium (اختیاری) |
| utmCampaign | string | پارامتر UTM campaign (اختیاری) |
| utmTerm | string | پارامتر UTM term (اختیاری) |
| utmContent | string | پارامتر UTM content (اختیاری) |
| iosUrl | string | ریدایرکت اختصاصی برای کاربران iOS (اختیاری) |
| androidUrl | string | ریدایرکت اختصاصی برای کاربران اندروید (اختیاری) |
محدودیت نرخ
هر کلید بهصورت پیشفرض ۱۲۰ درخواست در دقیقه دارد (قابل تنظیم). در صورت عبور، کد وضعیت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