REST API · v1

API ساخت کیو آر کد

با یک درخواست GET ساده، کیو آر کد دلخواه کاربر را بسازید و مستقیم تحویل دهید. نیازی به کلید API، ثبت‌نام یا دیتابیس نیست و هیچ داده‌ای ذخیره نمی‌شود.

GET https://qr.zeronex.ir/api.php
Quick start

شروع سریع

آدرس API را با پارامترهای دلخواه بسازید؛ پاسخ، خود فایل تصویر است و می‌توانید آن را مستقیم در تگ <img> استفاده کنید.

لینک ساده لینک ساده ?type=url&url=zeronex.ir&size=300 باز کردن
شماره تلفن · نقطه‌ای شماره تلفن · نقطه‌ای ?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">
Parameters

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

همه پارامترها اختیاری‌اند جز پارامترهای الزامی هر نوع. مقادیر را URL-encode کنید (برای متن فارسی ضروری است).

پارامترپیش‌فرضتوضیح
typetextنوع محتوا: text، url، sms، email، vcard، phone
data—متن خام برای کد شدن. اگر ارسال شود، type و فیلدهای آن نادیده گرفته می‌شوند.
formatpngفرمت خروجی: png، jpg، svg، pdf
size512ابعاد خروجی به پیکسل (۶۴ تا ۴۰۹۶). در PDF هر پیکسل = ۰٫۷۵ پوینت (۹۶ DPI).
margin2حاشیه سفید اطراف کد بر حسب ماژول (۰ تا ۲۰).
eccMسطح تصحیح خطا: L (۷٪)، M (۱۵٪)، Q (۲۵٪)، H (۳۰٪). اگر بدون افزایش نسخه ممکن باشد خودکار بالاتر می‌رود.
fg000000رنگ نقاط به‌صورت HEX (بدون #)، مثل 0B2E3B یا 333
bgFFFFFFرنگ پس‌زمینه به‌صورت HEX یا transparent (برای JPG سفید می‌شود).
eye= fgرنگ سه مربع گوشه (چشم‌ها).
stylesquareشکل نقاط: square، rounded، dots
eye_stylesquareشکل چشم‌ها: square، rounded، circle، leaf
logononebrand لوگوی ZERONEX را وسط کد قرار می‌دهد (ECC خودکار H). در POST می‌توانید فایل logo_file بفرستید.
logo_size22اندازه لوگو به درصد عرض کد (۱۰ تا ۳۰).
quality90کیفیت JPG (۱۰ تا ۱۰۰).
outputimageimage فایل خام برمی‌گرداند؛ json یک JSON شامل data_uri (Base64).
download0با 1 فایل به‌صورت دانلود (attachment) ارسال می‌شود.
filenameqrcode-{type}نام فایل دانلودی بدون پسوند (حروف لاتین، عدد، - و _).
Content types

پارامترهای هر نوع

بسته به مقدار 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 الزامی شماره برای تماس
Response

پاسخ

در حالت پیش‌فرض بدنه پاسخ خود فایل است با 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 برای همه دامنه‌ها باز است.
Errors

خطاها

در صورت خطا، پاسخ همیشه JSON است و کد وضعیت HTTP مناسب دارد:

HTTPcodeتوضیح
400 / 422missing_* · invalid_*پارامتر الزامی ارسال نشده یا مقدار آن نامعتبر است (مثل missing_url، invalid_email، invalid_param).
413data_too_longحجم اطلاعات بیش از ظرفیت کیو آر کد است (حداکثر حدود ۲۹۰۰ بایت در ECC=L).
413logo_too_largeفایل لوگو بیشتر از ۲ مگابایت است.
405method_not_allowedفقط GET و POST پشتیبانی می‌شوند.
500server_errorخطای داخلی سرور.
HTTP/1.1 422 Unprocessable Entity

{
  "ok": false,
  "error": {
    "code": "invalid_email",
    "message": "آدرس ایمیل معتبر نیست."
  }
}
Examples

نمونه کد

<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)
Playground

آزمایش زنده

یک آدرس API را ویرایش و اجرا کنید تا پاسخ را همین‌جا ببینید. می‌توانید از دکمه «کپی لینک API» در صفحه سازنده هم استفاده کنید.

برای دیدن پاسخ، «اجرا» را بزنید.