API Reference
English

活动状态(建议)

活动状态 API 是 TD 系统的一个关键功能,旨在确保获取活动信息的准确性和及时性。

通过活动状态 API,我们能够准确识别更加狡猾的欺诈者,这些欺诈者巧妙地运用正常身份和行为,以规避关键业务节点的检测,从而欺骗系统。仅凭单一的业务行为判断往往难以揭示欺诈者的真实意图。

此外,活动状态 API 的应用将提高我们对正常用户偶发异常行为的准确识别能力,从而在降低误报率的同时提升活动转化率。我们在一般业务节点对用户进行无感知的数据上报,并在关键业务节点做出决策。这种设计有助于减少对用户的干扰,提升用户体验。

通过活动状态 API ,我们能够确保 TD 系统始终获取到最新的活动信息,进而提升系统的安全性和可靠性。

API 方式

Base URL

API

URL请求方式Content-Type输出格式字符集
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

示例:https://cn-event.apitd.net/activity/v3?partner_code=test_code&partner_key=test_key

认证参数
字段类型含义建议备注
partner_codeString合作方标识必须由 TD 分配
partner_keyString合作方密钥必须由 TD 分配

请求参数

一次完整的请求参数通常由两部分字段组成:

  1. 基础字段:这些字段包含了与请求本身相关的基本信息,旨在确保请求的合法性和安全性。
  2. 业务事件字段:这些字段与活动状态有关,例如营销、领券等业务事件。通过这些字段,我们能够传递与特定业务事件相关的数据,如营销信息、优惠券信息等。

将基础字段和业务事件字段结合起来,构成了一次完整的请求参数。这样的设计使得我们能够有效地传递和处理与活动状态相关的业务事件数据,确保活动信息的准确性和安全性。

基础字段
字段类型含义建议备注
channelString渠道标识必须由 TD 分配
session_idString会话 ID必须会话 ID 是网站服务器为特定用户在访问期间分配的唯一标识,通常可以用 Cookie、表单字段或 URL 的形式存储
account_idString账户 ID条件必须:当账户注册(创建)后必须当账户不存在时可不传
event_timeString业务事件真实发生时间必须符合 ISO 8601 标准,格式 YYYY-MM-DDTHH:mm:ss.sssZ ,例如 2021-10-12T14:20:50.521+07:00
event_typeString业务事件类别必须枚举值:
marketing:营销
marketing_code:扫码
marketing_exchange:兑奖
send_gift:送礼
get_coupon:领券
withdraw:提现
invite:邀请
sms:短信
browse:浏览
activate:激活
lookup:查询
like:点赞
comment:评论
favorite:收藏
terminalTerminal终端信息必须
extExt扩展信息建议与 TD 约定好的扩展信息
业务事件字段

我们的 API 设计限制了每次请求只能涉及一个业务事件的数据。这意味着您无法同时发起多个不同的业务事件数据请求,例如营销和提现。

为了确保数据的准确性和系统的可靠性,我们建议您按照业务事件的独立性,分别发送业务事件请求。通过单独处理每个业务事件,我们能够更好地管理和跟踪数据的处理过程,避免混淆和冲突。

遵守这一规则将有助于提高系统的性能和可靠性,并确保每个业务事件都能得到正确处理。如果您需要同时处理多个不同的业务事件,我们建议您分别发送独立的请求,以确保数据的完整性和一致性。

业务事件业务事件类别建议
营销marketing强烈建议,如果已经通过风险验证 API 传递过营销信息则忽略
扫码marketing_code强烈建议,如果已经通过风险验证 API 传递过扫码信息则忽略
兑奖marketing_exchange强烈建议,如果已经通过风险验证 API 传递过兑奖信息则忽略
送礼send_gift强烈建议,如果已经通过风险验证 API 传递过送礼信息则忽略
领券get_coupon强烈建议,如果已经通过风险验证 API 传递过领券信息则忽略
提现withdraw强烈建议,如果已经通过风险验证 API 传递过提现信息则忽略
邀请invite强烈建议,如果已经通过风险验证 API 传递过邀请信息则忽略
短信sms强烈建议,如果已经通过风险验证 API 传递过短信信息则忽略
浏览browse强烈建议,如果已经通过风险验证 API 传递过浏览信息则忽略
激活activate强烈建议,如果已经通过风险验证 API 传递过激活信息则忽略
查询lookup强烈建议,如果已经通过风险验证 API 传递过查询信息则忽略
点赞like强烈建议,如果已经通过风险验证 API 传递过点赞信息则忽略
评论comment强烈建议,如果已经通过风险验证 API 传递过评论信息则忽略
收藏favorite强烈建议,如果已经通过风险验证 API 传递过收藏信息则忽略

请求示例

以领券事件为例

{
    "channel": "test",
    "session_id": "abc0123456789",
    "account_id": "123456789",
    "event_time": "2021-10-12T14:20:50.521+07:00",
    "event_type": "get_coupon",
    "terminal": {
        "black_box": "aGPH1658920283672ropYaFxT7",
        "ip": "210.20.10.33"
    },
    "ext": {
        "ext_book_id": "LFOUHOFHOHFNOUH",
        "ext_book_num": 10
    },
    "coupon": {
        "coupon_id": "NOHF08938",
        "coupon_name": "双十一限时购",
        "coupon_count": 1,
        "begin_time": 1596358039000,
        "expire_time": 1616358039000,
        "coupon_type": "discount",
        "coupon_rate": 0.85,
        "coupon_threshold": "10",
        "cash_back_amount": {
            "currency": "CNY",
            "amount_local": 68,
            "amount_usd": 10,
            "amount_cny": 6.8
        }
    }
}

响应参数

字段类型含义建议备注
codeIntegerAPI 状态码必须
messageString状态信息必须在 API 异常状态下会输出具体的异常原因
sequence_idString响应唯一码必须用于跟踪每次请求记录的唯一标识

API 状态码

code含义
200成功
9001{字段名}为空
9002{字段名}参数校验错误
9003{字段名}参数长度或者大小超过1024
9004black_box或ip至少存在一个
9200系统异常
9201未知异常
9202content-type不合法

响应示例

{
    "code": 200,
    "message": "",
    "sequence_id": "1648777165770866F82AC7F326307055"
}