订单 BI 聚合查询
POST /v2/order/analytics 使用与其他 Open API v2 接口相同的渠道签名。接口返回订单聚合值,不返回订单明细或用户信息。需要查看具体订单时,再按需调用 /v2/order/search。
可通过 订单分析 API Demo 查看聚合概览与每日趋势的页面示例。Demo 使用浏览器内合成数据;真实接入需要由合作方服务端签名调用 Open API。
统计口径
- 目前只统计酒店订单(tpHotel),状态为已确认或已完成(内部状态 4、5)。
- filter.bookedAt 与订单搜索的双端范围一样按订单创建时间筛选,包含开始时刻、不包含结束时刻。分析接口要求同时传入两个时间。推荐使用带时区的 ISO 8601 时间;按天、月分组仍以北京时间(UTC+08:00)划分。不限制时间跨度。
- 单独按天分组返回范围内全部有订单的日期,不支持 paging;其他分组(含组合分组)使用 paging 分页,每页最多 20 行,超过时 hasMore 为 true。包含 day 或 month 的分组按日期及其他维度升序,其他分组按总金额降序。
- groupBy 可以传单个分组或最多两个不同分组的数组,例如
["channel", "day"]。每行对应实际有订单的维度组合,不补齐没有订单的组合;none不与其他分组组合。 - totalAmount 和 averageOrderAmount 使用订单保存的 CNY、USD 或 JPY 含税预订金额,不按当前汇率换算;averageOrderAmount 是每单平均预订金额。orderCount、totalNights、averageOrderNights 为无币种数量,averageOrderNights 是每单平均晚数。
请求体
| 字段 | 必填 | 说明 |
|---|---|---|
| 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" } }