مستندات API

با API رسمی zqz.ir می‌توانید از برنامه، ربات یا افزونه وردپرس لینک کوتاه بسازید — بدون ورود دستی به پنل.

شروع سریع احراز هویت ورود و توکن ساخت لینک خطاها محدودیت‌ها نمونه کد

۱. شروع سریع

برای استفاده از API به یک حساب فعال در zqz.ir و توکن API نیاز دارید.

توکن را از حساب کاربری بسازید یا بچرخانید.
پایه آدرس API: https://zqz.ir
همه درخواست‌های عملیاتی فقط با متد POST هستند.
پاسخ‌ها همیشه JSON و با کدگذاری UTF-8 هستند.

پیشنهاد: توکن را فقط در هدر Authorization: Bearer … بفرستید. ارسال توکن در query string (آدرس URL) مجاز نیست.

۲. احراز هویت

پس از داشتن توکن، یکی از این روش‌ها را برای ساخت لینک استفاده کنید:

روش	توضیح
هدر Bearer پیشنهادی	`Authorization: Bearer YOUR_TOKEN`
فیلد POST	`token=YOUR_TOKEN` در بدنه form-urlencoded
بدنه JSON	`{"token":"YOUR_TOKEN", "url":"..."}`

توکن مثل رمز عبور است. آن را عمومی نکنید. در صورت لو رفتن، از حساب کاربری «ساخت توکن جدید» را بزنید تا توکن قبلی باطل شود.

POST ورود و دریافت توکن

https://zqz.ir/api-login.php

با نام کاربری و رمز حساب، توکن API را می‌گیرید. اگر هنوز توکن نداشته باشید، سامانه یکی می‌سازد.

پارامترها

نام	نوع	الزامی	توضیح
`username`	string	بله	نام کاربری ورود
`password`	string	بله	رمز عبور حساب

نمونه پاسخ موفق

{
  "success": true,
  "token": "a1b2c3…",
  "username": "myuser"
}

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

https://zqz.ir/api.php

یک URL بلند را به لینک کوتاه تبدیل می‌کند. سقف روزانه ساخت لینک حساب شما اعمال می‌شود.

پارامترها

نام	نوع	الزامی	توضیح
`url`	string	بله	آدرس مقصد (با یا بدون https)
`token`	string	*	اگر هدر Bearer نباشد، در بدنه الزامی است
`custom`	string	خیر	کد دلخواه ۳ تا ۳۰ کاراکتر: حروف، عدد، `-` و `_`
`title`	string	خیر	عنوان نمایشی لینک در پنل

نمونه پاسخ موفق

{
  "success": true,
  "short_code": "abc123",
  "short_url": "https://zqz.ir/abc123",
  "original_url": "https://example.com/page"
}

۳. کدهای وضعیت و خطا

HTTP	معنی رایج
200	موفق
400	درخواست نامعتبر (مثلاً توکن در GET یا URL خراب)
401	توکن خالی یا نامعتبر / ورود ناموفق
403	لینک مسدود یا غیراخلاقی
405	متد غیر از POST
429	سقف نرخ درخواست یا سقف روزانه لینک
500	خطای داخلی سرور

بدنه خطا معمولاً به این شکل است:

{
  "success": false,
  "error": "پیام خطا به فارسی"
}

۴. محدودیت‌ها و قوانین

محدودیت نرخ بر اساس IP و کاربر برای جلوگیری از سوءاستفاده
سقف روزانه تعداد لینک ساخته‌شده (قابل تنظیم توسط مدیریت برای هر کاربر)
لینک‌های نامعتبر یا غیراخلاقی پذیرفته نمی‌شوند
کد دلخواه تکراری یا خارج از الگوی مجاز رد می‌شود
استفاده از API تابع شرایط استفاده سایت است

۵. نمونه کد

cURL — ساخت لینک

curl -X POST "https://zqz.ir/api.php" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "url=https://example.com&title=Demo"

cURL — ورود

curl -X POST "https://zqz.ir/api-login.php" \
  -H "Content-Type: application/json" \
  -d '{"username":"myuser","password":"secret"}'

PHP

$ch = curl_init('https://zqz.ir/api.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
  ],
  CURLOPT_POSTFIELDS => http_build_query([
    'url'   => 'https://example.com',
    'title' => 'نمونه',
  ]),
]);
$res = json_decode(curl_exec($ch), true);

JavaScript (fetch)

const res = await fetch('https://zqz.ir/api.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({ url: 'https://example.com' }),
});
const data = await res.json();