تخطَّ إلى المحتوى
oqur

أدِر رموزك من نظامك الخاص.

أنشئ مئات رموز QR في طلب واحد، وحدّث وجهاتها، واسحب تقارير المسح إلى لوحتك الخاصة. كل ما يلزم: REST وJSON ومفتاح API.

مسودة — ستُعتمد نقاط النهاية أثناء التطوير. تعرض هذه الصفحة البنية المقترحة؛ لا توجد واجهة API فعلية بعد. قد تتغير العناوين وأسماء الحقول والحدود وصيغ الاستجابة.

عنوان URL الأساسي
https://api.oqur.io/v1
الصيغة
JSON، UTF-8، HTTPS
المصادقة
مفتاح API من نوع Bearer
الباقات
الأعمال والمؤسسات

البدء

تتيح لك واجهة oqur البرمجية أن تفعل من برنامجك ما تفعله في اللوحة: إنشاء رموز QR بالجملة، وتحديث الوجهات، وتنزيل ملفات الطباعة، وتقارير المسح. كل طلب يمر عبر HTTPS بجسم JSON.

  1. أنشئ مفتاحًا

    أنشئ مفتاحًا في قسم مفاتيح API من قائمة الإعدادات في اللوحة واختر نطاقاته. حين تجهز الواجهة ستُتاح في باقتي الأعمال والمؤسسات.

  2. أرسل طلبك الأول

    المثال المجاور يسرد أول رمز في حسابك. إذا كانت الاستجابة 200 فكل شيء جاهز.

  3. راقب الحدود

    طلباتك المتبقية في ترويسات كل استجابة. والتفاصيل في قسم حدود المعدل.

القواعد

الموضوعالصيغةالوصف
التاريخ والوقت 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 للبشر؛ قد يتغير نص الرسالة، فاعتمد على الرمز.

الحالات

HTTPcodeالوصف
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"
  }
}

هل من خطأ؟

راسلنا مع قيمة request_id؛ وسنجد طلبك ونتحقق منه.

الدعم الفني

جرّبه في اللوحة أولًا، ثم أتمِته.

حين تجهز واجهة API ستُتاح في باقتي الأعمال والمؤسسات. ولتكاملات المؤسسات يمكنك التحدث مع فريق المبيعات.