> ## 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.

# التقارير

> صدّر تقرير مسح لمرة واحدة أو جدوِل رسائل بريد إلكتروني دورية بالتقارير.

> [!NOTE]
>
> 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}` | [حذف تقرير مجدول](#حذف-تقرير-مجدول) |

## الترويسات

**Authorization** `string` *required*

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

**Content-Type** `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`

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

**scope** `string` *required*

`all` أو `selected` أو `single`. راجع [النطاق](#النطاق).

**period** `string` *required*

`daily` أو `weekly` أو `monthly`. راجع [الفترة](#الفترة).

**format** `string` *required*

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

**qrIds** `string[]`

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

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

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

**locale** `string` (default: en)

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

**name** `string`

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

### استجابة JSON

**periodStart** `string`

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

**periodEnd** `string`

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

**qrs** `object[]`

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

**properties**

**qrId** `string`

معرّف رمز QR.

**name** `string`

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

**type** `string`

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

**totalScans** `integer`

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

**uniqueScans** `integer`

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

**topGeography** `string`

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

**topDevice** `string`

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

**topOs** `string`

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

**topBrowser** `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`.

```bash JSON theme={null}
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"
  }'
```

```bash PDF theme={null}
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
```

```json 200 theme={null}
{
  "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"
    }
  ]
}
```

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

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

**id** `string`

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

**name** `string | null`

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

**frequency** `string`

`daily` أو `weekly` أو `monthly`.

**scope** `string`

`all` أو `selected` أو `single`.

**qrIds** `string[] | null`

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

**filters** `null`

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

**includePdf** `boolean`

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

**status** `string`

`active` أو `paused`.

**timezone** `string`

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

**locale** `string`

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

**nextRunAt** `string`

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

**lastRunAt** `string | null`

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

**createdAt** `string`

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

**updatedAt** `string`

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

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

`GET /api/v1/reports/schedules`

يُرجع التقارير المجدولة في مساحة عملك، بما فيها التي أنشأها أعضاء آخرون، الأحدث أولًا. القائمة مقسّمة إلى صفحات: راجع [ترقيم الصفحات](https://docs.getqr.com/ar/api/introduction.md#ترقيم-الصفحات).

**page** `integer` (default: 1)

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

**pageSize** `integer` (default: 100)

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

```bash cURL theme={null}
curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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` من التكرار والمنطقة الزمنية.

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

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

**frequency** `string` *required*

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

**scope** `string` *required*

`all` أو `selected` أو `single`. راجع [النطاق](#النطاق).

**timezone** `string` *required*

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

**locale** `string` *required*

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

**qrIds** `string[]`

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

**name** `string`

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

**includePdf** `boolean` (default: false)

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

```bash cURL theme={null}
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"
  }'
```

```json 200 theme={null}
{
  "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`.

**id** `string` *required*

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

**status** `string`

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

**name** `string`

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

**frequency** `string`

`daily` أو `weekly` أو `monthly`.

**scope** `string`

`all` أو `selected` أو `single`.

**qrIds** `string[]`

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

**includePdf** `boolean`

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

**timezone** `string`

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

**locale** `string`

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

```bash cURL theme={null}
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"
  }'
```

```json 200 theme={null}
{
  "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}`

يحذف الجدول ويوقف كل رسائل البريد الإلكتروني اللاحقة.

> [!WARNING]
>
> لا يمكن التراجع عن حذف تقرير مجدول.

**id** `string` *required*

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

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }
```

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

> [accordion] الخطأ 404 عند تصدير تقرير
>
> مع النطاق `selected` أو `single`، لم يطابق أي من `qrIds` رمز QR له رابط قصير في مساحة عملك. تحقّق من المعرّفات.

> [accordion] 404 "QR not found." عند جدولة تقرير
>
> أحد `qrIds` ليس رمز QR في مساحة عملك، أو أنه حُذف. تحقّق من المعرّفات باستخدام [عرض قائمة رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md).

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

> [accordion] 404 "Scheduled report not found."
>
> لا يطابق `id` أي تقرير مجدول في مساحة عملك. خذه من [عرض قائمة التقارير المجدولة](#عرض-قائمة-التقارير-المجدولة).

> [accordion] التقرير لا يتضمن عمليات المسح اليوم
>
> لا تغطي التقارير إلا آخر فترة مكتملة. استخدم [التحليلات](https://docs.getqr.com/ar/api/endpoints/analytics.md) للأرقام الفورية.

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

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

> [card] [التقارير المجدولة في التطبيق](https://docs.getqr.com/ar/analytics/scheduled-reports.md)

> [card] [قراءة التقارير](https://docs.getqr.com/ar/analytics/reading-reports.md)

> [card] [الأخطاء](https://docs.getqr.com/ar/api/errors.md)


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