المصادقة

تتطلب كل الطلبات Bearer token في ترويسة Authorization. أنشئ المفاتيح من صفحة مفاتيح API؛ يُعرض المفتاح الخام مرة واحدة عند الإنشاء، ثم تظهر البادئة فقط. المفاتيح مرتبطة بمساحة واحدة.

Authorization: Bearer qrf_live_...

حدود المعدل

حدود بالدقيقة لكل مساحة عمل (مشتركة بين جميع مفاتيح مساحة العمل). تحمل كل استجابة الترويسات أدناه؛ وتجاوز الحد يُعيد رمز الحالة 429 مع ترويسة Retry-After (عدد الثواني حتى تُعاد تهيئة النافذة).

Free — 60 req/min
Pro — 300 req/min
Business — 1,000 req/min

X-RateLimit-Plan: pro
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1718724000

# When exceeded:
HTTP/1.1 429 Too Many Requests
Retry-After: 42

مرجع الواجهة

العنوان الأساسيhttps://www.qra.cc/api/v1

GET/qr

قائمة مرقّمة لرموز QR في مساحة عملك.

المعاملات

الاسم	الموضع	النوع	الوصف
`page`	query	integer	· افتراضي `1`
`limit`	query	integer	· افتراضي `20`

الطلب

curl -X GET "https://www.qra.cc/api/v1/qr?page=1&limit=20" \
  -H "Authorization: Bearer qrf_live_..."

مثال الاستجابة 200

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "slug": "abc123xyz",
      "name": "Riyadh Mall — counter sticker",
      "type": "url",
      "destination": "https://example.com/menu",
      "status": "active",
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "pages": 0
  }
}

الاستجابات

200Paginated list
401Missing or invalid API key
429Rate limit exceeded — too many requests this minute (limit is per workspace).

POST/qr

أنشئ رمز QR ديناميكياً جديداً — وفق حدّ عدد الرموز في خطتك.

جسم الطلب application/json

الحقل	النوع	الوصف
`name`*	string	· مثال `Q4 catalogue insert`
`type`	string
`destination`	string	· مثال `https://example.com/catalogue`

الطلب

curl -X POST "https://www.qra.cc/api/v1/qr" \
  -H "Authorization: Bearer qrf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Q4 catalogue insert","type":"url","destination":"https://example.com/catalogue"}'

مثال الاستجابة 201

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "slug": "abc123xyz",
  "name": "Riyadh Mall — counter sticker",
  "type": "url",
  "destination": "https://example.com/menu",
  "status": "active",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-01T12:00:00Z"
}

الاستجابات

201Created
400Validation error
403Plan limit reached
429Rate limit exceeded — too many requests this minute (limit is per workspace).

GET/qr/{id}

اجلب رمزاً واحداً حسب معرّفه.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`*	path	string (uuid)

الطلب

curl -X GET "https://www.qra.cc/api/v1/qr/{id}" \
  -H "Authorization: Bearer qrf_live_..."

مثال الاستجابة 200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "slug": "abc123xyz",
  "name": "Riyadh Mall — counter sticker",
  "type": "url",
  "destination": "https://example.com/menu",
  "status": "active",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-01T12:00:00Z"
}

الاستجابات

200Found
404Not found
429Rate limit exceeded — too many requests this minute (limit is per workspace).

PATCH/qr/{id}

حدّث اسم الرمز أو وجهته أو حالته (نشط / موقوف / منتهٍ).

المعاملات

الاسم	الموضع	النوع	الوصف
`id`*	path	string (uuid)

جسم الطلب application/json

الحقل	النوع	الوصف
`name`	string
`destination`	string
`status`	string	· active · paused · expired

الطلب

curl -X PATCH "https://www.qra.cc/api/v1/qr/{id}" \
  -H "Authorization: Bearer qrf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"string","destination":"string","status":"active"}'

مثال الاستجابة 200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "slug": "abc123xyz",
  "name": "Riyadh Mall — counter sticker",
  "type": "url",
  "destination": "https://example.com/menu",
  "status": "active",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-01T12:00:00Z"
}

الاستجابات

200Updated
429Rate limit exceeded — too many requests this minute (limit is per workspace).

DELETE/qr/{id}

احذف الرمز وجميع عمليات مسحه نهائياً.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`*	path	string (uuid)

الطلب

curl -X DELETE "https://www.qra.cc/api/v1/qr/{id}" \
  -H "Authorization: Bearer qrf_live_..."

الاستجابات

204Deleted
429Rate limit exceeded — too many requests this minute (limit is per workspace).

GET/qr/{id}/scans

سجل المسح الخام — الطابع الزمني والدولة والجهاز ونظام التشغيل والمتصفح والمصدر. صفِّ عبر since / until.

المعاملات

الاسم	الموضع	النوع	الوصف
`id`*	path	string (uuid)
`page`	query	integer	· افتراضي `1`
`limit`	query	integer	· افتراضي `50`
`since`	query	string (date-time)
`until`	query	string (date-time)

الطلب

curl -X GET "https://www.qra.cc/api/v1/qr/{id}/scans?page=1&limit=50" \
  -H "Authorization: Bearer qrf_live_..."

مثال الاستجابة 200

{
  "data": [
    {
      "id": 0,
      "ts": "2026-04-01T12:00:00Z",
      "country": "SA",
      "city": "Riyadh",
      "device": "mobile",
      "os": "iOS",
      "browser": "Safari",
      "referrer": "string"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "pages": 0
  }
}

الاستجابات

200Paginated scans
429Rate limit exceeded — too many requests this minute (limit is per workspace).