> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# التحليلات

> إحصائيات المسح لرمز QR واحد أو لمساحة عملك بالكامل.

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

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

| الطريقة | المسار | الوصف |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [الحصول على تحليلات رمز QR](#الحصول-على-تحليلات-رمز-qr) |
| `GET` | `/api/v1/analytics` | [الحصول على تحليلات مساحة العمل](#الحصول-على-تحليلات-مساحة-العمل) |

للحصول على ملخص جاهز لكل رمز QR، راجع [التقارير](https://docs.getqr.com/ar/api/endpoints/reports.md).

## معنى الأرقام

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

## الترويسات

**Authorization** `string` *required*

`Bearer` متبوعة بمفتاح API الخاص بك. راجع [المصادقة](https://docs.getqr.com/ar/api/authentication.md).

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

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

**groupBy** `string` (default: count)

بُعد التصنيف. تُرجع `count` الإجمالي. راجع [التصنيفات](#التصنيفات) لكل قيمة وبنية استجابتها.

**interval** `string` (default: 30d)

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

**start** `string`

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

**end** `string`

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

**timezone** `string` (default: UTC)

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

**unique** `boolean` (default: 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`:

```json theme={null}
{ "clicks": 142 }
```

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

```json theme={null}
[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]
```

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

`GET /api/v1/qrs/{qrId}/analytics`

يُرجع إحصائيات المسح لرمز QR واحد، مقصورة على رابطه القصير. يأخذ [معاملات الاستعلام](#معاملات-الاستعلام) و[مرشحات الأبعاد](#مرشحات-الأبعاد) المذكورة أعلاه.

**qrId** `string` *required*

معرّف رمز QR. خذه من استجابة القائمة أو الإنشاء في [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md).

```bash Total scans, last 30 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Unique scans theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash By country, last 7 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "clicks": 142
}
```

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

`GET /api/v1/analytics`

يُرجع إحصائيات المسح لجميع رموز QR في مساحة عملك. يأخذ [معاملات الاستعلام](#معاملات-الاستعلام) و[مرشحات الأبعاد](#مرشحات-الأبعاد) المذكورة أعلاه، إضافةً إلى معاملات النطاق التالية.

**domain** `string`

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

**key** `string`

المعرّف النصي (slug) للرابط القصير، مثل `x7Kd2p1`. استخدمه مع `domain`. كلاهما موجود في [كائن رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md).

**qrType** `string`

أنواع رموز QR المراد تضمينها، مفصولة بفواصل: `website` أو `pdf` أو `image` أو `video` أو `whatsapp` أو `social` أو `wifi` أو `app` أو `feedback` أو `vcard` أو `sms` أو `payment` أو `location` أو `multilink` أو `email` أو `event`. راجع [أنواع QR](https://docs.getqr.com/ar/api/guides/qr-types.md).

```bash Devices, last 7 days theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Devices, website QR codes only theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash One short link theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]
```

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

> [accordion] 400 "QR has no associated link."
>
> ليس لرمز QR رابط قصير، لذا لا توجد عمليات مسح تُحتسب.

> [accordion] الخطأ 404 عند التصفية حسب domain وkey
>
> لا يوجد في مساحة عملك رابط قصير بهذا النطاق والمعرّف النصي. انسخ `domain` و`key` من كائن رمز QR.

> [accordion] الخطأ 422 في groupBy أو interval أو أحد المرشحات
>
> القيمة غير مدعومة. تذكر رسالة الخطأ اسم المعامل وتسرد القيم الصالحة.

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

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

> [card] [التقارير](https://docs.getqr.com/ar/api/endpoints/reports.md)

> [card] [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md)

> [card] [التحليلات في التطبيق](https://docs.getqr.com/ar/analytics/overview.md)

> [card] [حدود الطلبات](https://docs.getqr.com/ar/api/rate-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.