订单状态(强烈建议)

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

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

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

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

API 方式

Base URL

API

URL请求方式Content-Type输出格式字符集
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8
认证参数
字段类型含义建议备注
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业务事件类别必须枚举值:
order_cancel:取消订单
order_payment:支付订单
order_payment_result:订单支付结果
order_ship:订单发货
order_confirm:订单收货
order_return:订单退货
order_refund:订单退款
order_chargeback:订单拒付
terminalTerminal终端信息必须
extExt扩展信息建议与 TD 约定好的扩展信息
业务事件字段

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

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

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

业务事件业务事件类别建议
取消订单order_cancel强烈建议
支付订单order_payment强烈建议,如果已经通过风险验证 API 传递过支付订单等信息则忽略
订单支付结果order_payment_result强烈建议,如果已经通过风险验证 API 传递过支付订单结果等信息则忽略
订单发货order_ship强烈推荐
订单收货order_confirm强烈推荐
订单退货order_return强烈推荐
订单退款order_refund强烈建议
订单拒付order_chargeback强烈建议

请求示例

以订单发货事件为例

{
    "channel": "test",
    "session_id": "abc0123456789",
    "account_id": "123456789",
    "event_time": "2021-10-12T14:20:50.521+07:00",
    "event_type": "order_ship",
    "terminal": {
        "black_box": "aGPH1658920283672ropYaFxT7",
        "ip": "210.20.10.33"
    },
    "ext": {
        "ext_book_id": "LFOUHOFHOHFNOUH",
        "ext_book_num": 10
    },
    "order_id": "NX348566DIHD",
    "logistics": {
        "logistics_type": "Standard Shipping",
        "cost": {
            "currency": "CNY",
            "amount_local": 68,
            "amount_usd": 10,
            "amount_cny": 68
        },
        "logistics_company": "SF"
    }
}

响应参数

字段类型含义建议备注
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"
}