优时开放平台 控制台
开发文档 / 对接教程

对接教程

本文说明接入优时开放平台的完整流程。接口参数、返回字段及错误码以 接口文档 为准。

1. 接入准备

接入前,请与平台运营确认以下事项:

事项 说明
合作商户 应用所服务的商户。每个应用绑定一个商户,仅可访问该商户的门店
所需能力 如门店与时段查询、预约、现场取号、门店叫号,平台运营据此开通相应权限(scope)
服务器出口 IP 用于配置 IP 白名单,白名单以外的请求将被拒绝
回调地址 用于接收事件通知,须为可从公网访问的 HTTPS 地址

平台提供以下环境:

环境 用途
沙箱环境 联调测试,使用模拟数据
正式环境 正式业务

两套环境的应用与凭证相互独立,接口、签名规则及错误码一致。

2. 获取应用凭证

应用开通后,平台运营将提供以下凭证:

凭证 用途
appid 应用标识
secret 换取访问令牌(access_token),须严格保密
sign_key 请求签名与回调验签,须严格保密
  • secret 与 sign_key 仅在创建或重置时展示一次,须保存在服务端,不得写入客户端或前端代码;
  • 凭证存在泄露风险时,应由商户管理员在 控制台 重置,或联系平台运营处理。

3. 获取访问令牌

POST /oauth/token HTTP/1.1
Content-Type: application/json

{"appid":"op_xxxxxxxxxxxxxxxx","secret":"<secret>","grant_type":"client_credential"}

响应示例:

{"code":0,"msg":"ok","data":{"access_token":"at_...","expires_in":7200},"request_id":"req_..."}
  • 访问令牌有效期为 2 小时,应在服务端缓存并于到期前刷新;每个应用每日获取次数有上限;
  • 刷新后,原令牌在 5 分钟内仍然有效;
  • 调用业务接口时,在请求头中携带 Authorization: Bearer <access_token>。

详见 接口文档 · 获取 access_token。

4. 请求签名

写操作(创建预约、取号、取消、签到、叫号等)须进行请求签名:

X-Sign = lower_hex( HMAC-SHA256( sign_key,
           METHOD + "\n" + path + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + sha256_hex(body) ) )
参数 要求
path 请求路径,不含域名及查询参数,如 /v1/tickets
body 实际发送的请求体原文,签名与发送须使用同一内容
X-Timestamp 秒级时间戳,与服务器时间偏差不超过 5 分钟
X-Nonce 随机字符串,10 分钟内不得重复

各语言的实现见 示例代码,示例提供签名自检命令。详见 接口文档 · 请求签名。

5. 调用示例

以现场取号为例:

  1. 查询门店:调用 GET /v1/stores,获取可访问的门店及 store_id。

  2. 现场取号:调用 POST /v1/tickets(须签名)。

    {
      "out_ticket_no": "TK202611180001",
      "store_id": "st_xxxxxxxxxxxxxxxx",
      "user": { "open_user_id": "u_8823", "mobile": "13800000000" }
    }
    
    • out_ticket_no 为接入方单号,作为幂等键;
    • user.mobile 为必填项,平台以手机号识别顾客。手机号的真实性由接入方负责验证。
  3. 查询排队进度:调用 GET /v1/tickets/{ticket_id},获取号码状态及前方等待人数 ahead_count。

预约流程:依次查询服务项目(/services)与可约时段(/slots),调用 POST /v1/bookings 创建预约;顾客到店后调用签到接口生成排队号码。

6. 重试规则

请求超时或返回 50001 时,处理结果可能未知,应按以下规则处理:

场景 处理方式
创建预约、取号 使用相同的单号与参数重试,平台保证同一单号仅创建一次
返回 40907 同一单号的请求处理中,稍后使用相同参数重试
返回 40905 单号已用于其他参数,新业务须使用新单号
取消、签到等操作 可直接重试,已完成的操作返回成功

详见 接口文档 · 幂等。

7. 事件通知

预约与号码的状态变化(如叫号、即将到号、取消、爽约)将推送至回调地址。接收方须:

  1. 使用 sign_key 验证请求头中的 X-Sign,拒绝时间戳偏差超过 5 分钟的请求;
  2. 按 event_id 去重;
  3. 处理成功后于 5 秒内返回 HTTP 200,响应体为 success。

未成功响应的通知将按 1 分钟、5 分钟、30 分钟、2 小时、6 小时的间隔重试。

门店开启短信通知时,平台将向顾客发送叫号、即将到号、预约提醒等短信,接入方可据此确定自身的通知策略。

详见 接口文档 · 回调通知,验签代码见 示例代码。

8. 沙箱联调

  • 沙箱环境地址及测试应用凭证由平台运营提供;
  • 沙箱使用模拟门店与数据,不影响正式业务;
  • 联调事件通知时,可由平台运营在沙箱中模拟取号、叫号、过号、完成等操作。

9. 上线检查

  • 凭证仅保存在服务端,日志中不记录 secret、sign_key 及访问令牌;
  • 访问令牌已缓存并于到期前刷新;
  • 写操作的签名、时间戳与随机字符串正确,服务器时间已同步;
  • 创建类接口在超时或返回 50001 时使用相同单号重试;
  • 事件通知已验签、按 event_id 去重,并于 5 秒内返回 success;
  • 已验证顾客手机号;
  • 正式环境已配置 IP 白名单与回调地址;
  • 以响应中的 code 判断结果,并记录 request_id。

10. 常见问题

返回 40103(签名错误) 使用示例代码的自检命令,以相同输入计算签名并比对。常见原因:签名所用请求体与实际发送内容不一致、路径包含查询参数、sign_key 含多余字符。

返回 40104(请求已过期或重复提交) 检查服务器时间是否准确,以及每次请求是否使用新的 X-Nonce。

返回 40303(IP 不在白名单内) 将服务器出口 IP 加入应用的 IP 白名单(商户管理员可在控制台配置)。

返回 40908(超出每人限额) 同一手机号在同一门店最多有 3 个待到店预约,当天最多有 1 个未结束的号码,通过本平台接入的各应用合并计算。

问题反馈 请提供响应中的 request_id、请求时间及 appid。