ADX客户余额与日消耗API对接文档

v1.0.0

1. 概述

ADX 需求方余额 OpenAPI 的对接方式说明如下：

接口	路径	说明
查询需求方余额	/openApi/dspInfo/balance	查询当前需求方余额
查询需求方日消耗	/openApi/dspInfo/dailyConsume	按天返回需求方客户消耗数据

2. 通用说明

2.1 请求方式

• 请求方法：POST
• Content-Type：application/json
• 请求体格式：JSON

2.2 环境地址

环境	地址
正式环境	https://ad.adintl.cn

3. 接口详情

3.1 查询需求方余额

查询当前账号授权范围内所有需求方（DSP）的实时余额。

• 请求路径： POST /openApi/dspInfo/balance

请求参数

参数	类型	必填	说明
userName	String	是	登陆章鱼平台账号
authCode	String	是	授权码见章鱼平台右上角

请求示例

{
  "userName": "testUser",
  "authCode": "5f8d7a3b9c2e4f1a8d6b0c4e2f9a1b7d"
}

响应参数（result）

参数	类型	说明
result	JSONArray	余额列表
result[].dspName	String	需求方名称
result[].dspId	String	需求方ID
result[].balance	BigDecimal	余额，单位元

响应示例

{
  "success": true,
  "message": "",
  "code": 200,
  "result": [
      {
        "dspId": "1",
        "dspName": "示例DSP",
        "balance": 100000
      },
      {
        "dspId": "2",
        "dspName": "示例DSP2",
        "balance": 0
      }
],
  "timestamp": 1711111111111
}

说明

• 无余额记录的需求方 balance 返回 0。
• 若账号未关联任何 DSP，result 返回空数组。

3.2 查询需求方日消耗

按天返回账号授权范围内所有需求方（DSP）的客户结算数据。

• 请求路径： POST /openApi/dspInfo/dailyConsume

请求参数

参数	类型	必填	说明
userName	String	是	登陆章鱼平台账号
authCode	String	是	授权码见章鱼平台右上角
dspId	String	否	指定需求方 ID。传入时只查询该 DSP，且必须为账号已关联的 DSP，否则返回错误
startDate	String	是	查询起始日期，格式 yyyy-MM-dd
endDate	String	是	查询结束日期，格式 yyyy-MM-dd

查询范围限制： 起止日期跨度（含起止当天）最多 7 天，超出范围返回错误

请求示例

{
  "userName": "testUser",
  "authCode": "5f8d7a3b9c2e4f1a8d6b0c4e2f9a1b7d",
  "dspId":"1",
  "startDate": "2026-08-01",
  "endDate": "2026-08-06"
}

响应参数（result）

参数	类型	说明
startDate	String	查询起始日期
endDate	String	查询结束日期
dailyConsumes	JSONArray	日消耗列表
dailyConsumes[].date	String	日期，格式 yyyy-MM-dd
dailyConsumes[].dspId	String	需求方 ID
dailyConsumes[].requestCount	long	请求数
dailyConsumes[].fillCount	long	填充数
dailyConsumes[].impCount	long	曝光数
dailyConsumes[].clkCount	long	点击数
dailyConsumes[].consume	double	消耗金额，单位：元

响应示例

{
  "success": true,
  "message": "success",
  "code": 200,
  "result": {
    "startDate": "2026-08-01",
    "endDate": "2026-08-06",
    "dailyConsumes": [
      {
        "date": "2026-08-01",
        "dspId": "1",
        "requestCount": 10000,
        "fillCount": 8000,
        "impCount": 6000,
        "clkCount": 300,
        "consume": 50000
      },
      {
        "date": "2026-08-02",
        "dspId": "1",
        "requestCount": 0,
        "fillCount": 0,
        "impCount": 0,
        "clkCount": 0,
        "consume": 0
      }
    ]
  },
  "timestamp": 1711111111111
}

说明

• 无数据的日期返回全 0。
• 若账号未关联任何 DSP，dailyConsumes 返回空数组。

4. 错误码与错误信息

场景	code	message
鉴权失败（账号不存在 / authCode 错误 / 参数缺失）	500	授权无效
触发频率限制	500	请求过于频繁，请稍后再试
起止日期格式错误或缺失	500	起止日期格式错误，应为yyyy-MM-dd
结束日期早于起始日期	500	结束日期不能早于起始日期
查询日期范围超过 7 天	500	查询日期范围不能超过7天

错误响应示例：

{
  "success": false,
  "message": "授权无效",
  "code": 500,
  "result": null,
  "timestamp": 1711111111111
}

5. 对接注意事项

1. 请控制调用频率（单接口单账号每分钟不超过 20 次），建议合理设置轮询间隔。
2. 金额单位统一为元（yuan），前端展示时请注意换算。
3. 日期参数必须符合 yyyy-MM-dd 格式，例如 2026-08-01。
4. 接口仅返回账号授权范围内的 DSP 数据。