# 用户订单报表 > 来源：https://help.gravity-engine.com/docs/server-integration/reporting/user-order-reports > 说明如何通过 Gravity Engine OpenAPI 查询用户付费事件与订单明细数据，涵盖认证、请求参数、筛选条件和返回字段。 此接口用于获取引力收集到的用户付费事件数据。 **数据更新频率：** 数据分钟级更新延迟，高峰期时间可能会变长，极端情况可能会延迟 10 分钟以上。 ## 申请引力开发者应用 [#申请引力开发者应用] 在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。 创建好开发者应用之后，请复制 `app_key` 参数，并发送给研发同学以供后续接口调用使用。 ## 接口限频 [#接口限频] 默认接口限频：每 10 秒 10 次。接口限频按开发者应用维度统计，即同一个 `app_key` 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。 ## 接口信息 [#接口信息] ### 请求地址 [#请求地址] ```text https://api-insight.gravity-engine.com/openapi/api/v1/report/order/list/ ``` ### 请求方法 [#请求方法] POST ### Header [#header] | 字段 | 类型 | 描述 | | ------------- | ------ | ------------------------------------------------------------- | | Authorization | string | 具体如何生成，请参考 [【签名生成】](/docs/server-integration/request-signing) | ### body 请求参数 [#body-请求参数] | 字段 | 必填 | 参数类型 | 描述 | | ----------------- | -- | ----------------- | -------------------------------------------------------------------------------- | | `app_id` | Y | number | 查询的应用引力 ID，可以在引力后台-[应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面获取 | | `user_filtering` | Y | UserFilterObject | 用户默认属性过滤，具体参见 [UserFilterObject](#userfilterobject) | | `event_filtering` | Y | EventFilterObject | 付费事件属性过滤，具体参见 [EventFilterObject](#eventfilterobject) | | `order_by_list` | N | OrderByObject | 排序数组，具体参见 [OrderByObject](#orderbyobject) | | `page` | N | number | 查询的页码，从 1 开始 | | `page_size` | N | number | 单页的大小，最大支持 500 | | `sign` | Y | string | 签名，详情请参考 [【签名生成】](/docs/server-integration/request-signing) | ### UserFilterObject [#userfilterobject] 用户默认属性过滤 | 字段 | 必填 | 参数类型 | 描述 | | ------------------------------- | -- | --------- | ------------------------------------------------------- | | `create_date_list` | N | string\[] | 用户注册时间，如 \["2023-03-01", "2023-03-10"] | | `ad_platform_list` | N | string\[] | 广告平台枚举值，具体详见 [广告平台枚举](/docs/appendix/ad-platform-enums) | | `channel_list` | N | string\[] | 渠道列表，例如 `['xiaomi', 'huawei']` | | `version_list` | N | number\[] | 版本列表，例如 `[123, 125]` | | `turbo_promoted_object_id_list` | N | string\[] | 引力推广活动 ID 列表 | | `advertiser_id_list` | N | string\[] | 广告账户 ID 列表 | | `gid_list` | N | string\[] | 计划 ID 列表 | | `aid_list` | N | string\[] | 广告 ID 列表 | | `cid_list` | N | string\[] | 创意 ID 列表 | | `wx_openid_list` | N | string\[] | openid 列表 | | `client_id_list` | N | string\[] | 用户 clientID 列表 | ### EventFilterObject [#eventfilterobject] 付费事件属性过滤 | 字段 | 支持查询类型 | 参数格式 | 必填 | 描述 | | ------------------ | ----------- | --------- | -- | ----------------------------------------------------- | | `Amount` | 区间查询和 in 查询 | QueryItem | N | 订单金额，具体见 [QueryItem](#queryitem) | | `BackAmount` | 区间查询和 in 查询 | QueryItem | N | 实际回传金额，具体见 [QueryItem](#queryitem) | | `UploadTime` | 时间区间查询 | string\[] | N | 最近更新时间区间列表，例如 \["2023-01-01", "2023-02-01"]，数组长度必须为 2 | | `PayEventTime` | 时间区间查询 | string\[] | Y | 事件发生时间区间列表，例如 \["2023-01-01", "2023-02-01"]，数组长度必须为 2 | | `Status` | 单选查询 | string | N | 订单状态，`0` 为未回传，`1` 为回传成功，`2` 为回传失败，`3` 为回传跳过；样例："0" | | `PayCount` | 列表查询 | string\[] | N | 当前付费次数，支持传入数组，例如 \["2","3","4"] | | `PostbackCnt` | 列表查询 | string\[] | N | 补报次数，支持传入数组，例如 \["2","3","4"] | | `TraceID` | 列表查询 | string\[] | N | 订单 ID，支持传入数组，例如 \["2","3","4"] | | `event$pay_method` | 列表查询 | string\[] | N | 支付方法，支持传入数组，例如 \["2","3","4"] | | `event$pay_reason` | 列表查询 | string\[] | N | 支付原因，支持传入数组，例如 \["2","3","4"] | #### QueryItem [#queryitem] QueryItem 为一个查询单元，其中包含两个字段： * `operator`：表征查询方式，目前支持 `between`（范围查询）和 `inner`（IN 查询） * `values`：表征传入值，`values` 为数组 `event_filtering` 举例如下： 查询订单金额在 5 到 10 之间，并且实际回传金额为 4 或者 5 的数据，其中填入了两个 QueryItem ```json { "Amount": { "operator": "between", "values": [5, 10] }, "BackAmount": { "operator": "inner", "values": [4, 5] } } ``` ### OrderByObject [#orderbyobject] 如果想在查询时排序，需要传入 `order_by_list` 参数，其中 `order_by_list` 为一个数组，数组中的元素为 `OrderByObject` 类型，`OrderByObject` 中包含两个字段： * `field`：排序字段，支持的排序字段参考【排序指标】 * `sort`：排序方式，支持的排序方式有：`0`（升序）和 `1`（降序） `order_by_list` 具有顺序，会优先按照第一个排序字段进行排序，如果第一个排序字段相同，则按照第二个排序字段进行排序，以此类推。 `order_by_list` 举例如下： 优先按照付费次数降序，其次按照付费金额升序排序 ```json [ { "field": "PayCount", "sort": 1 }, { "field": "Amount", "sort": 0 } ] ``` ### 排序指标 [#排序指标] 目前支持排序的字段如下，其中字符串按照字符串字母排序，数字按照数字大小排序，时间类型按照时间先后排序： | 字段 | 含义 | | ----------------------- | --------------------- | | `ClientID` | client ID | | `AdPlatform` | 媒体平台 | | `Channel` | 渠道 | | `Version` | 客户端版本 | | `TurboPromotedObjectID` | 推广活动 ID | | `WXOpenID` | openid | | `AdvertiserID` | 广告账户 ID | | `AdAid` | 广告 ID | | `PayEventTime` | 事件发生时间 | | `ModifyTime` | 最近更新时间 | | `Amount` | 金额 | | `PayCount` | 当前付费次数 | | `BackAmount` | 实际回传金额 | | `PassStatus` | 条件映射，`0` 为未通过，`1` 为通过 | | `PostbackCnt` | 回传次数 | ### 请求示例 [#请求示例] ```bash curl 'https://backend.gravity-engine.com/openapi/api/v1/report/order/list/' \ -H 'Content-Type: application/json' \ -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MjA3NTg1MzIsImlhdCI6MTcyMDY3MjEzMiwiaXNzIjoicGx1dHVzIiwiZGF550YSI6eyJpZCI6MTIxMzgsIm5hbWUiOiJcdTVmMjBcdTViODdcdTZkMmEiLCJjaWQiOjExMDQ3LCJlbWFpbCI6InpoYW5neWhAbW1oeWdhbWUuY29tIiwiaXNfcmVnaXN0ZXIiOmZhbHNlLCJpc19za2lwIjoxfX0.g35g8CfM3t3TPOA2kD3iGRRd7LnO-OtI8JCKROl-ylk' \ -d '{ "page": 1, "page_size": 20, "app_id": 17802622, "user_filtering": { "create_date_list": ["2024-07-04", "2024-07-11"] }, "event_filtering": { "UploadTime": ["2024-07-10", "2024-07-11"], "Amount": { "operator": "inner", "values": [3, 6] }, "PayCount": ["6"], "BackAmount": { "operator": "between", "values": [4, 10] }, "Status": "1", "TraceID": ["sfsdf"], "event$pay_method": ["xxx"], "event$pay_reason": ["df", "dfsf"], "PostbackCnt": ["555"], "PayEventTime": ["2024-07-11", "2024-07-11"] }, "property_condition": [], "order_by_list": [ { "field": "PayCount", "sort": 1 }, { "field": "Amount", "sort": 0 } ] }' ``` ### 应答参数指标说明 [#应答参数指标说明] 请参考 [用户订单报表应答字段说明](/docs/appendix/user-order-report-metrics)。 ### 应答示例 [#应答示例] ```json { "data": { "page_info": { "page": 1, "page_size": 20, "total_number": 32, "total_page": 2 }, "list": [ { "CreateTime": "2024-07-11 13:17:58", "ClientID": "_000aCURff4NW4CY5Bbjo-swLcvD6gUW8t82NA", "AdPlatform": "", "Channel": "base_channel", "Version": 0, "TurboPromotedObjectID": "default_17802622", "Name": "kk", "WXOpenID": "_000aCURff4NW4CY5Bbjo-swLcvD6gUW8t82NA", "AdvertiserID": "", "AdAid": "", "AdGid": "", "AdCid": "", "CSite": "", "LatestLoginDay": "20240711", "user$ad_24h_avg_ecpm": 0, "user$ad_24h_count": 0, "user$ad_24h_ltv": 0, "user$ad_avg_ecpm": 0, "user$ad_count": 0, "user$ad_ltv": 0, "user$ad_max_ecpm": 0, "user$brand": "VIVO", "user$channel": "base_channel", "user$city": "温州市", "user$country": "中国", "user$first_pay_method": "", "user$first_pay_reason": "", "user$first_pay_time": "2024-07-11 15:32:26", "user$first_scene": "023010", "user$gender": 0, "user$interstitial_ad_24_ltv": 0, "user$interstitial_ad_count": 0, "user$interstitial_ad_ltv": 0, "user$interstitial_ad_max_ecpm": 0, "user$manufacturer": "vivo", "user$model": "vivo", "user$os": "android", "user$pay_amount_sum": 100, "user$pay_count": 1, "user$pay_max_amount": 100, "user$province": "浙江省", "user$reward_ad_24h_ltv": 0, "user$reward_ad_count": 0, "user$reward_ad_ltv": 0, "user$reward_ad_max_ecpm": 0, "user$ta_account_id": 0, "user$ta_distinct_id": 0, "PayEventTime": "2024-07-11 15:32:26", "ModifyTime": "-", "Amount": 100, "PayCount": 1, "BackAmount": 0, "PassStatus": 0, "IsVirtual": 0, "TraceID": "400001_28825236638445517376", "PostbackCnt": 0, "event$is_first_pay": 0, "event$pay_method": 0, "event$pay_reason": 0, "event$brand": 0, "event$os": 0, "event$network_type": 0, "event$ip": "111.1.213.16", "event$browser": "Java", "event$ad_type": 0, "event$ad_unit_id": 0, "event$adn_type": 0, "event$app_crashed_reason": 0, "event$ecpm": 0, "event$event_duration": 0, "event$guide_step": 0, "event$order_id": "400001_28825236638445517376", "event$pay_amount": 100, "event$pay_type": "CNY", "event$scene_name": 0, "event$scene_path": 0, "event$share_depth": 0, "event$share_method": 0, "event$ta_account_id": 0, "event$ta_distinct_id": 0, "event$third_platform_type": 0, "event$url_path": 0, "event$url_query": 0, "Status": "未回传" } ], "total": [ { "user$pay_max_amount": 333, "user$pay_amount_sum": 4444, "Amount": 555, "BackAmount": 666 } ] }, "extra": null, "code": 0, "msg": "成功" } ```