广告主投放状态通知接口

用于将广告投放状态变更通知给广告主或合作方。回调地址由接收方提供，发送方按照约定的签名规则发送 HTTP 请求。

对接信息

项目	说明
请求地址	由接收方提供的回调地址
请求方法	HTTP POST
请求格式	JSON
字符编码	UTF-8
签名方式	MD5

投放动作

`action`	含义
`start`	开始投放
`stop`	停止投放

请求参数

请求体为 JSON 对象：

参数名	类型	必选	说明
`report_key`	string	是	广告主收入分配键，用于标识需要变更状态的投放链接
`action`	string	是	投放动作，取值为 `start` 或 `stop`
`timestamp`	integer	是	Unix 时间戳，单位为秒
`sign`	string	是	签名结果，32 位小写十六进制 MD5 字符串

请求示例：

{
  "report_key": "demo_report_key",
  "action": "start",
  "timestamp": 1790000000,
  "sign": "由签名规则计算得到的 32 位小写 MD5"
}

签名规则

签名密钥由双方约定，接收方需要使用与发送方相同的密钥校验签名。签名生成规则为：

sign = hex(md5(report_key + action + timestamp + secret))

其中：

report_key、action 和 secret 按原始字符串拼接，中间不添加分隔符。
timestamp 使用十进制 Unix 时间戳字符串，不要转换为毫秒。
拼接结果按 UTF-8 编码后计算 MD5。
sign 使用 MD5 的小写十六进制结果。

Python 示例：

import hashlib
import time

report_key = "demo_report_key"
action = "start"
timestamp = int(time.time())
secret = "demo_secret"

sign = hashlib.md5(
    f"{report_key}{action}{timestamp}{secret}".encode("utf-8")
).hexdigest()

签名校验

接收方处理请求时应依次完成以下校验：

校验 action 是否为 start 或 stop。
校验时间戳与当前时间的差值是否不超过 300 秒。超出 5 分钟的请求应视为无效。
使用相同的 report_key、action、timestamp 和共享密钥重新计算签名。
将计算结果与请求中的 sign 进行完整比较，校验通过后再处理投放状态。

参考实现：

import hashlib
import hmac
import time


def verify_sign(
    report_key: str,
    action: str,
    timestamp: int,
    secret: str,
    sign: str,
) -> bool:
    if abs(time.time() - timestamp) > 300:
        return False

    expected = hashlib.md5(
        f"{report_key}{action}{timestamp}{secret}".encode("utf-8")
    ).hexdigest()
    return hmac.compare_digest(expected, sign)

响应与安全建议

本通知协议未定义响应体格式，接收方可在成功接收并处理后返回 HTTP 2xx 状态码。
签名密钥仅用于双方服务端，不要放入 URL、前端代码或日志中。
回调地址建议使用 HTTPS，并确保发送方与接收方的系统时间同步。
接收方应按 report_key、action 和 timestamp 做必要的幂等处理；本协议未定义重试策略。