优时开放平台 控制台
开发文档 / 示例代码

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。

认证流程

  1. 调用 POST /oauth/token,请求体为 {"appid":"...","secret":"...","grant_type":"client_credential"}, 响应为 {"code":0,"msg":"ok","data":{"access_token":"...","expires_in":7200},"request_id":"..."};
  2. 后续请求均携带 Authorization: Bearer <access_token>;
  3. 令牌应在有效期内复用,每日获取次数有上限。多进程或多台服务器部署时,应将令牌存放于共享缓存;刷新后原令牌在 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)

  1. 签名所用请求体须与实际发送的字节完全一致。应先将请求体序列化为字符串,签名与发送使用同一字符串。
  2. path 不含查询参数。查询参数不在签名范围内,写接口的参数须放在请求体中。
  3. path 以实际发送的 URL 编码形式参与签名,不得解码;HTTP 库不得改写路径。
  4. path 包含 /v1 前缀;OPEN_BASE_URL 仅包含协议与域名。
  5. 时间戳允许偏差 ±300 秒,单位为秒。服务器应开启时间同步。
  6. X-Nonce 10 分钟内不得重复。每次发送(含重试)均须生成新的随机字符串与时间戳并重新签名。
  7. 幂等以单号保证。创建类请求重试时须使用相同的 out_ticket_no / out_booking_no。
  8. X-Sign 使用小写十六进制;sign_key 以原始字符串(UTF-8)作为 HMAC 密钥,不做 Base64 解码。
  9. 无请求体的 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 下的门店、预约、号码、叫号接口,各请求均附示例参数。

导入与配置

  1. 在 Postman 中点击 Import,选择 yours-open.postman_collection.json;

  2. 在集合「优时开放平台 v1」的 Variables 中填写:

    变量 说明
    base_url 协议与域名(可含端口),不含 /v1,如 https://open-api.yours.xyz
    appid 应用 appid
    secret 应用 secret
    sign_key 签名密钥
    date 预约及时段查询日期(门店当地日期 YYYY-MM-DD)

    secret、sign_key 建议仅填写在 Current value 中(不同步至 Postman 云端);

  3. 按目录顺序发送请求。

集合功能

功能 说明
自动获取令牌 集合使用 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。