## 订单 (`orders`)

充值、扣款、在线支付与套餐购买产生的订单;租户只见本租户,管理员可跨租户,订单只许改备注。

鉴权: 用户（部分参数仅管理员） · 文档: https://www-demo.kuxitong.com/zh/docs/api/orders

### GET `/api/v2/orders`

列出订单 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |
| `type` | string |  | 按订单类型过滤(recharge/deduct/payment/package 等)。 |
| `status` | string |  | 按状态过滤。 可选值: ["unpaid","paid"] |
| `start` | string |  | 下单时间起(含),RFC 3339。 |
| `end` | string |  | 下单时间止(不含),RFC 3339。 |

```sh
curl "https://panel.example.com/api/v2/orders" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/orders/stats`

订单金额统计 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |
| `type` | string |  | 按订单类型过滤(recharge/deduct/payment/package 等)。 |
| `status` | string |  | 按状态过滤。 可选值: ["unpaid","paid"] |
| `start` | string |  | 下单时间起(含),RFC 3339。 |
| `end` | string |  | 下单时间止(不含),RFC 3339。 |
| `group_by` | string |  | 汇总粒度,缺省 day。 可选值: ["day","month","year"] |
| `utc_offset_minutes` | integer |  | 已废弃,仅为兼容旧调用方保留(仍校验取值范围)。日/月/年恒按平台时区(Asia/Shanghai)切分,与今日流量同一日界,不再随此参数平移。 |

```sh
curl "https://panel.example.com/api/v2/orders/stats" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/orders/{id}`

获取订单 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/orders/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/orders/{id}`

改订单备注 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `des` | string | 有 | 备注说明 |

```sh
curl -X PUT "https://panel.example.com/api/v2/orders/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"des":"线下转账已核对"}'
```

订单对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `amount_cents` | integer |  | 金额(分),扣款单为负。 |
| `archived` | boolean |  | 已被归档任务搬进档案表(只读)。 |
| `created_at` | string |  | 创建时间 (只读) |
| `data` | object |  | 附加数据(如套餐购买明细)。 |
| `des` | string |  | 备注说明 |
| `group_by` | string |  | 汇总粒度:day、month 或 year。 可选值: ["day","month","year"] |
| `id` | integer |  | 记录 ID (只读) |
| `items` | OrderStatsItem[] |  | 本页条目 |
| `ledger_id` | integer |  | 关联的账户流水 ID;没有则为空。 |
| `mch_order_no` | string |  | 商户订单号(网关侧订单号);非在线支付为空。 |
| `paid_at` | string |  | 付款时间;未付款为空。 |
| `pay_type` | string |  | admin/balance/alipay/wxpay 等;空 = 未付款。 |
| `status` | string |  | 订单状态:unpaid 待付款、paid 已付款。 可选值: ["unpaid","paid"] |
| `tenant_id` | integer |  | 所属租户(用户)ID (只读) |
| `transaction_id` | string |  | 网关侧交易号;未付款为空。 |
| `type` | string |  | recharge(管理员充值)/deduct(管理员扣款)/payment(在线支付)/package(套餐)等。 |
| `updated_at` | string |  | 更新时间 (只读) |