API ساخت کیو آر کد
با یک درخواست GET ساده، کیو آر کد دلخواه کاربر را بسازید و مستقیم تحویل دهید. نیازی به کلید API، ثبتنام یا دیتابیس نیست و هیچ دادهای ذخیره نمیشود.
https://qr.zeronex.ir/api.php
شروع سریع
آدرس API را با پارامترهای دلخواه بسازید؛ پاسخ، خود فایل تصویر است و میتوانید آن را مستقیم در تگ <img> استفاده کنید.
?type=phone&phone=09123456789&style=dots&eye_style=circle&fg=0B2E3B&eye=1F8A8A&size=300
باز کردن
?type=url&url=zeronex.ir&style=rounded&eye_style=leaf&logo=brand&fg=0B2E3B&eye=1F8A8A&size=300
باز کردن
<img src="https://qr.zeronex.ir/api.php?type=url&url=example.com&size=300" alt="QR Code">
پارامترهای عمومی
همه پارامترها اختیاریاند جز پارامترهای الزامی هر نوع. مقادیر را URL-encode کنید (برای متن فارسی ضروری است).
| پارامتر | پیشفرض | توضیح |
|---|---|---|
type | text | نوع محتوا: text، url، sms، email، vcard، phone |
data | — | متن خام برای کد شدن. اگر ارسال شود، type و فیلدهای آن نادیده گرفته میشوند. |
format | png | فرمت خروجی: png، jpg، svg، pdf |
size | 512 | ابعاد خروجی به پیکسل (۶۴ تا ۴۰۹۶). در PDF هر پیکسل = ۰٫۷۵ پوینت (۹۶ DPI). |
margin | 2 | حاشیه سفید اطراف کد بر حسب ماژول (۰ تا ۲۰). |
ecc | M | سطح تصحیح خطا: L (۷٪)، M (۱۵٪)، Q (۲۵٪)، H (۳۰٪). اگر بدون افزایش نسخه ممکن باشد خودکار بالاتر میرود. |
fg | 000000 | رنگ نقاط بهصورت HEX (بدون #)، مثل 0B2E3B یا 333 |
bg | FFFFFF | رنگ پسزمینه بهصورت HEX یا transparent (برای JPG سفید میشود). |
eye | = fg | رنگ سه مربع گوشه (چشمها). |
style | square | شکل نقاط: square، rounded، dots |
eye_style | square | شکل چشمها: square، rounded، circle، leaf |
logo | none | brand لوگوی ZERONEX را وسط کد قرار میدهد (ECC خودکار H). در POST میتوانید فایل logo_file بفرستید. |
logo_size | 22 | اندازه لوگو به درصد عرض کد (۱۰ تا ۳۰). |
quality | 90 | کیفیت JPG (۱۰ تا ۱۰۰). |
output | image | image فایل خام برمیگرداند؛ json یک JSON شامل data_uri (Base64). |
download | 0 | با 1 فایل بهصورت دانلود (attachment) ارسال میشود. |
filename | qrcode-{type} | نام فایل دانلودی بدون پسوند (حروف لاتین، عدد، - و _). |
پارامترهای هر نوع
بسته به مقدار type، فیلدهای زیر را بفرستید. ارقام فارسی در شمارهها خودکار به لاتین تبدیل میشوند.
text |
الزامی | متن دلخواه (فارسی/انگلیسی) |
url |
الزامی | آدرس صفحه؛ بدون پروتکل، https:// اضافه میشود |
phone |
الزامی | شماره گیرنده |
message |
اختیاری | متن پیامک |
to |
الزامی | آدرس ایمیل گیرنده |
subject |
اختیاری | موضوع |
body |
اختیاری | متن ایمیل |
first_name |
الزامی | نام (یا org) |
last_name |
اختیاری | نام خانوادگی |
mobile |
الزامی | موبایل (یا work_phone / email) |
work_phone |
اختیاری | تلفن ثابت |
email |
اختیاری | ایمیل |
org |
اختیاری | سازمان |
title |
اختیاری | سمت |
website |
اختیاری | وبسایت |
address |
اختیاری | آدرس |
note |
اختیاری | یادداشت |
phone |
الزامی | شماره برای تماس |
پاسخ
در حالت پیشفرض بدنه پاسخ خود فایل است با Content-Type مناسب (image/png، image/jpeg، image/svg+xml، application/pdf). هدرهای X-QR-Version، X-QR-ECC و X-QR-Modules مشخصات کد را برمیگردانند. با output=json:
{
"ok": true,
"format": "png",
"mime": "image/png",
"size": 512,
"version": 2,
"ecc": "M",
"payload": "https://zeronex.ir",
"data_uri": "data:image/png;base64,iVBORw0KG..."
}
Cache-Control: no-store ارسال میشوند. CORS برای همه دامنهها باز است.
خطاها
در صورت خطا، پاسخ همیشه JSON است و کد وضعیت HTTP مناسب دارد:
| HTTP | code | توضیح |
|---|---|---|
400 / 422 | missing_* · invalid_* | پارامتر الزامی ارسال نشده یا مقدار آن نامعتبر است (مثل missing_url، invalid_email، invalid_param). |
413 | data_too_long | حجم اطلاعات بیش از ظرفیت کیو آر کد است (حداکثر حدود ۲۹۰۰ بایت در ECC=L). |
413 | logo_too_large | فایل لوگو بیشتر از ۲ مگابایت است. |
405 | method_not_allowed | فقط GET و POST پشتیبانی میشوند. |
500 | server_error | خطای داخلی سرور. |
HTTP/1.1 422 Unprocessable Entity
{
"ok": false,
"error": {
"code": "invalid_email",
"message": "آدرس ایمیل معتبر نیست."
}
}
نمونه کد
<img src="https://qr.zeronex.ir/api.php?type=url&url=example.com&size=300" alt="QR Code">
curl -o qrcode.png "https://qr.zeronex.ir/api.php?type=url&url=example.com&size=1024"
# PDF چاپی با رنگ دلخواه
curl -o qrcode.pdf "https://qr.zeronex.ir/api.php?type=text&text=Hello&format=pdf&fg=0B2E3B"
# آپلود لوگوی دلخواه (POST)
curl -o qrcode.png -F type=url -F url=example.com -F logo_file=@logo.png "https://qr.zeronex.ir/api.php"
<?php
$params = [
'type' => 'vcard',
'first_name' => 'Sara',
'last_name' => 'Ahmadi',
'mobile' => '09123456789',
'format' => 'png',
'size' => 1024,
];
$png = file_get_contents('https://qr.zeronex.ir/api.php?' . http_build_query($params));
file_put_contents('contact.png', $png);
const params = new URLSearchParams({
type: 'email',
to: 'info@example.com',
subject: 'سلام',
output: 'json',
});
const res = await fetch('https://qr.zeronex.ir/api.php?' + params);
const json = await res.json();
if (json.ok) {
document.querySelector('#qr').src = json.data_uri;
} else {
console.error(json.error.code, json.error.message);
}
import requests
r = requests.get('https://qr.zeronex.ir/api.php', params={
'type': 'sms',
'phone': '09123456789',
'message': 'Hello',
'format': 'svg',
})
r.raise_for_status()
open('sms.svg', 'wb').write(r.content)
آزمایش زنده
یک آدرس API را ویرایش و اجرا کنید تا پاسخ را همینجا ببینید. میتوانید از دکمه «کپی لینک API» در صفحه سازنده هم استفاده کنید.