یک درخواست، یک کد.
کد QR و بارکد را از داخل اپ خودتان بسازید و فایل آماده تحویل بگیرید.
اتصال به API سرور شما
آدرس پایه https://qr.example.com است. هدر Authorization: Bearer <API_KEY> را همراه درخواست بفرستید.
کلید را با openssl rand -hex 32 بسازید و در فایل /etc/ramzineh.env با نام RAMZINEH_API_KEY قرار دهید. همین مقدار را در سرور اپ مقصد تنظیم کنید. کلید را در کد عمومی اپ موبایل یا مرورگر قرار ندهید.
شروع سریع
این نمونه‌ها فایل خروجی را ذخیره می‌کنند. مقدار توکن را در محیط سرور خودتان تنظیم کنید.
export RAMZINEH_BASE_URL="https://qr.example.com"
# Set RAMZINEH_API_KEY in your server environment.
curl --fail-with-body "$RAMZINEH_BASE_URL/api/v1/qr" \
-H "Authorization: Bearer $RAMZINEH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data":"https://example.com","format":"png","size":1024}' \
--output qrcode.pngامتحان API
برای ارسال درخواست آزمایشی، کلید API خودتان را وارد کنید. کلید در حافظهٔ همین صفحه نگه داشته می‌شود.
آدرس‌ها و پارامترها
هر دو مسیر از GET و POST پشتیبانی می‌کنند. برای POST، هدر Content-Type: application/json لازم است. در GET، پارامترها را URL-encode کنید و برای دانلود، download=1 بفرستید.
POST /api/v1/qrPOST /api/v1/barcode| پارامتر | مقدار و پیش‌فرض | کاربرد |
|---|---|---|
data | متن؛ الزامی | محتوای خام کد، شامل لینک یا رشتهٔ Wi-Fi و vCard |
format | png | svg؛ پیش‌فرض png | فرمت تصویر خروجی |
response | binary | json؛ پیش‌فرض binary | فایل تصویر یا JSON حاوی dataUrl با کدگذاری Base64 |
size | ۱۲۸ تا ۲۰۴۸؛ پیش‌فرض ۱۰۲۴ | عرض و ارتفاع QR برحسب پیکسل؛ محتوای زیاد به اندازهٔ بزرگ‌تر نیاز دارد |
color | #153e35 | رنگ تیرهٔ شش‌رقمی روی زمینهٔ سفید؛ رنگ روشن رد می‌شود |
symbology | CODE128 | EAN13 | CODE39 | استاندارد بارکد؛ پیش‌فرض CODE128 |
scale | ۱ تا ۴؛ پیش‌فرض ۳ | عرض هر ماژول بارکد برحسب پیکسل |
height | ۴۰ تا ۳۰۰؛ پیش‌فرض ۱۰۰ | ارتفاع میله‌ها؛ تصویر نهایی ۳۲ پیکسل حاشیهٔ عمودی دارد |
download | true | false؛ پیش‌فرض false | در POST مقدار true، در GET مقدار 1 برای دانلود فایل |
محدودیت‌ها — بدنهٔ JSON حداکثر ۱۶ کیلوبایت. ظرفیت QR تا ۲۹۵۳ بایت برای ASCII و ۲۹۵۲ بایت برای محتوای UTF-8 است. تصحیح خطا با M آغاز می‌شود و برای محتوای حجیم به L تغییر می‌کند. بارکد حداکثر ۸۰ نویسه و عرض ۴۰۹۶ پیکسل دارد.
دادهٔ بارکد — Code 128 برای ASCII قابل چاپ، Code 39 برای حروف بزرگ انگلیسی، اعداد و نشانه‌های مجاز است. EAN-13 با ۱۲ رقم، رقم کنترل را محاسبه می‌کند و با ۱۳ رقم، آن را بررسی می‌کند. تصویر بارکد شامل میله‌هاست.
پاسخ JSON — فیلدهای type، format، contentType، width، height و dataUrl برمی‌گردند. از dataUrl برای نمایش یا ذخیرهٔ فایل استفاده کنید.
خطاها — کدهای 400 برای JSON نامعتبر، 413 برای حجم زیاد، 415 برای Content-Type، و 422 برای داده یا تنظیمات نامعتبر هستند. خطای برنامه قالب {"error":{"code":"...","message":"..."}} دارد. خطای 401 یعنی کلید API نامعتبر است و خطای 503 یعنی کلید سمت سرور تنظیم نشده است.
حریم خصوصی و اتصال — API محتوای درخواست را برای ساخت فایل دریافت می‌کند و آن را در پایگاه داده ذخیره نمی‌کند. از POST برای محتوای حساس استفاده کنید. برای اتصال از اپ‌های دیگر، درخواست را با کلید API از بک‌اند بفرستید.