التحليلات

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

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

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

الطريقة	المسار	الوصف
`GET`	`/api/v1/qrs/{qrId}/analytics`	الحصول على تحليلات رمز QR
`GET`	`/api/v1/analytics`	الحصول على تحليلات مساحة العمل

للحصول على ملخص جاهز لكل رمز QR، راجع التقارير.

معنى الأرقام

عمليات المسح. كل عدد موجود في الحقل clicks. تُحتسب عملية مسح في كل مرة يفتح فيها شخص الرابط القصير لرمز QR.
عمليات المسح الفريدة. مع unique=true، يُحتسب كل زائر مرة واحدة ضمن النطاق الزمني.
النطاق. تأتي الأرقام من الرابط القصير لرمز QR. رمز QR الذي لا رابط قصيرًا له ليست لديه عمليات مسح تُحتسب.
السجل. لا يمكن إعادة تعيين التحليلات عبر API. حذف رمز QR لا يمسح بيانات المسح التاريخية الخاصة به.

الترويسات

string

مطلوب

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

معاملات الاستعلام

تأخذ نقطتا النهاية كلتاهما هذه المعاملات. جميعها اختيارية.

string

افتراضي:"count"

بُعد التصنيف. تُرجع count الإجمالي. راجع التصنيفات لكل قيمة وبنية استجابتها.

string

افتراضي:"30d"

نطاق زمني جاهز: 24h أو 7d أو 30d أو 90d أو 1y أو mtd أو qtd أو ytd أو all. راجع النطاقات الزمنية. يُتجاهل عند إرسال start.

string

بداية نطاق مخصص، بصيغة ISO 8601، مثل 2026-08-01 أو 2026-08-01T00:00:00Z. له الأولوية على interval. يجب أن يكون قبل end.

string

نهاية نطاق مخصص، بصيغة ISO 8601. القيمة الافتراضية نهاية اليوم. يُستخدم مع start أو interval=all، ويُتجاهل مع النطاقات الأخرى.

string

افتراضي:"UTC"

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

boolean

افتراضي:"false"

true تحتسب عمليات المسح الفريدة بدلًا من إجمالي عمليات المسح.

يمكنك أيضًا إرسال مرشحات الأبعاد.

النطاقات الزمنية

`interval`	ما يغطيه	فترات `timeseries`
`24h`	آخر 24 ساعة	ساعات
`7d`	آخر 7 أيام، بما فيها اليوم	أيام
`30d`	آخر 30 يومًا، بما فيها اليوم	أيام
`90d`	آخر 90 يومًا، بما فيها اليوم	أيام
`1y`	آخر 365 يومًا، بما فيها اليوم	أشهر
`mtd`	من بداية الشهر حتى اليوم	أيام
`qtd`	من بداية الربع حتى اليوم	أيام
`ytd`	من بداية السنة حتى اليوم	أيام، أو أشهر بعد 180 يومًا
`all`	منذ إنشاء مساحة عملك	أيام، أو أشهر بعد 180 يومًا

لنطاق مخصص، أرسل start وend اختياريًا. تستخدم النطاقات حتى يومين فترات بالساعة، والنطاقات التي تتجاوز 180 يومًا فترات شهرية، وكل ما بينهما فترات يومية.

مرشحات الأبعاد

اقصر النتائج على عمليات المسح المطابقة لمرشح. تُجمع المرشحات المختلفة بـ AND. وعندما يأخذ مرشح عدة قيم، افصل بينها بفواصل: تُجمع القيم بـ OR.

المرشح	القيمة	عدة قيم
`country`	رمز الدولة وفق ISO 3166-1 alpha-2، مثل `US`	نعم
`region`	رمز المنطقة وفق ISO 3166-2، مثل `US-CA`	نعم
`city`	اسم المدينة، مثل `New York`	نعم
`continent`	`AF` أو `AN` أو `AS` أو `EU` أو `NA` أو `OC` أو `SA`	نعم
`device`	نوع الجهاز، مثل `Mobile` أو `Desktop`	نعم
`browser`	اسم المتصفح، مثل `Chrome`	نعم
`os`	نظام التشغيل، مثل `iOS` أو `Windows`	نعم
`url`	رابط الوجهة	نعم
`referer`	المُحيل، مثل `google.com`	لا
`utm_source`، `utm_medium`، `utm_campaign`، `utm_term`، `utm_content`	قيمة UTM، حتى 190 حرفًا	لا

