对接教程
本文说明接入优时开放平台的完整流程。接口参数、返回字段及错误码以 接口文档 为准。
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>。
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. 调用示例
以现场取号为例:
-
查询门店:调用
GET /v1/stores,获取可访问的门店及store_id。 -
现场取号:调用
POST /v1/tickets(须签名)。{ "out_ticket_no": "TK202611180001", "store_id": "st_xxxxxxxxxxxxxxxx", "user": { "open_user_id": "u_8823", "mobile": "13800000000" } }out_ticket_no为接入方单号,作为幂等键;user.mobile为必填项,平台以手机号识别顾客。手机号的真实性由接入方负责验证。
-
查询排队进度:调用
GET /v1/tickets/{ticket_id},获取号码状态及前方等待人数ahead_count。
预约流程:依次查询服务项目(/services)与可约时段(/slots),调用 POST /v1/bookings 创建预约;顾客到店后调用签到接口生成排队号码。
6. 重试规则
请求超时或返回 50001 时,处理结果可能未知,应按以下规则处理:
| 场景 | 处理方式 |
|---|---|
| 创建预约、取号 | 使用相同的单号与参数重试,平台保证同一单号仅创建一次 |
返回 40907 |
同一单号的请求处理中,稍后使用相同参数重试 |
返回 40905 |
单号已用于其他参数,新业务须使用新单号 |
| 取消、签到等操作 | 可直接重试,已完成的操作返回成功 |
详见 接口文档 · 幂等。
7. 事件通知
预约与号码的状态变化(如叫号、即将到号、取消、爽约)将推送至回调地址。接收方须:
- 使用
sign_key验证请求头中的X-Sign,拒绝时间戳偏差超过 5 分钟的请求; - 按
event_id去重; - 处理成功后于 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。
