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

# 二维码分析

> POST /analytics/qr/

返回一个或多个二维码的聚合扫描分析数据，按您请求的一个或多个指标类型进行分组。

<Warning>
  尽管名称听起来像是一次查询，这实际上是一个**仅支持 POST** 的端点——`GET` 请求会返回 `405 Method Not Allowed`。查询参数（`from`、`to`、`type`）用于选择日期范围和指标；请求体则用于选择要包含哪些二维码。
</Warning>

<Note>
  需要一个拥有 `MANAGEMENT_API`（或 `MANAGEMENT_API_SANDBOX`）配额的 Management API 密钥——参见 [Management API 概览](/zh/api-reference/management-api/overview)——以及账户自身的 `QR_ANALYTICS_BASIC` 配额。请求 `count` 指标以外的任何内容还需要 `QR_ANALYTICS_ADVANCED`；若没有该配额，无论您请求的 `type` 是什么，请求都会被静默降级为 `count`。
</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_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`。请求 `count` 以外的任何内容都需要账户的 `QR_ANALYTICS_ADVANCED` 配额。
</ParamField>

<ParamField query="group" type="string" default="date">
  时间序列型指标类型的分组方式，例如 `date`、`week`、`month`。
</ParamField>

<ParamField query="exclude_bot_scan" type="boolean" default="false">
  从结果中排除被识别为机器人流量的扫描。
</ParamField>

<ParamField query="overview" type="boolean">
  传入 `true` 以用于仪表盘概览风格的调用——绕过下文所述的二维码数量/日期范围数据量限制，且不计入账户的"已获取分析数据"活跃度信号。
</ParamField>

### 请求体

<ParamField body="q" type="array" required>
  用于限定分析范围的标识符列表——标识符的类型取决于 `filter_by`。
</ParamField>

<ParamField body="filter_by" type="string" default="qrid">
  `qrid`（二维码 ID）、`id`（内部数字 ID）、`tags`（标签名称）或 `folder`（文件夹 ID）之一。
</ParamField>

### 响应

响应是一个以每个请求的指标 `type` 为键的对象，如适用还会包含 `qr_meta`（见上文）。数据结构因指标类型而异——`count` 返回扫描总数，`device`/`os`/`browser`/`geography` 返回按该维度的细分数据，而时间序列类型（`date`/`day`/`time`）则返回按 `group` 分桶的序列数据。

<Warning>
  请求过多二维码或过宽的日期范围，会在 `q` 字段下返回一个 `400` 错误：`"High Volume of data. Either select lower than {N} QR Codes/{N} days time period or generate Analytics Export instead."` 实际上，[导出分析数据](/zh/api-reference/management-api/analytics/export)和[导出原始分析数据](/zh/api-reference/management-api/analytics/export-raw)都强制执行完全相同的限制——三个端点共享同一套请求校验代码路径——因此这个错误的真正解决办法是缩小 `q` 或日期范围，而不是切换端点。
</Warning>

## 相关内容

* [导出分析数据](/zh/api-reference/management-api/analytics/export) —— 将同类聚合指标下载为文件，而不是获取 JSON 响应。
* [导出原始分析数据](/zh/api-reference/management-api/analytics/export-raw) —— 下载逐行的扫描记录，而不是聚合后的细分数据。
* [Management API 概览](/zh/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.

````