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

# تحليلات رموز QR

> POST /analytics/qr/

يعيد تحليلات المسح المجمّعة لرمز QR واحد أو أكثر، مصنّفة بحسب نوع (أو أنواع) المقياس الذي تطلبه.

<Warning>
  هذه نقطة نهاية **POST فقط** رغم أن الاسم يوحي بعملية بحث — طلب `GET` يعيد `405 Method Not Allowed`. معلمات الاستعلام (`from`، `to`، `type`) تحدد النطاق الزمني والمقاييس؛ نص الطلب يحدد رموز QR المطلوب تضمينها.
</Warning>

<Note>
  يتطلب مفتاح Management API بحصة `MANAGEMENT_API` (أو `MANAGEMENT_API_SANDBOX`) — راجع [نظرة عامة على Management API](/ar/api-reference/management-api/overview) — بالإضافة إلى حصة `QR_ANALYTICS_BASIC` الخاصة بالحساب نفسه. طلب أي شيء يتجاوز مقياس `count` يتطلب إضافيًا `QR_ANALYTICS_ADVANCED`؛ من دونها، يُخفَّض كل طلب بصمت إلى `count` بغض النظر عن `type` الذي طلبته.
</Note>

## الطلب

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://management.scanova.io/analytics/qr/?from=2026-07-01&to=2026-08-16&type=qr' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "q": ["Q07afe81aa0034c01"],
      "filter_by": "qrid"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "qr": [],
    "qr_meta": {
      "docs-v2-first-qr-code": {
        "qrid": "Q07afe81aa0034c01",
        "category": "Website URL",
        "category_slug": "url"
      }
    }
  }
  ```
</ResponseExample>

<Note>
  تم التحقق منه مباشرة على النظام الفعلي — مصفوفة `qr` الفارغة هنا تعكس رمز QR بلا أي عمليات مسح ضمن النافذة الزمنية المطلوبة، وليست خطأً. `qr_meta` هي خريطة إضافية من `name -> {qrid, category, category_slug}`، تُضاف فقط عندما تكون `qr` ضمن `type` المطلوبة، بحيث يمكن للمستدعي الربط من صف مفهرَس بالاسم رجوعًا إلى `qrid` الخاص به. إنها إضافية بحتة: الشكل الذي يحلّله المستدعون بالفعل تحت كل مفتاح مقياس يبقى دون تغيير.
</Note>

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

<ParamField query="from" type="string" required>
  تاريخ البدء (`YYYY-MM-DD`)، شامل.
</ParamField>

<ParamField query="to" type="string" required>
  تاريخ الانتهاء (`YYYY-MM-DD`)، شامل.
</ParamField>

<ParamField query="type" type="string" required>
  أنواع مقاييس مفصولة بفواصل، مثل `qr,device,geography`. القيم الشائعة: `count`، `qr`، `date`، `day`، `time`، `utm`، `device`، `os`، `browser`، `handset`، `geography`، `geo_location`، `age`. يتطلب حصة `QR_ANALYTICS_ADVANCED` الخاصة بالحساب لأي شيء يتجاوز `count`.
</ParamField>

<ParamField query="group" type="string" default="date">
  التجميع لأنواع المقاييس الزمنية المتسلسلة، مثل `date`، `week`، `month`.
</ParamField>

<ParamField query="exclude_bot_scan" type="boolean" default="false">
  يستبعد عمليات المسح المحدَّدة كحركة روبوتات (bot) من النتائج.
</ParamField>

<ParamField query="overview" type="boolean">
  مرِّر `true` للاستدعاءات على غرار نظرة عامة على لوحة التحكم — يتجاوز حد حجم عدد رموز QR/النطاق الزمني الموصوف أدناه، ولا يُحتسب ضمن مؤشر نشاط "التحليلات المسحوبة" الخاص بالحساب.
</ParamField>

### نص الطلب

<ParamField body="q" type="array" required>
  قائمة المعرّفات التي تُحدَّد التحليلات ضمن نطاقها — نوع المعرّف يعتمد على `filter_by`.
</ParamField>

<ParamField body="filter_by" type="string" default="qrid">
  واحد من `qrid` (معرّفات رموز QR)، `id` (المعرّفات الرقمية الداخلية)، `tags` (أسماء الوسوم)، أو `folder` (معرّفات المجلدات).
</ParamField>

### الاستجابة

الاستجابة كائن مفهرس بكل `type` مقياس مطلوب، بالإضافة إلى `qr_meta` عند الاقتضاء (انظر أعلاه). يختلف الشكل حسب نوع المقياس — `count` يعيد إجماليات المسح، و`device`/`os`/`browser`/`geography` تعيد تفصيلات حسب ذلك البُعد، وأنواع السلاسل الزمنية (`date`/`day`/`time`) تعيد سلسلة مقسّمة حسب `group`.

<Warning>
  طلب عدد كبير جدًا من رموز QR ضمن نطاق زمني واسع جدًا يعيد `400` تحت `q`: `"High Volume of data. Either select lower than {N} QR Codes/{N} days time period or generate Analytics Export instead."` عمليًا، كل من [تصدير التحليلات](/ar/api-reference/management-api/analytics/export) و[تصدير التحليلات الخام](/ar/api-reference/management-api/analytics/export-raw) يفرضان الحد نفسه بالضبط — نقاط النهاية الثلاث جميعها تتشارك مسار كود التحقق من صحة الطلب نفسه — لذا الحل الفعلي لهذا الخطأ هو تضييق `q` أو النطاق الزمني، لا التبديل بين نقاط النهاية.
</Warning>

## ذات صلة

* [تصدير التحليلات](/ar/api-reference/management-api/analytics/export) — نزّل النوع نفسه من المقاييس المجمّعة كملف بدلًا من استجابة JSON.
* [تصدير التحليلات الخام](/ar/api-reference/management-api/analytics/export-raw) — نزّل سجلات مسح على مستوى الصف بدلًا من تفصيلات مجمّعة.
* [نظرة عامة على Management API](/ar/api-reference/management-api/overview) — مخطط المصادقة وبنية الحصص التي تنتمي إليها نقطة النهاية هذه.


## OpenAPI

````yaml api-reference/openapi/management-api.json POST /analytics/qr/
openapi: 3.1.0
info:
  title: Scanova Management API (v2)
  description: >-
    The complete Scanova Management API — every endpoint available at
    management.scanova.io (QR codes, folders, tags, leads, forms, analytics,
    plans, shared users & roles), plus the token-creation and usage-stats
    endpoints used to authenticate against it. Every path and request/response
    shape below was verified live against a real API key and the actual running
    backend (Phase 7, 2026-08-16) — not guessed from reading urls.py alone.
  version: 2.0.0
servers:
  - url: https://management.scanova.io
    description: Management API — QR/folder/tag/lead/form/analytics/plans endpoints
security:
  - apiKeyAuth: []
paths:
  /analytics/qr/:
    post:
      summary: QR analytics
      description: >-
        Returns aggregated analytics data. Requires `from` and `to` as query
        parameters (dates) and a `type` query parameter (comma-separated metric
        types, e.g. `qr`). The request body selects which QR codes to include
        via `q` (a list of identifiers) and `filter_by` (which identifier type
        `q` contains — `qrid` is the default; `tags`, `id`, and `folder` are
        also supported). Requesting too many QR codes over too wide a date range
        returns a 400 under `q` — the same volume cap applies to
        /analytics/qr/export/ and /analytics/qr/raw/, which share this
        endpoint's request-validation code.
      operationId: getManagedQrAnalytics
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: type
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated metric types, e.g. `qr`.
        - name: group
          in: query
          schema:
            type: string
            default: date
          description: Grouping for time-series metric types, e.g. date/week/month.
        - name: exclude_bot_scan
          in: query
          schema:
            type: boolean
            default: false
        - name: overview
          in: query
          schema:
            type: boolean
          description: Bypasses the volume cap; used by dashboard overview widgets.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: array
                  items:
                    type: string
                  description: >-
                    Query data — a list of identifiers of the type named in
                    filter_by.
                filter_by:
                  type: string
                  enum:
                    - qrid
                    - tags
                    - id
                    - folder
                  default: qrid
              required:
                - q
            example:
              q:
                - Q07afe81aa0034c01
              filter_by: qrid
      responses:
        '200':
          description: >-
            Analytics data, grouped by the requested type(s). A `qr_meta`
            name->{qrid, category, category_slug} map is attached whenever `qr`
            is among the requested types.
          content:
            application/json:
              example:
                qr: []
                qr_meta:
                  docs-v2-first-qr-code:
                    qrid: Q07afe81aa0034c01
                    category: Website URL
                    category_slug: url
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Send your Management API key as the raw value of the Authorization
        header — no "Bearer " or "Token " prefix, and no other characters.
        Example: `Authorization: 401f7ac837da42b97f613d789819ff93537bee6a`. A
        header containing more than one space-separated part is rejected
        outright. Requests also require the request's Host header to be the
        management API host (e.g. management.scanova.io) — the same key sent to
        the regular API host will not authenticate.

````