يُرجع رمز الدولة أو القارة غير المعروف 422. تُطابَق أسماء الأجهزة والمتصفحات وأنظمة التشغيل بحرف أول كبير، لذا تعمل mobile مثل Mobile. على سبيل المثال، عمليات المسح من الولايات المتحدة أو كندا على الأجهزة المحمولة: ?country=US,CA&device=Mobile.

التصنيفات

تُرجع count كائنًا. وتُرجع كل قيمة أخرى مصفوفة مرتبة حسب clicks من الأعلى إلى الأدنى (تُرتَّب timeseries حسب الوقت).

`groupBy`	يحتوي كل عنصر على
`count`	`clicks` (كائن، لا مصفوفة)
`timeseries`	`start` (بداية الفترة)، `clicks`
`continents`	`continent`، `clicks`
`regions`	`region`، `country`، `clicks`
`countries`	`country`، `city` (دائمًا `*`)، `clicks`
`cities`	`city`، `country`، `clicks`
`devices`	`device`، `clicks`
`browsers`	`browser`، `clicks`
`os`	`os`، `clicks`
`triggers`	`trigger` (`qr` أو `link`)، `clicks`
`referers`	`referer` (`(direct)` إذا كان غير معروف)، `clicks`
`referer_urls`	`refererUrl` (`(direct)` إذا كان غير معروف)، `clicks`
`top_links`	`id`، `domain`، `key`، `shortLink`، `url`، `createdAt`، `qr` (`id`، `qrType`، `title`)، `clicks`
`top_urls`	`url`، `clicks`
`top_types`	`qr_type`، `clicks`
`utm_sources`، `utm_mediums`، `utm_campaigns`، `utm_terms`، `utm_contents`	قيمة UTM (`utm_source` أو `utm_medium` أو `utm_campaign` أو `utm_term` أو `utm_content`)، `clicks`

تُرجع قيمة groupBy غير المعروفة 422 مع قائمة القيم الصالحة. الاستجابة عند groupBy=count:

{ "clicks": 142 }

الاستجابة عند groupBy=countries:

[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]

الحصول على تحليلات رمز QR

GET /api/v1/qrs/{qrId}/analytics يُرجع إحصائيات المسح لرمز QR واحد، مقصورة على رابطه القصير. يأخذ معاملات الاستعلام ومرشحات الأبعاد المذكورة أعلاه.

string

مطلوب

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

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "clicks": 142
}

الحصول على تحليلات مساحة العمل

GET /api/v1/analytics يُرجع إحصائيات المسح لجميع رموز QR في مساحة عملك. يأخذ معاملات الاستعلام ومرشحات الأبعاد المذكورة أعلاه، إضافةً إلى معاملات النطاق التالية.

string

مع key، يقصر النتائج على الرابط القصير الذي يحمل هذا النطاق، مثل getqr.sh. يجب أن ينتمي النطاق إلى مساحة عملك.

string

المعرّف النصي (slug) للرابط القصير، مثل x7Kd2p1. استخدمه مع domain. كلاهما موجود في كائن رمز QR.

string

أنواع رموز QR المراد تضمينها، مفصولة بفواصل: website أو pdf أو image أو video أو whatsapp أو social أو wifi أو app أو feedback أو vcard أو sms أو payment أو location أو multilink أو email أو event. راجع أنواع QR.

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"

curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"

[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]

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

400 "QR has no associated link."

ليس لرمز QR رابط قصير، لذا لا توجد عمليات مسح تُحتسب.

الخطأ 404 عند التصفية حسب domain وkey

لا يوجد في مساحة عملك رابط قصير بهذا النطاق والمعرّف النصي. انسخ domain وkey من كائن رمز QR.

الخطأ 422 في groupBy أو interval أو أحد المرشحات

القيمة غير مدعومة. تذكر رسالة الخطأ اسم المعامل وتسرد القيم الصالحة.

الأرقام لا تطابق لوحة التحكم

تحقّق من أنك تستخدم النطاق الزمني والمنطقة الزمنية نفسيهما، ومما إذا كنت تحتسب عمليات المسح الفريدة (unique=true) أم إجمالي عمليات المسح.

API

معنى الأرقام

الترويسات

معاملات الاستعلام

النطاقات الزمنية

مرشحات الأبعاد

التصنيفات

الحصول على تحليلات رمز QR

الحصول على تحليلات مساحة العمل

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

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

التقارير

رموز QR