التقارير

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf

{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf

{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}

GetQR API في مرحلة تجريبية (beta) ومتاحة لمساحات عمل مختارة. قد تتغير التفاصيل قبل الإصدار العام.

تلخّص التقارير عمليات المسح لكل رمز QR عن يوم أو أسبوع أو شهر مكتمل. صدّر تقريرًا فورًا، أو جدوِل تقريرًا يُرسل بالبريد الإلكتروني بانتظام.

الطريقة	المسار	الوصف
`POST`	`/api/v1/reports`	تصدير تقرير
`GET`	`/api/v1/reports/schedules`	عرض قائمة التقارير المجدولة
`POST`	`/api/v1/reports/schedules`	جدولة تقرير
`PATCH`	`/api/v1/reports/schedules/{id}`	تحديث تقرير مجدول
`DELETE`	`/api/v1/reports/schedules/{id}`	حذف تقرير مجدول

الترويسات

string

مطلوب

Bearer متبوعة بمفتاح API الخاص بك. راجع المصادقة.

string

application/json. مطلوب في طلبات POST وPATCH.

النطاق

تأخذ التقارير الفردية والمجدولة كلتاهما scope:

`scope`	ما يغطيه	`qrIds`
`all`	رموز QR في مساحة عملك	لا ترسله
`selected`	مجموعة مختارة من رموز QR	معرّف واحد أو أكثر
`single`	رمز QR واحد بالضبط	معرّف واحد بالضبط

يسرد التقرير 50 رمز QR على الأكثر. مع all، تكون هذه أحدث رموز QR النشطة إنشاءً؛ وتُستبعد الرموز الموقوفة مؤقتًا. مع selected وsingle، تُضمَّن الرموز الموقوفة مؤقتًا. رموز QR التي لا رابط قصيرًا لها ليست لديها عمليات مسح وتُتخطى.

الفترة

الفترة هي دائمًا آخر فترة مكتملة، لذا لا يتضمن التقرير أبدًا بيانات اليوم الجزئية. حدودها منتصف الليل بالمنطقة الزمنية للتقرير.

`period` أو `frequency`	ما يغطيه
`daily`	اليوم السابق
`weekly`	الأسبوع السابق، من الاثنين إلى الأحد
`monthly`	الشهر الميلادي السابق

تصدير تقرير

POST /api/v1/reports يُنشئ تقريرًا لآخر فترة مكتملة ويُرجعه في الاستجابة.

string

مطلوب

all أو selected أو single. راجع النطاق.

string

مطلوب

daily أو weekly أو monthly. راجع الفترة.

string

مطلوب

تُرجع json التقرير في جسم الاستجابة. وتُرجع csv وpdf ملفًا للتنزيل.

string[]

رموز QR المراد تغطيتها. مطلوب مع selected (معرّف واحد أو أكثر) وsingle (معرّف واحد بالضبط). لا ترسله مع all.

string

افتراضي:"UTC"

المنطقة الزمنية بصيغة IANA التي تُحاذى عليها حدود الفترة، مثل America/New_York. تُرجع المنطقة الزمنية غير المعروفة 422.

string

افتراضي:"en"

لغة ملف PDF، مثل en أو de. تعود القيمة غير المدعومة إلى الإنجليزية. يتجاهله csv وjson.

string

العنوان المعروض على ملف PDF، حتى 40 حرفًا. يتجاهله csv وjson.

استجابة JSON

string

أول يوم في الفترة، YYYY-MM-DD.

string

أول يوم بعد الفترة، YYYY-MM-DD. تنتهي الفترة عند منتصف الليل في بداية هذا اليوم.

object[]

إدخال واحد لكل رمز QR.

إظهار properties

string

معرّف رمز QR.

string

عنوان رمز QR، أو Untitled QR.

string

نوع رمز QR، مثل website.

integer

إجمالي عمليات المسح في الفترة.

integer

عمليات المسح الفريدة في الفترة.

string

رمز الدولة صاحبة أكبر عدد من عمليات المسح، أو — عند عدم وجود عمليات مسح.

string

الجهاز صاحب أكبر عدد من عمليات المسح، أو —.

string

نظام التشغيل صاحب أكبر عدد من عمليات المسح، أو —.

string

المتصفح صاحب أكبر عدد من عمليات المسح، أو —.

استجابات CSV وPDF

الجسم هو الملف نفسه. تسمّيه الترويسة Content-Disposition باسم الفترة، مثل report-2026-08-10_2026-08-17.csv. يحتوي ملف CSV على صف واحد لكل رمز QR بالأعمدة QR ID وQR name وQR type وTotal scans وUnique scans وTop geography وTop device وTop OS وTop browser.

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'

curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf

{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}

كائن التقرير المجدول

يُرسل التقرير المجدول بالبريد الإلكتروني إلى الحساب الذي أنشأه، عند منتصف الليل بمنطقته الزمنية.

string

معرّف التقرير المجدول.

string | null

التسمية المعروضة في موضوع البريد الإلكتروني وفي لوحة التحكم.

string

daily أو weekly أو monthly.

string

all أو selected أو single.

string[] | null

رموز QR التي يغطيها التقرير مع النطاقين selected وsingle. null عندما لا تُرسل أي معرّفات.

null

دائمًا null. محجوز.

boolean

ما إذا كان ملف PDF مرفقًا بالبريد الإلكتروني.

string

active أو paused.

string

المنطقة الزمنية بصيغة IANA التي يُحاذى عليها وقت الإرسال والفترة.

string

لغة البريد الإلكتروني وملف PDF.

string

موعد البريد الإلكتروني التالي، بصيغة ISO 8601: منتصف الليل التالي (daily)، أو يوم الاثنين التالي (weekly)، أو اليوم الأول من الشهر التالي (monthly)، بالمنطقة الزمنية للتقرير.

string | null

وقت إرسال آخر بريد إلكتروني، بصيغة ISO 8601.

string

تاريخ الإنشاء، بصيغة ISO 8601.

string

تاريخ آخر تحديث، بصيغة ISO 8601.

عرض قائمة التقارير المجدولة

GET /api/v1/reports/schedules يُرجع التقارير المجدولة في مساحة عملك، بما فيها التي أنشأها أعضاء آخرون، الأحدث أولًا. القائمة مقسّمة إلى صفحات: راجع ترقيم الصفحات.

integer

افتراضي:"1"

الصفحة التي تُعاد، 1 أو أكبر.

integer

افتراضي:"100"

النتائج في كل صفحة، من 1 إلى 100.

curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

جدولة تقرير

POST /api/v1/reports/schedules يُنشئ تقريرًا يُرسل بالبريد الإلكتروني بانتظام. تُحسب nextRunAt من التكرار والمنطقة الزمنية.

لا يمكن أن ينتمي رمز QR إلا إلى تقرير مجدول واحد لكل تكرار. يُرجع الجدول المتداخل 409 conflict.

يتداخل التقرير ذو النطاق all مع كل تقرير آخر بالتكرار نفسه. وتُحتسب التقارير الموقوفة مؤقتًا أيضًا.

string

مطلوب

عدد مرات إرسال التقرير: daily أو weekly أو monthly. يحدد أيضًا الفترة التي يغطيها. راجع الفترة.

string

مطلوب

all أو selected أو single. راجع النطاق.

string

مطلوب

المنطقة الزمنية بصيغة IANA التي يُحاذى عليها وقت الإرسال والفترة، مثل America/New_York. تُرجع المنطقة الزمنية غير المعروفة 422.

string

مطلوب

لغة البريد الإلكتروني وملف PDF، مثل en أو de. تعود القيمة غير المدعومة إلى الإنجليزية. تُنشأ ملفات PDF بلغات zh وja وko وar باللغة الإنجليزية.

string[]

رموز QR المراد تغطيتها. مطلوب مع selected (معرّف واحد أو أكثر) وsingle (معرّف واحد بالضبط). يجب أن يكون كل معرّف لرمز QR في مساحة عملك، وإلا يُرجع الطلب 404.

string

التسمية المعروضة في موضوع البريد الإلكتروني وفي لوحة التحكم، حتى 40 حرفًا.

boolean

افتراضي:"false"

إرفاق نسخة PDF من التقرير بالبريد الإلكتروني.

curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'

{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}

تحديث تقرير مجدول

PATCH /api/v1/reports/schedules/{id} يغيّر تقريرًا مجدولًا، أو يوقفه مؤقتًا ويستأنفه. أرسل فقط الحقول التي تريد تغييرها، حقلًا واحدًا على الأقل. تغيير التكرار أو المنطقة الزمنية، أو استئناف تقرير موقوف مؤقتًا، يعيد حساب nextRunAt. تظل قاعدة التقرير الواحد لكل تكرار سارية، لذا يُرجع التغيير المتداخل 409.

string

مطلوب

معرّف التقرير المجدول. خذه من استجابة القائمة أو الإنشاء.

string

توقف paused رسائل البريد الإلكتروني دون حذف الجدول. وتستأنفها active.

string

التسمية، حتى 40 حرفًا.

string

daily أو weekly أو monthly.

string

all أو selected أو single.

string[]

رموز QR المراد تغطيتها. يجب أن يكون كل معرّف لرمز QR في مساحة عملك.

boolean

إرفاق ملف PDF بالبريد الإلكتروني.

string

المنطقة الزمنية بصيغة IANA.

string

لغة البريد الإلكتروني وملف PDF.

curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'

{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}

حذف تقرير مجدول

DELETE /api/v1/reports/schedules/{id} يحذف الجدول ويوقف كل رسائل البريد الإلكتروني اللاحقة.

لا يمكن التراجع عن حذف تقرير مجدول.

string

مطلوب

معرّف التقرير المجدول.

curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }

