服务端集成 · 报表查询 · 用户订单报表

说明如何通过 Gravity Engine OpenAPI 查询用户付费事件与订单明细数据，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力收集到的用户付费事件数据。

数据更新频率： 数据分钟级更新延迟，高峰期时间可能会变长，极端情况可能会延迟 10 分钟以上。

申请引力开发者应用

在正式接入本接口之前，您需要在引力后台-引力开发者页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。

创建好开发者应用之后，请复制 app_key 参数，并发送给研发同学以供后续接口调用使用。

接口限频

默认接口限频：每 10 秒 10 次。接口限频按开发者应用维度统计，即同一个 app_key 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。

接口信息

请求地址

https://api-insight.gravity-engine.com/openapi/api/v1/report/order/list/

请求方法

POST

字段	类型	描述
Authorization	string	具体如何生成，请参考【签名生成】

body 请求参数

字段	必填	参数类型	描述
`app_id`	Y	number	查询的应用引力 ID，可以在引力后台-应用管理页面获取
`user_filtering`	Y	UserFilterObject	用户默认属性过滤，具体参见 UserFilterObject
`event_filtering`	Y	EventFilterObject	付费事件属性过滤，具体参见 EventFilterObject
`order_by_list`	N	OrderByObject	排序数组，具体参见 OrderByObject
`page`	N	number	查询的页码，从 1 开始
`page_size`	N	number	单页的大小，最大支持 500
`sign`	Y	string	签名，详情请参考【签名生成】

UserFilterObject

用户默认属性过滤

字段	必填	参数类型	描述
`create_date_list`	N	string[]	用户注册时间，如 ["2023-03-01", "2023-03-10"]
`ad_platform_list`	N	string[]	广告平台枚举值，具体详见广告平台枚举
`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

付费事件属性过滤

字段	支持查询类型	参数格式	必填	描述
`Amount`	区间查询和 in 查询	QueryItem	N	订单金额，具体见 QueryItem
`BackAmount`	区间查询和 in 查询	QueryItem	N	实际回传金额，具体见 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 为一个查询单元，其中包含两个字段：

operator：表征查询方式，目前支持 between（范围查询）和 inner（IN 查询）
values：表征传入值，values 为数组

event_filtering 举例如下：

查询订单金额在 5 到 10 之间，并且实际回传金额为 4 或者 5 的数据，其中填入了两个 QueryItem

{
  "Amount": {
    "operator": "between",
    "values": [5, 10]
  },
  "BackAmount": {
    "operator": "inner",
    "values": [4, 5]
  }
}

OrderByObject

如果想在查询时排序，需要传入 order_by_list 参数，其中 order_by_list 为一个数组，数组中的元素为 OrderByObject 类型，OrderByObject 中包含两个字段：

field：排序字段，支持的排序字段参考【排序指标】
sort：排序方式，支持的排序方式有：0（升序）和 1（降序）

order_by_list 具有顺序，会优先按照第一个排序字段进行排序，如果第一个排序字段相同，则按照第二个排序字段进行排序，以此类推。

order_by_list 举例如下：

优先按照付费次数降序，其次按照付费金额升序排序

[
  {
    "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`	回传次数

请求示例

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
    }
  ]
}'

应答参数指标说明

请参考用户订单报表应答字段说明。

应答示例

{
  "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": "成功"
}

用户订单报表