مستندات API

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

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

۱. شروع سریع

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

توکن را از حساب کاربری بسازید یا بچرخانید.
پایه آدرس API: https://zqz.ir
ساخت لینک با POST؛ لیست و آمار با GET یا POST؛ حذف با POST یا DELETE.
پاسخ‌ها همیشه 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"
}

GET/POST لیست لینک‌ها

https://zqz.ir/api.php?action=list

لیست لینک‌های صاحب توکن. هدر Bearer الزامی است (توکن در query نیاید).

پارامترها

نام	نوع	توضیح
`action`	string	`list`
`limit`	int	۱ تا ۱۰۰ — پیش‌فرض ۵۰
`offset`	int	صفحه‌بندی — پیش‌فرض ۰

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://zqz.ir/api.php?action=list&limit=20"

GET/POST آمار لینک

https://zqz.ir/api.php?action=stats

آمار یک لینک متعلق به همان کاربر: کلیک کل، کشورها، ۱۴ روز اخیر.

نام	توضیح
`code`	کد کوتاه لینک
`id`	شناسه عددی لینک (جایگزین code)

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://zqz.ir/api.php?action=stats&code=abc123"

POST/DELETE حذف لینک

https://zqz.ir/api.php

حذف لینک متعلق به صاحب توکن.

curl -s -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete","code":"abc123"}' \
  "https://zqz.ir/api.php"

امنیت توکن

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

توکن را از صفحه حساب کاربری بسازید یا در صورت لو رفتن، «ساخت توکن جدید» بزنید تا قبلی باطل شود.
توکن ممکن است پس از مدتی منقضی شود؛ در آن صورت دوباره از حساب کاربری توکن تازه بگیرید.
بسته به تنظیمات حساب، ممکن است توکن فقط اجازه بعضی کارها را داشته باشد (مثلاً فقط ساخت لینک، یا لیست و آمار و حذف).
درخواست مستقیم از مرورگر سایت‌های دیگر ممکن است محدود باشد؛ فراخوانی از سرور، افزونه وردپرس یا اسکریپت بک‌اند معمولاً بدون مشکل کار می‌کند.

پیشنهاد: همیشه توکن را فقط در هدر Authorization: Bearer … بفرستید و هرگز در آدرس URL قرار ندهید.

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

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();