订单事件推送

通过订单事件推送接口，oTMS系统将订单的各类事件（如状态更新、节点变更等）主动推送到客户预先配置的指定接收服务中。此为反向调用接口，即由 oTMS 作为客户端发起请求，外部系统作为服务端接收数据。

对方系统在接收到推送请求后，应按照约定的响应格式及时返回相应的确认信息。

接口说明

方向: 反向调用（oTMS → 外部系统）

配置说明

URL配置: 客户需要提供一个可公网访问的HTTPS服务地址（URL），用于接收oTMS的推送请求。该地址需在oTMS后台进行配置。

认证: 可根据需要配置Basic Auth、Token或IP白名单等安全验证机制。

环境: 支持正式环境和沙箱环境，需分别配置对应的接收地址。

注意: 请确保您提供的接收服务具备足够的处理能力和稳定性，以应对oTMS的推送压力。如果发现接收方服务异常（如频繁超时、错误响应），oTMS可能会暂停推送以保护系统稳定。

身份认证

默认情况下，oTMS 的订单事件推送请求不包含任何身份认证信息。为增强安全性，客户系统可以要求对推送来源进行身份验证。为此，需要实现一个获取 Token 的接口，并在 oTMS 系统中进行配置。

实现流程

客户系统提供 Token 接口：

客户需开发并部署一个 HTTPS 接口，供 oTMS 调用以获取访问令牌 (Token)。

该接口必须支持 POST 请求方法。

在 oTMS 中配置 Token 接口地址：

在 oTMS 管理后台，配置客户提供的 Token 获取接口的 URL。

配置格式：[客户Token接口URL]#[header] k=v&k2=v2

#header# 是分隔符，oTMS 系统会自动解析其后的参数。

k=v&k2=v2 是客户自定义的键值对，oTMS 在调用 Token 接口时会将这些键值作为 HTTP Header 发送。

建议：客户可将 k 和 v 设置为加密后的值（如使用 Base64 编码或更复杂的加密算法），以提高安全性。

oTMS 获取 Token：

当事件推送任务启动时，oTMS 会首先向客户配置的 Token 接口发起 POST 请求。

oTMS 会将配置的 k=v&k2=v2 解析并添加到请求的 HTTP Header 中。

客户系统收到请求后，验证 Header 中的 k 和 v 值是否正确。

验证通过后，返回一个包含有效 Token 的 JSON 响应。

事件推送携带 Token：

oTMS 成功获取 Token 后，会将其附加到后续的每一次事件推送请求中。

附加方式：将 Token 作为查询参数 (query parameter) 添加到原始的事件推送 URL 后。

格式：[原始推送URL]?token=XXX

客户系统验证 Token：

客户系统在接收到 oTMS 的事件推送请求时，从 URL 参数中提取 token 值。

验证该 Token 是否有效（例如，检查是否过期、是否在有效列表中等）。

验证通过则处理事件数据，否则拒绝请求。

Token 接口响应格式

{
  "data": {
    "token": "your_generated_token_string"
  }
}

•过期时间：oTMS 默认认为获取到的 Token 有效期为 1小时。过期后，oTMS 会自动重新调用 Token 接口获取新的 Token。
示例假设客户配置如下：
•Token 接口 URL: https://your-system.com/api/getToken#[header] authKey=abc123&secret=xyz789
•事件推送接收 URL: https://your-system.com/api/receiveOrderEvents
步骤一：oTMS 获取 TokenPOST https://your-system.com/api/getToken
Headers:
  authKey: abc123
  secret: xyz789

Response:
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}
步骤二：oTMS 推送事件PUT https://your-system.com/api/receiveOrderEvents?token=eyJhbGciOiJIUzI1NiIs...
Body: <event data>
推送策略
•组合频率: 每10秒内发生的订单事件会被组合成一次请求进行推送。
•请求上限: 单个推送请求中最多包含250个订单事件。
•重试机制: 
•采用触发式推送。
•若推送失败（如网络问题、服务无响应、返回非成功状态码），oTMS会进行重试。
•最多重试 5次。
•每次重试间隔为 10分钟。
请求参数
字段名    位置    是否必填    描述    Schema    
body    body    是    订单消息推送请求，包含一个或多个订单的事件数据列表    EventList    
响应反馈代码当接收方系统处理完推送请求后，需要返回以下代码以告知 oTMS 处理结果：
反馈代码    说明    
0    成功。接收方已成功处理所有事件。    
1    部分成功。建议在响应体中详细说明哪些订单处理成功，哪些失败。    
99    失败。接收方处理过程中发生严重错误，无法处理本次请求。    
重要提示：与常规API不同，此接口是 oTMS 主动向外部系统发起调用。因此，HTTPS请求地址是由接收方系统提供并配置在 oTMS 中的，而不是一个固定的 otms.cn 地址。

订单事件推送