订单 BI 聚合查询

POST /v2/order/analytics 使用与其他 Open API v2 接口相同的渠道签名。接口返回订单聚合值,不返回订单明细或用户信息。需要查看具体订单时,再按需调用 /v2/order/search。

可通过 订单分析 API Demo 查看聚合概览与每日趋势的页面示例。Demo 使用浏览器内合成数据;真实接入需要由合作方服务端签名调用 Open API。

统计口径

请求体

字段 必填 说明
filter.bookedAt 是 [开始时间, 结束时间],推荐 ISO 8601 带时区格式;结束时间不包含在内。要包含整段日期,可将结束时间设为最后一天的次日 00:00
groupBy 否 单个分组或最多两个不同分组的数组:none(默认)、day、month、city、hotel、channel;none 不与其他分组组合
preferred.currency 否 金额指标的币种:CNY(默认)、USD、JPY;数量指标无币种
preferred.language 否 分组名称语言:zh(默认)、en、ja;ja 暂回退英文名称
paging.skip / paging.limit 否 除单独按 day 分组外均可使用;skip 默认 0,limit 默认 10、最大 20

不接受城市、酒店等其他筛选条件,也不接受自定义 Mongo criteria、advancedCriteria、channelRef、userRef 或任意排序参数。未知字段、无效时间和超出限制的分页参数会报错。

示例

请求:POST /v2/order/analytics;按 认证与签名 提供请求头。

{
  "preferred": { "currency": "CNY" },
  "filter": { "bookedAt": ["2026-10-01T00:00:00+08:00", "2026-11-01T00:00:00+08:00"] },
  "groupBy": "day"
}

响应结构示例(数值仅用于说明字段):

{
  "currency": "CNY",
  "groupBy": "day",
  "period": { "from": "2026-10-01T00:00:00+08:00", "to": "2026-11-01T00:00:00+08:00" },
  "rows": [{ "date": "2026-10-01", "totalAmount": { "amount": 1234.56, "currency": "CNY" }, "averageOrderAmount": { "amount": 617.28, "currency": "CNY" }, "orderCount": 2, "totalNights": 5, "averageOrderNights": 2.5 }],
  "hasMore": false
}

按渠道和日期组合分组时,传 "groupBy": ["channel", "day"],并可传 "paging": { "skip": 0, "limit": 20 }。响应的每行同时包含 channel 和 date,例如 { "channel": { "_id": "...", "key": "partner", "name": "合作渠道" }, "date": "2026-10-01", ... }。

rows 包含所选分组和全部五个指标:按天为 date(YYYY-MM-DD),按月为 month(YYYY-MM),按城市为 city(包含 _id 和 name),按酒店为 hotel(包含 _id 和 name),按渠道为 channel(包含 _id、key 和 name);组合分组时每行同时包含两个分组字段,响应中的 groupBy 保持请求的数组形式。不分组时没有分组字段。金额指标 totalAmount、averageOrderAmount 使用 amount 和 currency 对象,数量指标 orderCount、totalNights、averageOrderNights 为数字。没有订单命中的日期或维度组合不返回行;若要显示连续日期,客户端可补零。响应中的 period 对应请求的 filter.bookedAt 范围。

错误处理

接口沿用 Open API 的错误响应格式,错误信息位于 err.message。例如缺少 filter.bookedAt、时间字符串无效、结束时间不晚于开始时间、paging.limit 超过 20、单独按天分组传入 paging,或传入 metric、channelRef、criteria 等未开放字段,都会在聚合查询前返回错误。签名无效、渠道未开通或该渠道未获接口权限时,按现有 Open API 鉴权规则返回错误。

{ "err": { "message": "paging.limit 必须为 1 至 20" } }