المشكلات الشائعة

الخطأ 404 عند تصدير تقرير

مع النطاق selected أو single، لم يطابق أي من qrIds رمز QR له رابط قصير في مساحة عملك. تحقّق من المعرّفات.

404 "QR not found." عند جدولة تقرير

أحد qrIds ليس رمز QR في مساحة عملك، أو أنه حُذف. تحقّق من المعرّفات باستخدام عرض قائمة رموز QR.

الخطأ 409 عند جدولة تقرير

أحد رموز QR ينتمي بالفعل إلى تقرير مجدول بالتكرار نفسه، أو أن تقريرًا بهذا التكرار يستخدم النطاق all. عدّل ذلك التقرير أو احذفه، أو اختر تكرارًا مختلفًا.

404 "Scheduled report not found."

لا يطابق id أي تقرير مجدول في مساحة عملك. خذه من عرض قائمة التقارير المجدولة.

التقرير لا يتضمن عمليات المسح اليوم

لا تغطي التقارير إلا آخر فترة مكتملة. استخدم التحليلات للأرقام الفورية.

API

الترويسات

النطاق

الفترة

تصدير تقرير

استجابة JSON

استجابات CSV وPDF

كائن التقرير المجدول

عرض قائمة التقارير المجدولة

جدولة تقرير

تحديث تقرير مجدول

حذف تقرير مجدول

المشكلات الشائعة

الخطوات التالية

التحليلات