أدِر رموزك من نظامك الخاص.
أنشئ مئات رموز QR في طلب واحد، وحدّث وجهاتها، واسحب تقارير المسح إلى لوحتك الخاصة. كل ما يلزم: REST وJSON ومفتاح API.
مسودة — ستُعتمد نقاط النهاية أثناء التطوير. تعرض هذه الصفحة البنية المقترحة؛ لا توجد واجهة API فعلية بعد. قد تتغير العناوين وأسماء الحقول والحدود وصيغ الاستجابة.
- عنوان URL الأساسي
https://api.oqur.io/v1- الصيغة
- JSON، UTF-8، HTTPS
- المصادقة
- مفتاح API من نوع Bearer
- الباقات
- الأعمال والمؤسسات
البدء
تتيح لك واجهة oqur البرمجية أن تفعل من برنامجك ما تفعله في اللوحة: إنشاء رموز QR بالجملة، وتحديث الوجهات، وتنزيل ملفات الطباعة، وتقارير المسح. كل طلب يمر عبر HTTPS بجسم JSON.
أنشئ مفتاحًا
أنشئ مفتاحًا في قسم مفاتيح API من قائمة الإعدادات في اللوحة واختر نطاقاته. حين تجهز الواجهة ستُتاح في باقتي الأعمال والمؤسسات.
أرسل طلبك الأول
المثال المجاور يسرد أول رمز في حسابك. إذا كانت الاستجابة 200 فكل شيء جاهز.
راقب الحدود
طلباتك المتبقية في ترويسات كل استجابة. والتفاصيل في قسم حدود المعدل.
القواعد
| الموضوع | الصيغة | الوصف |
|---|---|---|
| التاريخ والوقت | ISO 8601 |
تُعاد دائمًا بتوقيت UTC: 2026-09-30T09:12:44Z. وفي التقارير يمكنك اختيار المنطقة الزمنية التي تريدها. |
| المعرّفات | string |
نص ببادئة: رموز QR تبدأ بـ qr_، والمجلدات بـ fld_، والطلبات بـ req_. |
| ترقيم الصفحات | integer |
بـ page وper_page. 100 سجل على الأكثر في الصفحة. |
| الإصدار | v1 |
الإصدار في العنوان. التغييرات غير المتوافقة مع السابق تأتي فقط مع إصدار جديد. |
curl "https://api.oqur.io/v1/qr-codes?per_page=1" \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Accept: application/json"
<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;
$oqur = new Client([
'base_uri' => 'https://api.oqur.io/v1/',
'headers' => [
'Authorization' => 'Bearer ' . getenv('OQUR_API_KEY'),
'Accept' => 'application/json',
],
]);
$res = $oqur->get('qr-codes', ['query' => ['per_page' => 1]]);
$body = json_decode($res->getBody(), true);
// Node 18+ أو بيئات أخرى خارج المتصفح
const oqur = (path, init = {}) =>
fetch(`https://api.oqur.io/v1${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.OQUR_API_KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
...init.headers,
},
}).then((r) => r.json());
const body = await oqur('/qr-codes?per_page=1');
الاستجابة 200 مثال
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "menu",
"name": "Kafe Rıhtım · بطاقة طاولة",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"created_at": "2026-09-12T08:30:00Z"
}
],
"meta": { "page": 1, "per_page": 1, "total": 42 }
}
المصادقة
أضف مفتاح API إلى كل طلب في الترويسة Authorization. الطلبات بلا مفتاح أو بمفتاح غير صالح تعيد 401؛ والمفاتيح التي تفتقر إلى الصلاحية الكافية تعيد 403.
- استخدم المفتاح على جانب الخادم فقط؛ لا تضمّنه في متصفح أو تطبيق جوال.
- أنشئ مفتاحًا منفصلًا لكل تكامل. إذا تسرّب أحدها، تلغي ذلك المفتاح وحده.
- امنح المفتاح النطاقات التي يحتاجها فقط:
qr:read,qr:write,analytics:read,folders:write.
الترويسات
| الترويسة | النوع | الوصف |
|---|---|---|
Authorizationمطلوب |
string |
Bearer متبوعًا بمفتاح API الخاص بك. |
Content-Type |
string |
application/json في الطلبات التي لها جسم. |
Accept |
string |
application/json. |
Idempotency-Key |
string |
قيمة فريدة لإعادة محاولة طلبات الإنشاء بأمان. الطلب بالمفتاح نفسه خلال 24 ساعة يعيد الاستجابة الأولى. |
ترويسات الطلبمثال
Authorization: Bearer oqur_live_8f3kQ2…
Content-Type: application/json
Accept: application/json
الاستجابة 401 مثال
{
"error": {
"code": "unauthenticated",
"message": "مفتاح API مفقود أو غير صالح.",
"request_id": "req_5nT2pW"
}
}
حدود المعدل
يمكن لكل مفتاح API إجراء 60 طلبًا في الدقيقة؛ وفي باقة المؤسسات يُضبط الحد حسب احتياجك. نقاط النهاية المجمّعة تعالج 100 عنصر في طلب واحد، فيمكنك إنشاء أو تعديل ما يصل إلى 6,000 رمز في الدقيقة.
ترويسات الاستجابة
| الترويسة | النوع | الوصف |
|---|---|---|
X-RateLimit-Limit |
integer |
إجمالي طلباتك في الدقيقة. |
X-RateLimit-Remaining |
integer |
الطلبات المتبقية لهذه الدقيقة. |
X-RateLimit-Reset |
integer |
موعد إعادة ضبط حصتك، كطابع زمني Unix. |
Retry-After |
integer |
فقط في استجابة 429: كم ثانية تنتظر. |
حين تتلقى 429، انتظر مدة Retry-After وحاول مرة أخرى. ومع تكرار الأخطاء، فإن مضاعفة الانتظار في كل محاولة هي الطريقة الأكثر أمانًا.
الاستجابة 429 مثال
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790759580
Retry-After: 18
{
"error": {
"code": "rate_limited",
"message": "استنفدت طلبات هذه الدقيقة. حاول مرة أخرى بعد 18 ثانية.",
"request_id": "req_9kP1sV"
}
}
رموز QR
إنشاء الرموز وتعديلها وإنتاج ملفات الطباعة. تغيير وجهة رمز ديناميكي لا يغيّر رابطه المختصر: يبقى الرمز المطبوع كما هو.
إنشاء بالجملة
POST
/qr-codes/bulk
ينشئ ما يصل إلى 100 رمز QR في طلب واحد. يُتحقق من كل عنصر على حدة؛ وإذا كان أي عنصر غير صالح، لا يُنشأ أي منها وتعود الأخطاء بترتيب العناصر.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:write
الترويسات
| الترويسة | النوع | الوصف |
|---|---|---|
Idempotency-Key |
string |
قيمة فريدة لإرسال الطلب مجددًا بأمان. |
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
itemsمطلوب |
array |
الرموز المراد إنشاؤها. عنصر واحد على الأقل و100 على الأكثر. |
items[].typeمطلوب |
string |
نوع QR: واحد من 24 نوعًا مثل url وpdf وmenu وvcard-plus وwifi. |
items[].targetمطلوب |
object |
وجهة تعتمد على النوع. الحقل url للنوع url، والحقل file_url للنوع pdf. |
items[].name |
string |
الاسم الظاهر في اللوحة. 120 حرفًا على الأكثر. |
items[].folder_id |
string |
المجلد الذي يُضاف إليه الرمز. |
items[].design |
object |
اللون والنقش والزوايا والشعار والإطار. إذا تُرك فارغًا، يُستخدم القالب الافتراضي لحسابك. |
الأنواع على الخط Q5 (wifi، text، vcard، email، sms، whatsapp) تُنشأ ثابتة ولا تُحتسب من حصة رموزك الديناميكية.
رموز الحالة
- 201 أُنشئت الرموز.
- 401 مفتاح API مفقود أو غير صالح.
- 403 باقتك لا تسمح بواجهة API أو بهذا العدد من الرموز الديناميكية.
- 422 عنصر أو أكثر غير صالح؛ والتفاصيل في المصفوفة details.
- 429 بلغت حد المعدل؛ انتظر مدة Retry-After.
curl -X POST https://api.oqur.io/v1/qr-codes/bulk \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: campaign-september-01" \
-d '{
"items": [
{
"type": "url",
"name": "ملصق · Kadıköy",
"target": { "url": "https://cafename.com/campaign" },
"folder_id": "fld_91xQ"
},
{
"type": "pdf",
"name": "Katalog 2026",
"target": { "file_url": "https://kafeadi.com/katalog.pdf" }
}
]
}'
<?php
// $oqur: العميل من قسم البدء
$res = $oqur->post('qr-codes/bulk', [
'headers' => ['Idempotency-Key' => 'campaign-september-01'],
'json' => [
'items' => [
[
'type' => 'url',
'name' => 'ملصق · Kadıköy',
'target' => ['url' => 'https://cafename.com/campaign'],
'folder_id' => 'fld_91xQ',
],
[
'type' => 'pdf',
'name' => 'Katalog 2026',
'target' => ['file_url' => 'https://kafeadi.com/katalog.pdf'],
],
],
],
]);
// oqur(): الدالة المساعدة من قسم البدء
const { data } = await oqur('/qr-codes/bulk', {
method: 'POST',
headers: { 'Idempotency-Key': 'campaign-september-01' },
body: JSON.stringify({
items: [
{
type: 'url',
name: 'ملصق · Kadıköy',
target: { url: 'https://cafename.com/campaign' },
folder_id: 'fld_91xQ',
},
{
type: 'pdf',
name: 'Katalog 2026',
target: { file_url: 'https://kafeadi.com/katalog.pdf' },
},
],
}),
});
الاستجابة 201 مثال
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "ملصق · Kadıköy",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"folder_id": "fld_91xQ",
"created_at": "2026-09-30T09:12:44Z"
},
{
"id": "qr_8Lr3nY",
"type": "pdf",
"name": "Katalog 2026",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/8Lr3nQ",
"folder_id": null,
"created_at": "2026-09-30T09:12:44Z"
}
],
"meta": { "created": 2 }
}
تحديث بالجملة
PATCH
/qr-codes/bulk
يحدّث ما يصل إلى 100 رمز في طلب واحد. تتغير فقط الحقول التي ترسلها؛ ويبقى الرابط المختصر والرمز المطبوع كما هما.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:write
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
itemsمطلوب |
array |
الرموز المراد تحديثها. عنصر واحد على الأقل و100 على الأكثر. |
items[].idمطلوب |
string |
معرّف الرمز. |
items[].target |
object |
الوجهة الجديدة. تذهب إليها عمليات المسح التالية فورًا. |
items[].status |
string |
active أو paused. من يمسح رمزًا متوقفًا مؤقتًا يرى صفحة «مغلق مؤقتًا» بسيطة. |
items[].name |
string |
الاسم الجديد. |
items[].folder_id |
string |
المجلد الذي يُنقل إليه؛ وnull لإخراجه من مجلده. |
items[].design |
object |
حقول التصميم. تُدمج الحقول الفرعية التي ترسلها. |
رموز الحالة
- 200 حُدّثت الرموز.
- 401 مفتاح API مفقود أو غير صالح.
- 404 رمز في القائمة غير موجود أو ليس لك.
- 422 عنصر غير صالح؛ لم يُحدَّث أي رمز.
- 429 بلغت حد المعدل.
curl -X PATCH https://api.oqur.io/v1/qr-codes/bulk \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "qr_7Kq2mX", "target": { "url": "https://kafeadi.com/ekim" } },
{ "id": "qr_8Lr3nY", "status": "paused" }
]
}'
<?php
$res = $oqur->patch('qr-codes/bulk', [
'json' => [
'items' => [
['id' => 'qr_7Kq2mX', 'target' => ['url' => 'https://kafeadi.com/ekim']],
['id' => 'qr_8Lr3nY', 'status' => 'paused'],
],
],
]);
const { data } = await oqur('/qr-codes/bulk', {
method: 'PATCH',
body: JSON.stringify({
items: [
{ id: 'qr_7Kq2mX', target: { url: 'https://kafeadi.com/ekim' } },
{ id: 'qr_8Lr3nY', status: 'paused' },
],
}),
});
الاستجابة 200 مثال
{
"data": [
{ "id": "qr_7Kq2mX", "status": "active", "updated_at": "2026-09-30T10:04:12Z" },
{ "id": "qr_8Lr3nY", "status": "paused", "updated_at": "2026-09-30T10:04:12Z" }
],
"meta": { "updated": 2 }
}
سرد
GET
/qr-codes
يعيد الرموز في حسابك مقسمة على صفحات. الترتيب الافتراضي من الأحدث.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:read
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
page |
integer |
رقم الصفحة. الافتراضي 1. |
per_page |
integer |
السجلات في الصفحة. الافتراضي 25، و100 على الأكثر. |
folder_id |
string |
الرموز في هذا المجلد فقط. |
type |
string |
صفِّ حسب النوع، مثلًا menu. |
status |
string |
draft أو scheduled أو active أو paused. |
search |
string |
يبحث في الاسم أو الرابط المختصر. |
sort |
string |
created_at أو name أو scans_total. للترتيب التنازلي ضع علامة ناقص في الأول: -scans_total. |
رموز الحالة
- 200 عادت القائمة؛ وإذا لم توجد نتائج تكون data مصفوفة فارغة.
- 401 مفتاح API مفقود أو غير صالح.
- 422 قيمة تصفية أو ترتيب غير صالحة.
curl -G https://api.oqur.io/v1/qr-codes \
-H "Authorization: Bearer $OQUR_API_KEY" \
-d folder_id=fld_91xQ \
-d status=active \
-d sort=-scans_total \
-d per_page=25
<?php
$res = $oqur->get('qr-codes', ['query' => [
'folder_id' => 'fld_91xQ',
'status' => 'active',
'sort' => '-scans_total',
'per_page' => 25,
]]);
const params = new URLSearchParams({
folder_id: 'fld_91xQ',
status: 'active',
sort: '-scans_total',
per_page: '25',
});
const { data, meta } = await oqur(`/qr-codes?${params}`);
الاستجابة 200 مثال
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "ملصق · Kadıköy",
"status": "active",
"short_url": "https://oqur.io/d/7Kq2xP",
"scans_total": 312,
"created_at": "2026-09-12T08:30:00Z"
}
],
"meta": { "page": 1, "per_page": 25, "total": 1 },
"links": { "next": null, "prev": null }
}
جلب
GET
/qr-codes/{id}
يعيد كل حقول رمز واحد: الوجهة والتصميم والحالة وإجمالي عمليات المسح.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:read
معاملات المسار
| الحقل | النوع | الوصف |
|---|---|---|
idمطلوب |
string |
معرّف الرمز، مثلًا qr_7Kq2mX. |
رموز الحالة
- 200 وُجد الرمز.
- 401 مفتاح API مفقود أو غير صالح.
- 404 الرمز غير موجود أو ليس لك.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->get('qr-codes/qr_7Kq2mX');
$code = json_decode($res->getBody(), true)['data'];
const { data: code } = await oqur('/qr-codes/qr_7Kq2mX');
الاستجابة 200 مثال
{
"data": {
"id": "qr_7Kq2mX",
"type": "url",
"name": "ملصق · Kadıköy",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"target": { "url": "https://cafename.com/campaign" },
"folder_id": "fld_91xQ",
"design": {
"foreground": "#0B1F3A",
"background": "#FFFFFF",
"dots": "rounded",
"corners": "square",
"logo_url": null,
"frame": { "style": "bottom", "text": "Beni tara" },
"error_correction": "M"
},
"scans_total": 312,
"created_at": "2026-09-12T08:30:00Z",
"updated_at": "2026-09-28T17:02:10Z"
}
}
تحديث
PATCH
/qr-codes/{id}
يحدّث رمزًا واحدًا. تغيير الوجهة لا يغيّر الرمز: يبقى QR المطبوع كما هو، وتذهب عمليات المسح التالية إلى الوجهة الجديدة.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:write
معاملات المسار
| الحقل | النوع | الوصف |
|---|---|---|
idمطلوب |
string |
معرّف الرمز. |
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
target |
object |
الوجهة الجديدة. لا يمكن تغييرها في الرموز الثابتة. |
status |
string |
active أو paused. |
name |
string |
الاسم الجديد. |
folder_id |
string |
المجلد الذي يُنقل إليه؛ وnull لإخراجه من مجلده. |
design |
object |
حقول التصميم. تُدمج الحقول الفرعية التي ترسلها. |
رموز الحالة
- 200 حُدّث الرمز.
- 401 مفتاح API مفقود أو غير صالح.
- 404 الرمز غير موجود أو ليس لك.
- 422 حقل غير صالح؛ مثلًا، لا يمكن تغيير وجهة رمز ثابت.
curl -X PATCH https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "target": { "url": "https://kafeadi.com/kis-menusu" } }'
<?php
$res = $oqur->patch('qr-codes/qr_7Kq2mX', [
'json' => ['target' => ['url' => 'https://kafeadi.com/kis-menusu']],
]);
const { data } = await oqur('/qr-codes/qr_7Kq2mX', {
method: 'PATCH',
body: JSON.stringify({ target: { url: 'https://kafeadi.com/kis-menusu' } }),
});
الاستجابة 200 مثال
{
"data": {
"id": "qr_7Kq2mX",
"status": "active",
"short_url": "https://oqur.io/d/7Kq2xP",
"target": { "url": "https://kafeadi.com/kis-menusu" },
"updated_at": "2026-09-30T10:15:03Z"
}
}
نسخ
POST
/qr-codes/{id}/duplicate
ينسخ الرمز بتصميمه ووجهته. تبدأ النسخة برابط مختصر جديد وصفر عمليات مسح؛ وهي أسرع طريقة لتكرار التصميم نفسه للفروع.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:write
معاملات المسار
| الحقل | النوع | الوصف |
|---|---|---|
idمطلوب |
string |
معرّف الرمز المراد نسخه. |
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
name |
string |
اسم النسخة. إذا تُرك فارغًا، تُضاف «(نسخة)» إلى الاسم الأصلي. |
folder_id |
string |
المجلد الذي تُضاف إليه النسخة. الافتراضي: مجلد الرمز الأصلي. |
رموز الحالة
- 201 أُنشئت النسخة.
- 401 مفتاح API مفقود أو غير صالح.
- 403 بلغت حد الرموز الديناميكية.
- 404 الرمز غير موجود أو ليس لك.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/duplicate \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "ملصق · Beşiktaş" }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/duplicate', [
'json' => ['name' => 'ملصق · Beşiktaş'],
]);
const { data: copy } = await oqur('/qr-codes/qr_7Kq2mX/duplicate', {
method: 'POST',
body: JSON.stringify({ name: 'ملصق · Beşiktaş' }),
});
الاستجابة 201 مثال
{
"data": {
"id": "qr_9Ms4pZ",
"type": "url",
"name": "ملصق · Beşiktaş",
"status": "active",
"short_url": "https://oqur.io/d/9Ms4pR",
"scans_total": 0,
"created_at": "2026-09-30T10:20:31Z"
}
}
إنشاء صورة
POST
/qr-codes/{id}/image
ينتج صورة جاهزة للطباعة للرمز ويعيد رابط تنزيل قصير الأجل. يمكنك تمرير إعدادات لهذه الصورة فقط دون تغيير التصميم المحفوظ.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:read
معاملات المسار
| الحقل | النوع | الوصف |
|---|---|---|
idمطلوب |
string |
معرّف الرمز. |
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
formatمطلوب |
string |
png أو svg أو pdf أو eps. |
size |
integer |
لصيغة PNG، طول الضلع بالبكسل. بين 256 و4096؛ والافتراضي 1024. |
margin |
integer |
المنطقة الهادئة بالوحدات. الافتراضي 4؛ ولا يُنصح بأقل. |
design |
object |
إعدادات تصميم مؤقتة لهذه الصورة فقط. |
رابط التنزيل صالح لمدة ساعة واحدة. إذا أردت الاحتفاظ بالملف على خادمك، فاستخدم نقطة النهاية جلب صورة.
رموز الحالة
- 200 الصورة جاهزة.
- 401 مفتاح API مفقود أو غير صالح.
- 404 الرمز غير موجود أو ليس لك.
- 422 صيغة أو مقاس غير مدعوم.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "format": "svg", "margin": 4 }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/image', [
'json' => ['format' => 'svg', 'margin' => 4],
]);
$url = json_decode($res->getBody(), true)['data']['url'];
const { data } = await oqur('/qr-codes/qr_7Kq2mX/image', {
method: 'POST',
body: JSON.stringify({ format: 'svg', margin: 4 }),
});
console.log(data.url); // صالح لمدة ساعة
الاستجابة 200 مثال
{
"data": {
"format": "svg",
"url": "https://cdn.oqur.io/r/qr_7Kq2mX.svg?sig=Vb8f2…",
"expires_at": "2026-09-30T11:12:44Z"
}
}
جلب صورة
GET
/qr-codes/{id}/image.{format}
يعيد الصورة مباشرة كملف. الاستجابة هي الملف نفسه لا JSON؛ مناسبة للاحتفاظ بها على خادمك أو إضافتها إلى سير عمل الطباعة.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:read
معاملات المسار
| الحقل | النوع | الوصف |
|---|---|---|
idمطلوب |
string |
معرّف الرمز. |
formatمطلوب |
string |
png أو svg أو pdf أو eps. |
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
size |
integer |
لصيغة PNG، طول الضلع بالبكسل. الافتراضي 1024. |
margin |
integer |
المنطقة الهادئة بالوحدات. الافتراضي 4. |
رموز الحالة
- 200 عاد الملف.
- 401 مفتاح API مفقود أو غير صالح.
- 404 الرمز غير موجود أو ليس لك.
- 422 صيغة أو مقاس غير مدعوم.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048 \
-H "Authorization: Bearer $OQUR_API_KEY" \
-o masa-karti.png
<?php
$oqur->get('qr-codes/qr_7Kq2mX/image.png', [
'query' => ['size' => 2048],
'sink' => __DIR__ . '/masa-karti.png',
]);
import { writeFile } from 'node:fs/promises';
const res = await fetch('https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048', {
headers: { Authorization: `Bearer ${process.env.OQUR_API_KEY}` },
});
await writeFile('masa-karti.png', Buffer.from(await res.arrayBuffer()));
الاستجابة 200 مثال
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 48213
Content-Disposition: attachment; filename="qr_7Kq2mX.png"
Cache-Control: private, max-age=300
(ikili PNG verisi)
حذف بالجملة
DELETE
/qr-codes?ids=…
ينقل ما يصل إلى 100 رمز إلى سلة المحذوفات. يمكن استعادة الرموز من السلة عبر اللوحة خلال 30 يومًا؛ ومن يمسح رمزًا ديناميكيًا في السلة يرى صفحة «هذا الرمز غير مستخدم». إذا أردت إيقاف رمز فقط، فاضبط حالته على paused.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:write
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
idsمطلوب |
string |
معرّفات الرموز مفصولة بفواصل، 100 على الأكثر. |
رموز الحالة
- 200 نُقلت الرموز إلى سلة المحذوفات.
- 401 مفتاح API مفقود أو غير صالح.
- 404 لم يُعثر على رمز في القائمة؛ لم يُحذف أي رمز.
- 422 قائمة المعرّفات فارغة أو تتجاوز 100.
curl -X DELETE "https://api.oqur.io/v1/qr-codes?ids=qr_7Kq2mX,qr_8Lr3nY,qr_9Ms4pZ" \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->delete('qr-codes', ['query' => [
'ids' => implode(',', ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ']),
]]);
const ids = ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ'].join(',');
const { meta } = await oqur(`/qr-codes?ids=${ids}`, { method: 'DELETE' });
الاستجابة 200 مثال
{
"meta": { "deleted": 3 }
}
التحليلات
اسحب بيانات المسح إلى تقاريرك الخاصة. لا تحتوي التقارير على بيانات شخصية: لا يُعاد عنوان IP ولا معرّف جهاز ولا موقع دقيق.
تقرير التحليلات
GET
/analytics/scans
يعيد الإجماليات والسلسلة الزمنية والتوزيع للرموز ونطاق التاريخ الذي تختاره. تُجمَّع التواريخ والأوقات بالمنطقة الزمنية التي تريدها.
المصادقة: ApiKeyAuth (Bearer)النطاق: analytics:read
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
fromمطلوب |
date |
تاريخ البدء، YYYY-MM-DD. |
toمطلوب |
date |
تاريخ الانتهاء، شاملًا. النطاق 366 يومًا على الأكثر. |
qr_ids |
string |
معرّفات الرموز مفصولة بفواصل. إذا تُرك فارغًا، فكل الرموز. |
timezone |
string |
منطقة زمنية IANA، مثلًا Europe/Istanbul. الافتراضي: المنطقة الزمنية لمساحة العمل. |
group_by |
string |
hour أو day أو week أو month. الافتراضي day. |
breakdown |
string |
country أو city أو device أو os أو browser. |
رموز الحالة
- 200 عاد التقرير.
- 401 مفتاح API مفقود أو غير صالح.
- 422 نطاق التاريخ غير صالح أو يتجاوز 366 يومًا.
- 429 بلغت حد المعدل.
curl -G https://api.oqur.io/v1/analytics/scans \
-H "Authorization: Bearer $OQUR_API_KEY" \
-d from=2026-09-01 \
-d to=2026-09-07 \
-d timezone=Europe/Istanbul \
-d group_by=day \
-d breakdown=device
<?php
$res = $oqur->get('analytics/scans', ['query' => [
'from' => '2026-09-01',
'to' => '2026-09-07',
'timezone' => 'Europe/Istanbul',
'group_by' => 'day',
'breakdown' => 'device',
]]);
const params = new URLSearchParams({
from: '2026-09-01',
to: '2026-09-07',
timezone: 'Europe/Istanbul',
group_by: 'day',
breakdown: 'device',
});
const { data: report } = await oqur(`/analytics/scans?${params}`);
الاستجابة 200 مثال
{
"data": {
"range": { "from": "2026-09-01", "to": "2026-09-07", "timezone": "Europe/Istanbul" },
"totals": { "scans": 1840, "unique_scans": 1312 },
"series": [
{ "period": "2026-09-01", "scans": 212, "unique_scans": 160 },
{ "period": "2026-09-02", "scans": 247, "unique_scans": 181 }
],
"breakdown": {
"by": "device",
"items": [
{ "key": "ios", "scans": 1011 },
{ "key": "android", "scans": 783 },
{ "key": "desktop", "scans": 46 }
]
}
}
}
المجلدات
جمّع رموزك حسب الفرع أو الحملة أو العميل. يرى كل من في الفريق كل المجلدات؛ ويحدد دوره ما يستطيع فعله.
إنشاء مجلد
POST
/folders
ينشئ مجلدًا جديدًا لتجميع رموزك.
المصادقة: ApiKeyAuth (Bearer)النطاق: folders:write
جسم الطلب
| الحقل | النوع | الوصف |
|---|---|---|
nameمطلوب |
string |
اسم المجلد، بين 1 و80 حرفًا. يجب أن يكون فريدًا في حسابك. |
رموز الحالة
- 201 أُنشئ المجلد.
- 401 مفتاح API مفقود أو غير صالح.
- 409 يوجد مجلد بهذا الاسم بالفعل.
- 422 الاسم فارغ أو يتجاوز 80 حرفًا.
curl -X POST https://api.oqur.io/v1/folders \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "فرع Kadıköy" }'
<?php
$res = $oqur->post('folders', ['json' => ['name' => 'فرع Kadıköy']]);
const { data: folder } = await oqur('/folders', {
method: 'POST',
body: JSON.stringify({ name: 'فرع Kadıköy' }),
});
الاستجابة 201 مثال
{
"data": {
"id": "fld_91xQ",
"name": "فرع Kadıköy",
"qr_count": 0,
"created_at": "2026-09-30T10:31:08Z"
}
}
سرد المجلدات
GET
/folders
يعيد المجلدات في حسابك مع عدد الرموز في كل منها.
المصادقة: ApiKeyAuth (Bearer)النطاق: qr:read
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
page |
integer |
رقم الصفحة. الافتراضي 1. |
per_page |
integer |
السجلات في الصفحة. الافتراضي 25، و100 على الأكثر. |
رموز الحالة
- 200 عادت القائمة.
- 401 مفتاح API مفقود أو غير صالح.
curl https://api.oqur.io/v1/folders \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->get('folders');
$folders = json_decode($res->getBody(), true)['data'];
const { data: folders } = await oqur('/folders');
الاستجابة 200 مثال
{
"data": [
{ "id": "fld_91xQ", "name": "فرع Kadıköy", "qr_count": 14 },
{ "id": "fld_22bR", "name": "عبوة · سبتمبر", "qr_count": 120 }
],
"meta": { "page": 1, "per_page": 25, "total": 2 }
}
رموز الأخطاء
تعود الأخطاء دائمًا بالطريقة نفسها: رمز حالة HTTP وكائن error. الحقل code لبرنامجك، والحقل message للبشر؛ قد يتغير نص الرسالة، فاعتمد على الرمز.
الحالات
| HTTP | code | الوصف |
|---|---|---|
400 |
bad_request |
تعذّرت قراءة جسم الطلب. تأكد من صلاحية JSON وتحقق من ترويسة Content-Type. |
401 |
unauthenticated |
مفتاح API مفقود أو غير صالح. تحقق من ترويسة Authorization. |
403 |
forbidden |
باقتك أو مفتاحك لا يسمح بذلك؛ مثلًا، بلغت حد الرموز الديناميكية. |
404 |
not_found |
السجل غير موجود أو ليس في حسابك. |
409 |
conflict |
يوجد سجل بالاسم نفسه، أو أُعيد استخدام Idempotency-Key بجسم مختلف. |
422 |
validation_failed |
حقل غير صالح. أي حقل رُفض ولماذا موجود في المصفوفة details. |
429 |
rate_limited |
بلغت حد المعدل. انتظر مدة Retry-After. |
500 |
server_error |
حدث خطأ من جانبنا. حاول مرة أخرى؛ وإذا استمر، فراسلنا مع request_id. |
الاستجابة 422 مثال
{
"error": {
"code": "validation_failed",
"message": "تعذّر التحقق من عنصرين.",
"details": [
{ "field": "items.0.target.url", "message": "يجب أن يكون عنوان ويب صالحًا." },
{ "field": "items.3.type", "message": "Bilinmeyen QR tipi: menu2." }
],
"request_id": "req_3hV8qL"
}
}
جرّبه في اللوحة أولًا، ثم أتمِته.
حين تجهز واجهة API ستُتاح في باقتي الأعمال والمؤسسات. ولتكاملات المؤسسات يمكنك التحدث مع فريق المبيعات.