API 调用与签名示例
各示例均为单文件、无第三方依赖的客户端,提供以下功能:
sign(sign_key, method, path, timestamp, nonce, body):签名函数,可用于核对接入方自行实现的签名;- 获取并缓存
access_token; request(method, path, query, body):自动携带Authorization并签名;令牌失效(40102)时重新获取并重试一次;- 演示流程:获取令牌 →
GET /v1/stores→POST /v1/tickets(现场取号)。
| 语言 | 文件 | 运行 |
|---|---|---|
| PHP 7.4+(curl 扩展) | client.php | php client.php |
| Java 11+(java.net.http) | YoursOpenClient.java | java YoursOpenClient.java |
| Python 3.7+(标准库) | client.py | python3 client.py |
| Node.js 18+(内置模块及 fetch) | client.js | node client.js |
运行演示
演示要求应用具有 store.read 与 ticket.write 权限。配置通过环境变量传入:
export OPEN_BASE_URL=https://open-api.yours.xyz # 仅包含协议与域名,不含 /v1
export OPEN_APPID=op_xxxxxxxxxxxxxxxx
export OPEN_SECRET=<secret>
export OPEN_SIGN_KEY=<sign_key>
php client.php
输出示例:
获取 token 成功
门店:store_id=st_a1b2c3d4e5f6g7h8 name=优时测试门店
取号成功:ticket_id=tk_k2m9x1q7w4e6r8t0 number=B001 status=waiting ahead_count=0
调用失败时输出 code、msg 与 request_id,退出码为 1。反馈问题时请提供 request_id。
认证流程
- 调用
POST /oauth/token,请求体为{"appid":"...","secret":"...","grant_type":"client_credential"}, 响应为{"code":0,"msg":"ok","data":{"access_token":"...","expires_in":7200},"request_id":"..."}; - 后续请求均携带
Authorization: Bearer <access_token>; - 令牌应在有效期内复用,每日获取次数有上限。多进程或多台服务器部署时,应将令牌存放于共享缓存;刷新后原令牌在 5 分钟内仍然有效。
签名规则
scope 以 .write 结尾的接口(含 GET /v1/stores/{store_id}/tickets)须签名;其他接口签名不影响结果,示例对所有请求签名。
| 请求头 | 说明 |
|---|---|
X-Timestamp |
秒级 Unix 时间戳 |
X-Nonce |
16–64 位随机字符串,仅含字母、数字、_、- |
X-Sign |
签名,64 位小写十六进制 |
签名串 = METHOD + "\n" + path + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + sha256_hex(body)
X-Sign = lower_hex(HMAC-SHA256(sign_key, 签名串))
| 参数 | 说明 |
|---|---|
METHOD |
大写的请求方法,如 POST |
path |
请求路径,不含域名与查询参数,如 /v1/tickets |
body |
实际发送的请求体原始字节;无请求体时为空字符串(sha256_hex("") = e3b0c442...b855) |
字符串均按 UTF-8 编码。
自检命令
各示例均可单独计算签名,用于核对签名实现:
php client.php sign <sign_key> <method> <path> <timestamp> <nonce> <body_file>
java YoursOpenClient.java sign ... # 参数同上
python3 client.py sign ...
node client.js sign ...
<sign_key> 为 - 时从环境变量 OPEN_SIGN_KEY 读取,以避免密钥出现在命令历史与进程列表中。示例:
printf '{"out_ticket_no":"TP1","store_id":"st_a1b2c3d4e5f6g7h8"}' > body.json
OPEN_SIGN_KEY=<sign_key> php client.php sign - POST /v1/tickets 1763260800 0123456789abcdef0123456789abcdef body.json
签名常见问题(40103 / 40104)
- 签名所用请求体须与实际发送的字节完全一致。应先将请求体序列化为字符串,签名与发送使用同一字符串。
path不含查询参数。查询参数不在签名范围内,写接口的参数须放在请求体中。path以实际发送的 URL 编码形式参与签名,不得解码;HTTP 库不得改写路径。path包含/v1前缀;OPEN_BASE_URL仅包含协议与域名。- 时间戳允许偏差 ±300 秒,单位为秒。服务器应开启时间同步。
X-Nonce10 分钟内不得重复。每次发送(含重试)均须生成新的随机字符串与时间戳并重新签名。- 幂等以单号保证。创建类请求重试时须使用相同的
out_ticket_no/out_booking_no。 X-Sign使用小写十六进制;sign_key以原始字符串(UTF-8)作为 HMAC 密钥,不做 Base64 解码。- 无请求体的 POST 请求(如
call-next、checkin)按空字符串签名;发送{}时按{}签名。
回调验签示例
平台推送事件通知时携带以下请求头,接收方须验签:
| 请求头 | 说明 |
|---|---|
X-Timestamp |
秒级时间戳,与接收方服务器时间偏差超过 5 分钟的请求应拒绝 |
X-Nonce |
随机字符串 |
X-Sign |
lower_hex(HMAC-SHA256(sign_key, METHOD + "\n" + path + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + sha256_hex(body))) |
path为请求行中的原始路径(未解码),不含域名与查询参数;body为原始请求体字节;- 处理成功后须于 5 秒内返回 HTTP 200,响应体为
success;否则按 1 分钟、5 分钟、30 分钟、2 小时、6 小时的间隔重试; - 同一事件可能多次推送,应按
event_id去重。
| 语言 | 文件 | 自检命令 |
|---|---|---|
| PHP 7.4+ | verify.php | php verify.php <sign_key> <path> <timestamp> <nonce> <signature> <body_file> |
| Python 3.7+ | verify.py | python3 verify.py ...(参数同上) |
| Node.js 14+ | verify.js | node verify.js ...(参数同上) |
| Java 11+ | WebhookVerify.java | java WebhookVerify.java ...(参数同上) |
验签通过时退出码为 0,否则为 1。
接口调用与请求签名示例见 API 调用与签名示例。
Postman 集合
yours-open.postman_collection.json(Postman Collection v2.1)包含全部对外接口:获取令牌,以及 /v1 下的门店、预约、号码、叫号接口,各请求均附示例参数。
导入与配置
-
在 Postman 中点击 Import,选择
yours-open.postman_collection.json; -
在集合「优时开放平台 v1」的 Variables 中填写:
变量 说明 base_url协议与域名(可含端口),不含 /v1,如https://open-api.yours.xyzappid应用 appid secret应用 secret sign_key签名密钥 date预约及时段查询日期(门店当地日期 YYYY-MM-DD)secret、sign_key建议仅填写在 Current value 中(不同步至 Postman 云端); -
按目录顺序发送请求。
集合功能
| 功能 | 说明 |
|---|---|
| 自动获取令牌 | 集合使用 Bearer {{access_token}} 认证;令牌为空或即将过期时,集合级脚本自动调用 /oauth/token |
| 自动签名 | 为除获取令牌外的所有请求添加 X-Timestamp、X-Nonce、X-Sign,规则见 API 调用与签名示例 |
| 自动保存 ID | 门店列表、服务项目、可约时段、创建预约、现场取号、叫下一位等请求将返回的 ID 保存为集合变量,供后续请求引用 |
| 单号 | out_booking_no / out_ticket_no 使用 {{request_no}},每次发送前重新生成 |
使用限制
- 请求体中不得使用
{{$timestamp}}、{{$randomInt}}、{{$guid}}等动态变量:签名与发送时分别取值,将导致签名错误(40103)。随机值请使用{{request_no}}; - 路径中的特殊字符须使用 URL 编码后的形式;
- 请求体须为 raw / JSON 格式;
- 本机时间与服务器偏差超过 300 秒时返回 40104,须开启自动对时;
- 签到仅可在时段开始前 60 分钟至开始后 15 分钟内、预约当天调用;号码取消后不可再叫号;
- 更换应用后,须清空
access_token或将access_token_expires_at设为 0。
