优时开放平台 对外接口文档(v1)
本文档面向接入优时开放平台的第三方开发者(以下简称「接入方」),说明 access_token 获取、请求签名、预约取号接口调用及回调通知接收。
字段、取值及错误码以本文档为准。兼容性变更(新增字段、新增接口)不升级版本,接入方须忽略无法识别的字段。不兼容变更将发布
/v2,旧版本保留不少于 6 个月,并提前通知。
目录
1. 概述
1.1 环境地址
| 环境 | 地址 |
|---|---|
| 正式环境 | https://open-api.yours.xyz |
| 沙箱环境 | https://sandbox-api.yours.xyz |
本文所列路径均相对于环境地址,例如
POST https://open-api.yours.xyz/oauth/token、GET https://open-api.yours.xyz/v1/stores。开发者中心与商户控制台地址为https://open.yours.xyz。
仅 /oauth/token 与 /v1/* 对外开放。所有接口仅支持 HTTPS。
1.2 基本概念
| 概念 | 说明 |
|---|---|
| 应用 | 接入方在平台上的接入身份。每个应用绑定一个商户,绑定后不可更换;仅可访问该商户的门店,以及本应用创建的预约和号码 |
appid |
应用标识,格式为 op_ + 16 位小写字母或数字,如 op_8f3k2m9x1q7w4e6r。可公开 |
secret |
40 位字母数字,仅用于获取 access_token。仅在创建或重置时展示一次,须保存在服务端 |
sign_key |
40 位字母数字,仅用于请求签名和回调验签。仅在创建或重置时展示一次,须保存在服务端 |
access_token |
调用 /v1 接口的凭证,格式为 at_ + 40 位字母数字,有效期 2 小时 |
| scope | 应用获授的权限,见 4.6 |
1.3 接入流程
- 申请应用:联系平台运营创建应用。平台运营负责绑定商户、开通所需 scope,并按需配置 IP 白名单、回调地址、限流额度和预约配额。接入方获得
appid、secret、sign_key。 - 沙箱联调:使用平台运营提供的测试 appid,在沙箱环境完成获取 token、签名、调用接口、接收回调的全流程(见第 8 节)。
- 配置正式环境:商户管理员可在商户控制台查看调用日志和回调日志、重置
secret/sign_key、配置 IP 白名单和回调地址、停用应用。scope、限流和配额由平台运营调整。 - 上线:切换至正式环境地址和凭证。
调用 /v1 接口的步骤:
1. POST /oauth/token(appid + secret)→ access_token,服务端缓存,到期前刷新
2. 请求头携带 Authorization: Bearer <access_token>
3. 写接口(以及路由 scope 以 .write 结尾的接口)另须携带 X-Timestamp / X-Nonce / X-Sign
4. 检查响应的 code:0 表示成功,其他值见错误码
2. 获取 access_token
POST /oauth/token
Content-Type: application/json
本接口无需 Authorization 头,无需签名。
2.1 请求参数(JSON 请求体)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appid |
string | 是 | 应用 appid |
secret |
string | 是 | 应用 secret |
grant_type |
string | 是 | 固定为 client_credential |
appid、secret 长度均不超过 128 个字符。
2.2 响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
access_token |
string | at_ + 40 位字母数字 |
expires_in |
int | 有效期(秒),目前为 7200 |
响应头包含 Cache-Control: no-store、Pragma: no-cache。
2.3 示例
请求:
POST /oauth/token HTTP/1.1
Host: open-api.yours.xyz
Content-Type: application/json
{"appid":"op_8f3k2m9x1q7w4e6r","secret":"<secret>","grant_type":"client_credential"}
响应:
{
"code": 0,
"msg": "ok",
"data": {
"access_token": "at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP",
"expires_in": 7200
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
2.4 使用规则
- 有效期 2 小时。接入方须在服务端缓存 token,到期前刷新,不得每次请求均重新获取。
- 刷新:获取新 token 后,该应用此前的所有 token 在 5 分钟内失效(剩余有效期不足 5 分钟的,按原到期时间失效)。多台服务器须共用同一 token(如存放于共享缓存),不得各自获取,否则将导致彼此的 token 提前失效。
- 每日获取次数:每个 appid 每日最多获取 200 次,超出返回
42902。按平台服务器时区的自然日计算。 - 防暴力破解:同一 appid 或同一来源 IP 在 15 分钟内累计 10 次
appid 或 secret 错误,将被临时封禁 15 分钟,封禁期间返回42901。 - 立即失效:应用停用或重置
secret后,该应用的所有 token 立即失效(返回40102),须使用新 secret 重新获取。 - 应用的 scope、IP 白名单、限流等配置变更后立即生效,无需重新获取 token。
- 配置 IP 白名单后,
/oauth/token同样仅接受白名单内 IP 的请求(凭证正确但 IP 不在白名单内时返回40303)。
2.5 可能的错误码
| code | 场景 |
|---|---|
40001 |
缺少 appid 或 secret(空值视为缺少;data.errors 指明字段) |
40002 |
请求体不是 JSON 对象;grant_type 不为 client_credential;appid / secret 超长(后两种情况在 data.errors 中指明字段) |
40101 |
appid 或 secret 错误 |
40303 |
应用已配置 IP 白名单,请求 IP 不在其中 |
40304 |
应用已停用 |
40305 |
所绑定商户不可用(已停用或冻结) |
40902 |
所绑定商户已关闭预约取号 |
42901 |
认证失败次数过多,已被临时封禁 |
42902 |
当日获取 token 次数超限 |
50001 |
系统繁忙,请稍后重试 |
3. 请求签名
请求签名用于防止请求被篡改和重放。
3.1 哪些请求需要签名
满足以下任一条件的 /v1 请求须签名:
- HTTP 方法不是
GET/HEAD(即本文所有POST接口); - 接口所需 scope 以
.write结尾,与 HTTP 方法无关。目前属于此情况的 GET 接口仅有GET /v1/stores/{store_id}/tickets(call.write)。
各接口是否需要签名,见 5.0 接口总览 的「签名」列。无需签名的请求携带签名头时,签名头将被忽略,不会报错。
3.2 请求头
| 请求头 | 格式 | 说明 |
|---|---|---|
X-Timestamp |
纯数字 | 当前 Unix 时间戳(秒),与平台服务器时间偏差不得超过 300 秒 |
X-Nonce |
[A-Za-z0-9_-],16–64 位 |
随机串,每个请求均不相同。同一应用的 nonce 10 分钟内不得重复 |
X-Sign |
64 位十六进制 | 签名值,按 3.3 计算,使用小写 |
3.3 计算方法
string_to_sign = METHOD + "\n"
+ path + "\n"
+ X-Timestamp + "\n"
+ X-Nonce + "\n"
+ sha256_hex(body)
X-Sign = lower_hex( HMAC-SHA256( key = sign_key, message = string_to_sign ) )
| 部分 | 说明 |
|---|---|
METHOD |
大写 HTTP 方法,如 POST、GET |
path |
请求路径,不含域名及查询参数(? 及之后部分),须与请求行中的原始路径完全一致(不得解码或改写),如 /v1/bookings、/v1/stores/st_8k2m4q7x1z9w3e5r/tickets |
X-Timestamp、X-Nonce |
与请求头中的值完全一致 |
sha256_hex(body) |
原始请求体字节的 SHA-256,小写十六进制。请求体为空时,使用空串的 SHA-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
规则:
- 摘要须基于实际发送的请求体字节计算:先将 JSON 序列化为字符串,以该字符串计算签名并原样发送;不得在计算签名后由 HTTP 库重新序列化(键顺序、空格、中文是否转义为
\uXXXX均会改变摘要)。 - 查询参数不参与签名。写接口的参数须全部置于 JSON 请求体中,平台不读取写接口的查询参数。
- 校验顺序:签名头格式 → 时间戳 → 签名 → nonce 是否重复。nonce 仅在签名校验通过后登记,签名错误的请求不占用 nonce。
3.4 签名计算示例
以下数值由平台签名实现计算得出,可用于验证接入方的签名实现。
示例 1:POST 请求(创建预约)
| 输入 | 值 |
|---|---|
| sign_key | k3Zb8QvN2xLp7RtY5wHc9JmE4sGd6FaU1oKi0nBr |
| METHOD | POST |
| path | /v1/bookings |
| X-Timestamp | 1794965400(2026-11-18T09:30:00+08:00) |
| X-Nonce | n8Kq2xV7mZp4Lw9RtY3c |
| body(共 200 字节,无换行和多余空格) | {"out_booking_no":"TP202611180001","store_id":"st_8k2m4q7x1z9w3e5r","service_id":"sv_3n6p8r1t4v7x9z2b","date":"2026-11-18","start_time":"10:00","user":{"open_user_id":"u_8823","mobile":"13800000000"}} |
中间结果:
sha256_hex(body) = f7ba4682fd40abf9ce416a89ff37ff3a0c35cc2169dd305efdfa1416f49e2060
string_to_sign(4 个 \n 分隔,末尾没有换行):
POST
/v1/bookings
1794965400
n8Kq2xV7mZp4Lw9RtY3c
f7ba4682fd40abf9ce416a89ff37ff3a0c35cc2169dd305efdfa1416f49e2060
结果:
X-Sign = 79a7d5a80953f282278a0ba2318ac19b37f90502f33b52bd7ed1abadad6fbfe5
示例 2:带查询参数的 GET 请求、空请求体(叫号排队列表)
请求为 GET /v1/stores/st_8k2m4q7x1z9w3e5r/tickets?status=waiting,sign_key 同示例 1:
| 输入 | 值 |
|---|---|
| METHOD | GET |
| path | /v1/stores/st_8k2m4q7x1z9w3e5r/tickets(不含 ?status=waiting) |
| X-Timestamp | 1794965460 |
| X-Nonce | Q4wE7rT1yU5iO9pA2sD6 |
| body | 空 |
string_to_sign:
GET
/v1/stores/st_8k2m4q7x1z9w3e5r/tickets
1794965460
Q4wE7rT1yU5iO9pA2sD6
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Sign = 6388b5fdb1fd2362c55d5bab5b571fee993ff5ce443f30cb59c118564e996f2f
PHP 参考实现:
function yours_open_sign(string $signKey, string $method, string $path, string $timestamp, string $nonce, string $body): string
{
$stringToSign = strtoupper($method) . "\n" . $path . "\n" . $timestamp . "\n" . $nonce . "\n" . hash('sha256', $body);
return hash_hmac('sha256', $stringToSign, $signKey);
}
其他语言(Java、Python、Node.js)实现见 examples/sign/。
3.5 签名相关错误
| code | 场景 |
|---|---|
40103 |
签名头缺失或格式错误(时间戳非纯数字、nonce 不符合格式、X-Sign 不是 64 位十六进制);签名不匹配 |
40104 |
时间戳与服务器时间偏差超过 300 秒;nonce 在 10 分钟内重复使用 |
收到 40104 时,请检查服务器时钟(建议启用 NTP),并确保每次请求(含重试)均生成新的 nonce 和时间戳。
4. 通用约定
4.1 请求格式
- 所有
/v1请求须携带Authorization: Bearer <access_token>。 - 写接口的参数置于 JSON 请求体中,须携带
Content-Type: application/json,编码为 UTF-8。请求体须为 JSON 对象;无参数的写接口可发送空请求体。 - 查询接口的参数置于查询字符串中。
- 请求体中未定义的字段将被忽略。
4.2 响应格式
所有接口(含出错时)均返回 JSON:
{
"code": 0,
"msg": "ok",
"data": {},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
| 字段 | 类型 | 说明 |
|---|---|---|
code |
int | 0 表示成功,其他值见错误码 |
msg |
string | 通用说明文案,不得用于程序判断,请以 code 为准 |
data |
object | null | 成功时为业务数据(对象);出错时通常为 null,参数校验失败时见下文 |
request_id |
string | 本次请求的唯一编号,与响应头 X-Request-Id 的值相同。反馈问题时请提供 |
HTTP 状态码:成功时为 200;出错时为 code 的前三位(code / 100 取整),例如 40102 → 401,40903 → 409,42901 → 429,50001 → 500。
参数校验错误:部分参数错误在 data.errors 中按字段给出提示(提示文案仅供排查,可能调整):
{
"code": 40001,
"msg": "参数缺失",
"data": { "errors": { "store_id": "必填", "date": "必填" } },
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
部分参数错误不返回 data.errors(如创建预约时 start_time 不是可约时段),请以 code 为准。
4.3 时间与时区
- 每个门店有独立时区,门店详情返回
timezone(IANA 名称,如Asia/Shanghai、Asia/Tokyo)。 - 时间点(
created_at、called_at、checkin_deadline、回调的occurred_at等)均为 ISO 8601 格式,带时区偏移,精确到秒,以门店时区表示,如2026-11-18T10:30:00+08:00、2026-11-18T11:30:00+09:00。 - 日期(
date)格式为YYYY-MM-DD,时间(start_time、end_time)格式为HH:MM(24 小时制),均为门店当地日期和时间。请求中传入的date、start_time同样按门店时区解释。 - 营业时间的
close可能为24:00,表示营业至当日结束。
4.4 对外 ID
平台仅返回对外 ID,不返回任何内部 ID。对外 ID 格式为「前缀 + 16 位小写字母或数字」:
| 前缀 | 对象 | 示例 |
|---|---|---|
st_ |
门店 | st_8k2m4q7x1z9w3e5r |
sv_ |
服务项目 | sv_3n6p8r1t4v7x9z2b |
bk_ |
预约 | bk_5h7j9k2l4m6n8p1q |
tk_ |
号码 | tk_2c4e6g8i1k3m5o7q |
- 预约和号码的 ID 按应用分别生成:同一号码在不同应用中的
ticket_id不同。接口返回的 ID 与回调中的 ID 一致。 - ID 须作为不透明字符串保存,不得解析。格式不合法的 ID 按「不存在」处理(门店返回
40401,预约 / 号码返回40402)。
4.5 数据范围
- 门店:仅可访问所绑定商户的门店。访问其他门店(含不存在的门店)均返回
40401。 - 预约、号码:仅可访问本应用创建的预约及本应用取的号码。访问其他数据均返回
40402。 - 例外:持有
call.write的应用可查看并操作所绑定商户门店所有渠道的号码(见 5.5)。
4.6 权限(scope)
| scope | 能力 |
|---|---|
store.read |
查询门店、服务项目、时段、排队状态 |
booking.read |
查询本应用创建的预约 |
booking.write |
创建、取消预约,签到 |
ticket.read |
查询本应用取的号码 |
ticket.write |
现场取号、取消号码 |
call.write |
查看门店完整排队列表,叫号、过号、完成(仅向门店自有系统开放) |
调用未授权的接口返回 40301。
4.7 鉴权顺序
每个 /v1 请求依次执行以下检查,任一步骤失败即返回对应错误码:
| 顺序 | 检查 | 失败时 |
|---|---|---|
| 1 | access_token 是否有效 | 40102 |
| 2 | 应用是否启用;所绑定商户是否可用、是否开通预约取号 | 40304 / 40305 / 40902 |
| 3 | IP 白名单(已配置时检查) | 40303 |
| 4 | 限流与日调用量 | 42901 / 42902 |
| 5 | 请求签名(需签名的接口) | 40103 / 40104 |
| 6 | scope | 40301 |
| 7 | 接口参数及业务校验 | 见各接口 |
签名错误、权限不足的请求同样计入调用量。未知路径或请求方法不匹配时直接返回 40400,不执行上述检查。
4.8 限流与配额
| 限制 | 范围 | 默认值 | 超出时 |
|---|---|---|---|
| 应用 QPS | 每个应用每秒请求数 | 20(平台运营可按应用调整) | 42901 |
| 平台全局 QPS | 整个平台 | — | 42901 |
| 日调用量 | 每个应用每日的 /v1 请求数 |
100000(平台运营可按应用调整) | 42902 |
| 预约配额 | 每个应用在「同一门店 + 同一预约日期」可创建的预约数 | 200(平台运营可按应用调整) | 40906 |
| 获取 token | 每个 appid 每日 | 200 | 42902 |
- 应用的具体额度请向平台运营确认。
- 日计数按平台服务器时区的自然日计算。
- 预约配额:预约被取消(用户取消、门店取消、系统取消)或爽约后归还;因业务错误创建失败的请求不占用配额。
- 收到
42901时,须降低调用频率后重试(建议采用指数退避)。
4.9 IP 白名单
- 应用可配置 IP 白名单(单个 IP 或 CIDR,支持 IPv4 / IPv6)。配置后,白名单外的请求(含
/oauth/token)返回40303;未配置时不做限制。 - 白名单由平台运营或商户管理员(商户控制台)配置。
4.10 分页
所有列表接口目前一次返回全部数据,不支持分页参数。列表数据位于 data.items。
4.11 幂等(创建类接口)
创建预约(POST /v1/bookings)和现场取号(POST /v1/tickets)须传入接入方单号作为幂等键:out_booking_no / out_ticket_no。
- 单号格式:字母、数字、
_、-,1–64 位。 - 单号在本应用内唯一;预约单号与取号单号相互独立。
- 使用同一单号重复请求时,处理规则如下:
| 情况 | 结果 |
|---|---|
| 之前已成功,参数相同 | 返回首次创建成功时的响应 data,不重复创建。该数据为首次创建时的快照,不反映最新状态;最新状态须调用查询接口获取 |
| 参数与之前不同 | 40905(单号已被使用且参数不一致) |
| 之前的请求仍在处理中 | 40907(请求处理中),请稍后使用相同的单号和参数重试 |
之前因业务错误失败(如 40901 约满、40902、40904、40401) |
视为未创建,单号可重新使用 |
- 「参数是否相同」的比较字段:预约为
store_id、service_id、date、start_time、user(open_user_id、mobile、name)、remark;取号为store_id、service_id、user。与字段顺序无关;未传与传空串视为相同。 - 超时或收到
50001时:结果可能未知(平台可能已创建成功)。须使用相同的单号和参数重试,不得更换单号,否则可能重复创建:- 60 秒内重试可能返回
40907,请稍后重试; - 处理时间超过 60 秒的请求,可由相同单号的重试接管处理并返回最终结果。
- 60 秒内重试可能返回
其他写接口(取消、签到、叫号等)不使用单号,重试规则见各接口说明。
4.12 状态枚举
预约状态 status
| 值 | 说明 |
|---|---|
pending |
待到店 |
checked_in |
已签到(已生成号码进入排队) |
completed |
已完成(签到生成的号码已完成) |
cancelled |
已取消 |
no_show |
爽约(超过签到截止时间未签到) |
pending ──签到──▶ checked_in ──号码完成──▶ completed
│ └──号码被取消──▶ cancelled
├──取消(用户、门店或系统)──▶ cancelled
└──超过签到截止时间──▶ no_show
号码状态 status
| 值 | 说明 |
|---|---|
waiting |
排队中 |
called |
已叫号 |
completed |
已完成 |
skipped |
过号 |
cancelled |
已取消 |
waiting ──叫号──▶ called ──完成──▶ completed
│ │ ▲
│ │ └─重新叫号
│ └──过号──▶ skipped ──重新叫号──▶ called
└──取消──▶ cancelled
号码类型 type:walk_in 现场取号,booking 预约签到生成。
取消方 cancelled_by:user 用户取消(含通过开放平台接口取消),store 门店取消,system 系统取消;未取消时为 null。门店当日营业结束后,排队中 / 已叫号 / 过号的号码由系统取消(cancelled_by = system),对应的已签到预约同时取消。
5. 接口列表
5.0 接口总览
| 方法 | 路径 | scope | 签名 | 说明 |
|---|---|---|---|---|
| GET | /v1/stores |
store.read |
否 | 门店列表 |
| GET | /v1/stores/{store_id} |
store.read |
否 | 门店详情 |
| GET | /v1/stores/{store_id}/queue |
store.read |
否 | 排队状态 |
| GET | /v1/stores/{store_id}/services |
store.read |
否 | 服务项目列表 |
| GET | /v1/stores/{store_id}/slots |
store.read |
否 | 可约时段 |
| POST | /v1/bookings |
booking.write |
是 | 创建预约 |
| GET | /v1/bookings/{booking_id} |
booking.read |
否 | 查询预约 |
| POST | /v1/bookings/{booking_id}/cancel |
booking.write |
是 | 取消预约 |
| POST | /v1/bookings/{booking_id}/checkin |
booking.write |
是 | 到店签到 |
| POST | /v1/tickets |
ticket.write |
是 | 现场取号 |
| GET | /v1/tickets/{ticket_id} |
ticket.read |
否 | 查询号码 |
| POST | /v1/tickets/{ticket_id}/cancel |
ticket.write |
是 | 取消号码 |
| GET | /v1/stores/{store_id}/tickets |
call.write |
是 | 门店完整排队列表 |
| POST | /v1/stores/{store_id}/call-next |
call.write |
是 | 叫下一位 |
| POST | /v1/tickets/{ticket_id}/recall |
call.write |
是 | 重新叫号 |
| POST | /v1/tickets/{ticket_id}/skip |
call.write |
是 | 过号 |
| POST | /v1/tickets/{ticket_id}/finish |
call.write |
是 | 完成 |
通用错误码(所有 /v1 接口均可能返回,各接口不再重复列出):40102、40304、40305、40902(商户关闭预约取号)、40303、42901、42902、40301、50001;需签名的接口还可能返回 40103、40104。
5.1 公共对象
Store 门店
| 字段 | 类型 | 说明 |
|---|---|---|
store_id |
string | 门店 ID(st_) |
name |
string | 门店名称 |
address |
string | 地址,可能为空串 |
phone |
string | 门店电话,可能为空串 |
timezone |
string | 门店时区(IANA 名称) |
business_hours |
array | 营业时间,见下表;不营业的日期不包含在内 |
queue_enabled |
bool | 是否开启现场排队 |
booking_enabled |
bool | 是否开启预约 |
business_hours 每一项:
| 字段 | 类型 | 说明 |
|---|---|---|
weekday |
int | 1–7,分别表示周一至周日 |
open |
string | 开始营业时间 HH:MM |
close |
string | 结束营业时间 HH:MM,可能为 24:00 |
Booking 预约
| 字段 | 类型 | 说明 |
|---|---|---|
booking_id |
string | 预约 ID(bk_) |
out_booking_no |
string | 创建时传入的单号 |
status |
string | 预约状态,见 4.12 |
store_id |
string | 门店 ID |
service_id |
string | 服务项目 ID |
date |
string | 预约日期(门店当地) |
start_time |
string | 时段开始时间(门店当地) |
end_time |
string | 时段结束时间(门店当地) |
checkin_deadline |
string | 签到截止时间(ISO 8601),目前为时段开始后 15 分钟;逾期未签到的预约变为 no_show |
user |
object | {"open_user_id": "..."},创建时传入的用户 ID,未传时为空串。不返回手机号和姓名 |
remark |
string | 备注,无备注时为空串 |
ticket_id |
string | null | 签到后生成的号码 ID,未签到时为 null |
cancelled_by |
string | null | 取消方:user / store / system,未取消时为 null |
created_at |
string | 创建时间(ISO 8601) |
updated_at |
string | 最后更新时间(ISO 8601) |
Ticket 号码
| 字段 | 类型 | 说明 |
|---|---|---|
ticket_id |
string | 号码 ID(tk_) |
out_ticket_no |
string | null | 取号时传入的单号;预约签到生成的号码为 null |
number |
string | 号码:现场取号前缀为 B,预约签到号码前缀为 A(门店可修改),如 B012、A003。按门店每日重新编号,超过 999 后继续递增 |
type |
string | walk_in 现场取号 / booking 预约签到 |
status |
string | 号码状态,见 4.12 |
ahead_count |
int | 前方等待人数;非 waiting 状态为 0。叫号顺序:已签到且预约时段已开始的预约号(按时段开始时间、签到时间排序)→ 现场号(按取号顺序)→ 提前签到且时段未开始的预约号。该值可能随时间变化 |
store_id |
string | 门店 ID |
service_id |
string | null | 服务项目 ID;取号时未指定服务项目则为 null |
booking_id |
string | null | 预约签到生成的号码对应的预约 ID;现场取号为 null |
date |
string | 号码所属的门店当地日期 |
created_at |
string | 取号时间(ISO 8601) |
called_at |
string | null | 最近一次叫号时间,未叫号时为 null |
finished_at |
string | null | 完成时间,未完成时为 null |
叫号接口(5.5)返回的号码在此基础上增加 channel、mobile_tail 两个字段,见 5.5。
5.2 门店
5.2.1 门店列表
GET /v1/stores
scope store.read,无需签名,无参数。返回所绑定商户的全部门店(目前一个商户对应一个门店)。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array<Store> | 门店列表 |
示例:
GET /v1/stores HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
{
"code": 0,
"msg": "ok",
"data": {
"items": [
{
"store_id": "st_8k2m4q7x1z9w3e5r",
"name": "优时测试门店(上海)",
"address": "上海市徐汇区测试路 1 号",
"phone": "",
"timezone": "Asia/Shanghai",
"business_hours": [
{ "weekday": 1, "open": "08:00", "close": "22:00" },
{ "weekday": 2, "open": "08:00", "close": "22:00" }
],
"queue_enabled": true,
"booking_enabled": true
}
]
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
(示例中 business_hours 仅列出两天。)
5.2.2 门店详情
GET /v1/stores/{store_id}
scope store.read,无需签名。
| 路径参数 | 说明 |
|---|---|
store_id |
门店 ID |
响应 data:Store 对象(字段见 5.1)。
错误码:40401 门店不存在或不属于所绑定商户。
5.2.3 排队状态
GET /v1/stores/{store_id}/queue
scope store.read,无需签名。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
store_id |
string | 门店 ID |
queue_enabled |
bool | 是否开启现场排队 |
current_number |
string | null | 当日最近一次叫到的号码(该号码此后完成或过号,仍返回该值);当日尚未叫号时为 null |
waiting_count |
int | 当日排队中(waiting)的号码数 |
estimated_wait_minutes |
int | null | 预计等待分钟数,无法估算时为 null |
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"store_id": "st_8k2m4q7x1z9w3e5r",
"queue_enabled": true,
"current_number": "B012",
"waiting_count": 5,
"estimated_wait_minutes": 25
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:40401。
5.2.4 服务项目列表
GET /v1/stores/{store_id}/services
scope store.read,无需签名。
响应 data.items 每一项:
| 字段 | 类型 | 说明 |
|---|---|---|
service_id |
string | 服务项目 ID(sv_) |
name |
string | 名称 |
duration_minutes |
int | 服务时长(分钟) |
booking_enabled |
bool | 是否可预约 |
queue_enabled |
bool | 是否可现场取号 |
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"items": [
{ "service_id": "sv_3n6p8r1t4v7x9z2b", "name": "剪发", "duration_minutes": 30, "booking_enabled": true, "queue_enabled": true },
{ "service_id": "sv_6q8s1u3w5y7a9c2e", "name": "洗护", "duration_minutes": 60, "booking_enabled": false, "queue_enabled": true }
]
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:40401。
5.2.5 可约时段
GET /v1/stores/{store_id}/slots?service_id={service_id}&date={date}
scope store.read,无需签名。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
service_id |
string | 是 | 服务项目 ID,须属于该门店 |
date |
string | 是 | 门店当地日期 YYYY-MM-DD |
- 仅返回当日营业时间内、开始时间晚于当前时间的时段。
- 目前最多可查询自当日起 7 天(含当日);超出范围返回空列表。
- 名额(
capacity)按「门店 + 服务项目 + 时段」计算,各渠道共享。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
store_id |
string | 门店 ID |
service_id |
string | 服务项目 ID |
date |
string | 日期 |
items |
array | 时段列表,见下表 |
items 每一项:
| 字段 | 类型 | 说明 |
|---|---|---|
start_time |
string | 开始时间 HH:MM |
end_time |
string | 结束时间 HH:MM |
capacity |
int | 总名额 |
remaining |
int | 剩余名额,0 表示已约满 |
示例:
GET /v1/stores/st_8k2m4q7x1z9w3e5r/slots?service_id=sv_3n6p8r1t4v7x9z2b&date=2026-11-18 HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
{
"code": 0,
"msg": "ok",
"data": {
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"date": "2026-11-18",
"items": [
{ "start_time": "10:00", "end_time": "10:30", "capacity": 2, "remaining": 2 },
{ "start_time": "10:30", "end_time": "11:00", "capacity": 2, "remaining": 0 }
]
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:
| code | 场景 |
|---|---|
40001 |
缺少 service_id 或 date(data.errors 指明字段) |
40002 |
date 格式错误(data.errors.date);service_id 不属于该门店(data.errors.service_id);参数值为数组 |
40401 |
门店不存在或不属于所绑定商户 |
5.3 预约
5.3.1 创建预约
POST /v1/bookings
scope booking.write,需要签名,幂等(见 4.11)。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
out_booking_no |
string | 是 | 接入方预约单号(幂等键),字母、数字、_、-,1–64 位 |
store_id |
string | 是 | 门店 ID |
service_id |
string | 是 | 服务项目 ID,须属于该门店且可预约 |
date |
string | 是 | 预约日期(门店当地)YYYY-MM-DD |
start_time |
string | 是 | 时段开始时间(门店当地)HH:MM,须为 可约时段 返回的某个 start_time |
user |
object | 是 | 用户信息,见下表(user.mobile 必填) |
remark |
string | 否 | 备注,最长 200 个字符 |
user:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
open_user_id |
string | 否 | 接入方系统中的用户 ID,最长 64 个字符 |
mobile |
string | 是 | 手机号:可带前导 +,6–20 位数字。平台以手机号识别同一顾客 |
name |
string | 否 | 姓名,最长 32 个字符 |
- 手机号是否属于顾客本人由接入方负责验证(如短信验证码),平台仅校验格式和限额。
- 同一应用下,同一手机号在同一日期、同一开始时间仅可有一个有效预约(不区分服务项目),否则返回
40904。open_user_id仅原样保存,不参与判断。 - 每人限额:同一手机号在同一门店最多 3 个待到店预约,超出返回
40908。通过开放平台接入的所有应用合并计算;使用同一单号重试不受限额影响。 - 手机号、姓名仅用于门店服务,任何接口均不返回。
- 顾客通知:门店开启短信通知时,平台向顾客发送短信(叫号、即将轮到、预约提醒、门店取消预约),不发送微信消息。回调照常推送,接入方可据此决定是否另行通知顾客。
响应 data:Booking 对象。
示例请求(签名见 3.4 示例 1):
POST /v1/bookings HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
Content-Type: application/json
X-Timestamp: 1794965400
X-Nonce: n8Kq2xV7mZp4Lw9RtY3c
X-Sign: 79a7d5a80953f282278a0ba2318ac19b37f90502f33b52bd7ed1abadad6fbfe5
{"out_booking_no":"TP202611180001","store_id":"st_8k2m4q7x1z9w3e5r","service_id":"sv_3n6p8r1t4v7x9z2b","date":"2026-11-18","start_time":"10:00","user":{"open_user_id":"u_8823","mobile":"13800000000"}}
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"booking_id": "bk_5h7j9k2l4m6n8p1q",
"out_booking_no": "TP202611180001",
"status": "pending",
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"date": "2026-11-18",
"start_time": "10:00",
"end_time": "10:30",
"checkin_deadline": "2026-11-18T10:15:00+08:00",
"user": { "open_user_id": "u_8823" },
"remark": "",
"ticket_id": null,
"cancelled_by": null,
"created_at": "2026-11-18T09:30:01+08:00",
"updated_at": "2026-11-18T09:30:01+08:00"
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:
| code | 场景 |
|---|---|
40001 |
缺少必填字段(data.errors 指明字段) |
40002 |
字段格式错误(data.errors 指明字段,如 service_id 不属于该门店);start_time 不是可约时段(data 为 null);请求体不是 JSON 对象 |
40401 |
门店不存在或不属于所绑定商户 |
40901 |
时段已约满 |
40902 |
门店、服务项目未开通预约,或该日期不营业 |
40904 |
该手机号在此时段已有预约 |
40905 |
单号已被使用且参数不一致 |
40906 |
超出本应用在该门店该日期的预约配额 |
40908 |
该手机号在该门店已有 3 个待到店预约 |
40907 |
同一单号的请求正在处理中,请稍后使用相同参数重试 |
50001 |
系统繁忙,结果可能未知;须使用相同单号和参数重试 |
5.3.2 查询预约
GET /v1/bookings/{booking_id}
scope booking.read,无需签名。仅可查询本应用创建的预约。
响应 data:Booking 对象(实时状态)。
错误码:40402 预约不存在或不属于本应用。
5.3.3 取消预约
POST /v1/bookings/{booking_id}/cancel
scope booking.write,需要签名。
请求体(可为空):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
reason |
string | 否 | 取消原因,最长 200 个字符 |
- 仅
pending(待到店)的预约可取消。已签到的预约须通过取消号码(需ticket.write)取消,号码取消后预约同时变为cancelled。 - 预约已为
cancelled时直接返回成功;超时后可直接重试。 - 取消成功后释放时段名额,并归还本应用的预约配额。
响应 data:取消后的 Booking 对象(status 为 cancelled,cancelled_by 为 user)。
示例请求:
POST /v1/bookings/bk_5h7j9k2l4m6n8p1q/cancel HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
Content-Type: application/json
X-Timestamp: <当前时间戳>
X-Nonce: <新的随机串>
X-Sign: <按第 3 节计算>
{"reason":"用户行程变更"}
错误码:
| code | 场景 |
|---|---|
40002 |
reason 不是字符串或超过 200 个字符;请求体不是 JSON 对象 |
40402 |
预约不存在或不属于本应用 |
40903 |
当前状态不允许取消(非 pending 且非 cancelled) |
5.3.4 到店签到
POST /v1/bookings/{booking_id}/checkin
scope booking.write,需要签名。请求体可为空(内容将被忽略)。
- 签到时间窗口:时段开始前 60 分钟起至
checkin_deadline止,且仅限预约当日;窗口外返回40903。 - 仅
pending的预约可签到。签到后预约变为checked_in,同时生成一个type = booking的号码进入排队,排队顺序见 Ticket 对象 的ahead_count(预约时段开始后,已签到的预约号优先叫号)。 - 预约已为
checked_in时直接返回成功及同一号码;超时后可直接重试。结果未知时,也可通过 查询预约 返回的ticket_id获取号码。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
booking |
Booking | 签到后的预约(status 为 checked_in,ticket_id 为生成的号码) |
ticket |
Ticket | 生成的号码(type 为 booking,out_ticket_no 为 null,booking_id 为该预约) |
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"booking": {
"booking_id": "bk_5h7j9k2l4m6n8p1q",
"out_booking_no": "TP202611180001",
"status": "checked_in",
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"date": "2026-11-18",
"start_time": "10:00",
"end_time": "10:30",
"checkin_deadline": "2026-11-18T10:15:00+08:00",
"user": { "open_user_id": "u_8823" },
"remark": "",
"ticket_id": "tk_9a8b7c6d5e4f3g2h",
"cancelled_by": null,
"created_at": "2026-11-18T09:30:01+08:00",
"updated_at": "2026-11-18T09:52:40+08:00"
},
"ticket": {
"ticket_id": "tk_9a8b7c6d5e4f3g2h",
"out_ticket_no": null,
"number": "A015",
"type": "booking",
"status": "waiting",
"ahead_count": 3,
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"booking_id": "bk_5h7j9k2l4m6n8p1q",
"date": "2026-11-18",
"created_at": "2026-11-18T09:52:40+08:00",
"called_at": null,
"finished_at": null
}
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:
| code | 场景 |
|---|---|
40402 |
预约不存在或不属于本应用 |
40903 |
不在签到时间窗口内,或状态不是 pending / checked_in |
5.4 号码
5.4.1 现场取号
POST /v1/tickets
scope ticket.write,需要签名,幂等(见 4.11)。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
out_ticket_no |
string | 是 | 接入方取号单号(幂等键),字母、数字、_、-,1–64 位 |
store_id |
string | 是 | 门店 ID |
service_id |
string | 否 | 服务项目 ID,须属于该门店;门店不区分服务项目时不传 |
user |
object | 是 | 用户信息,字段及规则同 创建预约 的 user(user.mobile 必填) |
- 仅可在门店当日营业时间内取号,且门店(及指定的服务项目)须已开启现场排队,否则返回
40902。 - 号码按门店统一排队(不按服务项目分队),叫号顺序见 Ticket 对象 的
ahead_count。 - 每人限额:同一手机号当日最多 1 个未结束(排队中或已叫号)的号码,超出返回
40908;通过开放平台接入的所有应用合并计算,使用同一单号重试不受限额影响。
响应 data:Ticket 对象。
示例请求:
POST /v1/tickets HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
Content-Type: application/json
X-Timestamp: <当前时间戳>
X-Nonce: <新的随机串>
X-Sign: <按第 3 节计算>
{"out_ticket_no":"TK202611180001","store_id":"st_8k2m4q7x1z9w3e5r","service_id":"sv_3n6p8r1t4v7x9z2b","user":{"open_user_id":"u_8823","mobile":"13800000000"}}
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"ticket_id": "tk_2c4e6g8i1k3m5o7q",
"out_ticket_no": "TK202611180001",
"number": "B012",
"type": "walk_in",
"status": "waiting",
"ahead_count": 4,
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"booking_id": null,
"date": "2026-11-18",
"created_at": "2026-11-18T09:41:07+08:00",
"called_at": null,
"finished_at": null
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:
| code | 场景 |
|---|---|
40001 |
缺少 out_ticket_no、store_id 或 user.mobile(data.errors 指明字段) |
40002 |
字段格式错误,或 service_id 不属于该门店(data.errors 指明字段);请求体不是 JSON 对象 |
40401 |
门店不存在或不属于所绑定商户 |
40902 |
不在营业时间内,或门店 / 服务项目未开启现场排队 |
40905 |
单号已被使用且参数不一致 |
40908 |
该手机号当日已有未结束的号码 |
40907 |
同一单号的请求正在处理中,请稍后使用相同参数重试 |
50001 |
系统繁忙,结果可能未知;须使用相同单号和参数重试 |
5.4.2 查询号码
GET /v1/tickets/{ticket_id}
scope ticket.read,无需签名。仅可查询本应用取的号码(含本应用预约签到生成的号码)。
响应 data:Ticket 对象(含实时 ahead_count)。
错误码:40402 号码不存在或不属于本应用。
持有
call.write的应用通过本接口同样仅可查询本应用取的号码;其他渠道的号码须通过 门店完整排队列表 查看。
5.4.3 取消号码
POST /v1/tickets/{ticket_id}/cancel
scope ticket.write,需要签名。请求体可为空(内容将被忽略)。
- 仅
waiting的号码可取消;号码已为cancelled时直接返回成功,超时后可直接重试。 - 预约签到生成的号码被取消时,对应预约同时变为
cancelled,该时段名额不归还。
响应 data:取消后的 Ticket 对象。
错误码:
| code | 场景 |
|---|---|
40402 |
号码不存在或不属于本应用 |
40903 |
当前状态不允许取消 |
5.5 叫号
叫号接口供门店自有系统使用,需 call.write(由平台运营单独开通)。所有叫号接口均需要签名,包括 GET 排队列表。
- 可查看和操作所绑定商户门店所有渠道的号码(本应用、小程序、商户端等)。平台为其他渠道的号码生成本应用的对外
ticket_id,与回调中的ticket_id一致。 - 叫号接口返回的号码为 Ticket 对象附加以下两个字段,并对其他渠道的号码隐藏部分信息:
| 字段 | 类型 | 说明 |
|---|---|---|
channel |
string | self 本应用取的号码 / other 其他渠道的号码 |
mobile_tail |
string | null | 用户手机号后 4 位,无手机号时为 null |
其他渠道(channel = other)号码的 out_ticket_no、booking_id 固定为 null,且不返回任何用户标识。
5.5.1 门店完整排队列表
GET /v1/stores/{store_id}/tickets?status={status}&date={date}
scope call.write,需要签名(path 不含查询参数,请求体为空,见 3.4 示例 2)。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
status |
string | 否 | 按状态筛选,多个值以英文逗号分隔,如 waiting,called。可选值:waiting、called、completed、skipped、cancelled。未传时返回全部状态 |
date |
string | 否 | 门店当地日期 YYYY-MM-DD,默认为当日。仅可查询当日或前一日 |
查询参数不参与签名。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
store_id |
string | 门店 ID |
date |
string | 查询的日期 |
items |
array | 号码列表(叫号格式的 Ticket),按取号顺序排列 |
示例请求:
GET /v1/stores/st_8k2m4q7x1z9w3e5r/tickets?status=waiting HTTP/1.1
Host: open-api.yours.xyz
Authorization: Bearer at_Xk9mQ2vL7pR4tY8wZ3nB6cF1hJ5sD0gKaE2uI7oP
X-Timestamp: 1794965460
X-Nonce: Q4wE7rT1yU5iO9pA2sD6
X-Sign: 6388b5fdb1fd2362c55d5bab5b571fee993ff5ce443f30cb59c118564e996f2f
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"store_id": "st_8k2m4q7x1z9w3e5r",
"date": "2026-11-18",
"items": [
{
"ticket_id": "tk_7m1n3p5r7t9v2x4z",
"out_ticket_no": null,
"number": "A011",
"type": "walk_in",
"status": "waiting",
"ahead_count": 0,
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": null,
"booking_id": null,
"date": "2026-11-18",
"created_at": "2026-11-18T09:38:12+08:00",
"called_at": null,
"finished_at": null,
"channel": "other",
"mobile_tail": "5678"
},
{
"ticket_id": "tk_2c4e6g8i1k3m5o7q",
"out_ticket_no": "TK202611180001",
"number": "B012",
"type": "walk_in",
"status": "waiting",
"ahead_count": 1,
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": "sv_3n6p8r1t4v7x9z2b",
"booking_id": null,
"date": "2026-11-18",
"created_at": "2026-11-18T09:41:07+08:00",
"called_at": null,
"finished_at": null,
"channel": "self",
"mobile_tail": "0000"
}
]
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
错误码:
| code | 场景 |
|---|---|
40002 |
status 含不支持的值(data.errors.status);date 不是当日或前一日(data.errors.date) |
40401 |
门店不存在或不属于所绑定商户 |
5.5.2 叫下一位
POST /v1/stores/{store_id}/call-next
scope call.write,需要签名。请求体可为空(内容将被忽略)。
将该门店当日最早的 waiting 号码置为 called。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
ticket |
Ticket(叫号格式)| null | 被叫到的号码;无等待中的号码时为 null(code 仍为 0) |
示例响应:
{
"code": 0,
"msg": "ok",
"data": {
"ticket": {
"ticket_id": "tk_7m1n3p5r7t9v2x4z",
"out_ticket_no": null,
"number": "A011",
"type": "walk_in",
"status": "called",
"ahead_count": 0,
"store_id": "st_8k2m4q7x1z9w3e5r",
"service_id": null,
"booking_id": null,
"date": "2026-11-18",
"created_at": "2026-11-18T09:38:12+08:00",
"called_at": "2026-11-18T10:02:15+08:00",
"finished_at": null,
"channel": "other",
"mobile_tail": "5678"
}
},
"request_id": "req_20261118_a1b2c3d4e5f60718"
}
本接口不具备幂等性。超时或收到
50001时不得直接重试,须先调用 门店完整排队列表 确认是否已叫号,再决定是否重试,否则可能重复叫号。
错误码:40401 门店不存在或不属于所绑定商户。
5.5.3 重新叫号 / 过号 / 完成
POST /v1/tickets/{ticket_id}/recall
POST /v1/tickets/{ticket_id}/skip
POST /v1/tickets/{ticket_id}/finish
scope call.write,需要签名。请求体可为空(内容将被忽略)。ticket_id 为本应用获取的号码 ID(来自排队列表、叫下一位、取号结果或回调)。
| 接口 | 允许的当前状态 | 操作后状态 | 说明 |
|---|---|---|---|
recall 重新叫号 |
called、skipped |
called |
更新 called_at |
skip 过号 |
called |
skipped |
|
finish 完成 |
called |
completed |
设置 finished_at;预约签到生成的号码完成后,对应预约变为 completed |
响应 data:操作后的号码(叫号格式的 Ticket)。
错误码:
| code | 场景 |
|---|---|
40402 |
号码不存在,或号码所在门店不属于所绑定商户 |
40903 |
当前状态不允许该操作(如对 waiting 号码执行 finish,或重复执行 finish) |
6. 回调通知
预约或号码状态变化时,平台向应用配置的回调地址推送通知。回调地址由平台运营或商户管理员配置;未配置回调地址的应用不推送。
6.1 回调地址要求
- 仅允许
https,端口默认仅允许443; - 不得包含用户名和密码;路径仅可包含 URL 允许的字符(中文等须先编码),不得包含
.、..路径段; - 不得指向内网或保留地址(平台每次推送前重新解析并校验);
- 平台不跟随重定向,3xx 视为推送失败。
6.2 事件类型
事件 event |
触发时机 | data 字段(除对象 ID 和 store_id 外) |
|---|---|---|
ticket.called |
号码被叫到(含重新叫号) | number、recall |
ticket.near |
前方等待人数首次降至 N 位以内(N 由平台配置,目前默认为 3)。每个号码最多推送一次;取号时前方等待人数已不超过 N 的号码不推送 | number、ahead_count |
ticket.skipped |
过号 | number |
ticket.completed |
完成 | number |
ticket.cancelled |
号码被取消(用户、门店或系统) | number、cancelled_by |
booking.reminder |
预约开始前提醒(提前时间由平台配置,目前默认为 60 分钟) | date、start_time |
booking.no_show |
超过签到截止时间未签到 | 无 |
booking.cancelled |
预约被取消(用户、门店或系统;含已签到预约的号码被取消) | cancelled_by |
推送范围:
- 本应用创建的预约、取的号码(含签到生成的号码)的事件,推送给本应用;
- 持有
call.write的应用,另接收所绑定商户门店所有渠道号码的ticket.*事件(其他渠道号码的ticket_id为该应用生成,与叫号接口返回值一致); - 同一事件对同一应用仅推送一份。
6.3 推送请求
POST <回调地址> HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: yours-open-webhook/1.0
X-Timestamp: 1794967335
X-Nonce: 5f0c9e2a7b4d1e8f3a6c9b2d5e8f1a4c
X-Sign: c43fdeb8569d8dda0abc96e65e873647d14891a3620c707a3f9574603bddbfb4
{"event_id":"evt_3f9a1c7e5b2d8f4a6c0e9b1d","event":"ticket.called","occurred_at":"2026-11-18T10:02:15+08:00","data":{"ticket_id":"tk_2c4e6g8i1k3m5o7q","store_id":"st_8k2m4q7x1z9w3e5r","number":"B012","recall":false}}
请求体字段:
| 字段 | 类型 | 说明 |
|---|---|---|
event_id |
string | 事件 ID,evt_ + 24 位小写十六进制。同一事件对同一应用始终相同(重试时不变),用于去重 |
event |
string | 事件类型,见 6.2 |
occurred_at |
string | 事件发生时间(ISO 8601,门店时区) |
data |
object | 事件数据,见下表 |
data 字段:
| 字段 | 类型 | 出现于 | 说明 |
|---|---|---|---|
ticket_id |
string | ticket.* |
号码 ID |
booking_id |
string | booking.* |
预约 ID |
store_id |
string | 全部 | 门店 ID |
number |
string | null | ticket.* |
号码,如 B012 |
recall |
bool | ticket.called |
是否为重新叫号 |
ahead_count |
int | null | ticket.near |
前方等待人数 |
cancelled_by |
string | null | ticket.cancelled、booking.cancelled |
user / store / system |
date |
string | null | booking.reminder |
预约日期(门店当地) |
start_time |
string | null | booking.reminder |
时段开始时间(门店当地) |
示例:
{"event_id":"evt_8b2e4d6f1a3c5e7b9d0f2a4c","event":"ticket.near","occurred_at":"2026-11-18T10:05:40+08:00","data":{"ticket_id":"tk_9a8b7c6d5e4f3g2h","store_id":"st_8k2m4q7x1z9w3e5r","number":"B015","ahead_count":3}}
{"event_id":"evt_1c3e5a7b9d2f4a6c8e0b2d4f","event":"booking.cancelled","occurred_at":"2026-11-18T08:12:03+08:00","data":{"booking_id":"bk_5h7j9k2l4m6n8p1q","store_id":"st_8k2m4q7x1z9w3e5r","cancelled_by":"store"}}
{"event_id":"evt_6d8f0b2c4e6a8c0e2a4b6d8f","event":"booking.no_show","occurred_at":"2026-11-18T10:15:30+08:00","data":{"booking_id":"bk_5h7j9k2l4m6n8p1q","store_id":"st_8k2m4q7x1z9w3e5r"}}
6.4 验签
回调请求的签名方式与请求签名完全相同,使用同一 sign_key:
X-Sign = lower_hex(HMAC-SHA256(sign_key, "POST" + "\n" + path + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + sha256_hex(body)))
path:回调地址的路径部分,取请求行中的原始路径(不解码),不含域名和查询参数,如/yours/webhook;body:收到的原始请求体字节(须先验签,再解析 JSON);X-Timestamp与接收方服务器时间偏差超过 5 分钟的请求应拒绝;- 须使用常量时间比较签名;
- 验签失败时应返回非 200 状态码(如 401),且不得处理该请求。
自测数据:6.3 示例请求的回调地址为 https://partner.example.com/yours/webhook、sign_key 为 k3Zb8QvN2xLp7RtY5wHc9JmE4sGd6FaU1oKi0nBr 时:
sha256_hex(body) = a03357c6284fddab0f53a064d059a76fc3bdf88897b800b6c22c2c554575d31f
string_to_sign:
POST
/yours/webhook
1794967335
5f0c9e2a7b4d1e8f3a6c9b2d5e8f1a4c
a03357c6284fddab0f53a064d059a76fc3bdf88897b800b6c22c2c554575d31f
X-Sign = c43fdeb8569d8dda0abc96e65e873647d14891a3620c707a3f9574603bddbfb4
(自测时请跳过时间戳检查,或将当前时间固定为 1794967335。)
PHP、Python、Node.js、Java 验签代码见 examples/webhook/。
6.5 响应、重试与去重
- 成功:须在 5 秒内返回 HTTP
200,响应体为success(忽略前后空白)。其他情况(非 200、响应体不是success、超时、连接失败、重定向)均视为失败。平台仅读取响应的前 1KB。 - 重试:推送失败后,分别在 1 分钟、5 分钟、30 分钟、2 小时、6 小时后重试,共重试 5 次(含首次最多推送 6 次)。仍失败则停止推送。商户管理员可在控制台查询推送记录,如需重新推送请联系平台运营。
- 去重:同一事件可能多次推送(重试、手动重推、网络抖动),接入方须按
event_id去重,并保证处理逻辑幂等。 - 顺序:平台不保证事件到达顺序,不同号码之间、预约与号码之间均可能乱序。请以
occurred_at及查询接口返回的实时状态为准,如收到事件后调用 查询号码 / 查询预约 获取最新状态。 - 建议:先验签并持久化,立即返回
success,再异步处理业务,确保在 5 秒内响应。
7. 错误码总表
HTTP 状态码为 code 的前三位(成功时为 200)。msg 为通用文案,程序判断以 code 为准。
| code | HTTP | msg | 说明与处理建议 |
|---|---|---|---|
0 |
200 | ok | 成功 |
40001 |
400 | 参数缺失 | 缺少必填参数,data.errors 指明字段 |
40002 |
400 | 参数格式错误 | 参数格式或取值错误;多数情况下 data.errors 指明字段 |
40101 |
401 | appid 或 secret 错误 | 请检查凭证;多次失败将被临时封禁 |
40102 |
401 | token 无效或已过期 | 缺少 Authorization 头、token 已过期或已被吊销(应用停用、重置 secret)。请重新获取 token |
40103 |
401 | 签名错误 | 签名头缺失 / 格式错误,或签名不匹配。请检查 path、请求体字节、sign_key |
40104 |
401 | 请求已过期或重复提交 | 时间戳偏差超过 ±300 秒,或 nonce 10 分钟内重复。请校准时钟,每次请求生成新 nonce |
40301 |
403 | 无权访问该接口 | 应用未获授该接口所需的 scope,请联系平台运营开通 |
40303 |
403 | IP 不在白名单内 | 请将服务器出口 IP 加入白名单 |
40304 |
403 | 应用已停用 | 请联系平台运营或商户管理员 |
40305 |
403 | 所绑定商户不可用 | 商户已停用或冻结 |
40400 |
404 | 接口不存在 | 路径错误或请求方法不匹配 |
40401 |
404 | 门店不存在 | 门店不属于所绑定商户时同样返回 |
40402 |
404 | 预约或号码不存在 | 预约 / 号码不属于本应用时同样返回 |
40901 |
409 | 时段已约满 | 请选择其他时段 |
40902 |
409 | 门店未营业或排队已关闭 | 商户已关闭预约取号(所有接口均可能返回);门店 / 服务项目未开通预约或排队;不在营业时间内 |
40903 |
409 | 当前状态不允许该操作 | 请先查询最新状态 |
40904 |
409 | 该用户在此时段已有预约 | 同一手机号在同一日期、同一开始时间已有有效预约 |
40905 |
409 | 单号已被使用且参数不一致 | 同一单号仅可用于同一组参数;新业务须使用新单号 |
40906 |
409 | 超出本应用预约配额 | 本应用在该门店该日期的预约数已达上限 |
40907 |
409 | 请求处理中,请稍后重试 | 同一单号的请求正在处理中,请稍后使用相同单号和参数重试 |
40908 |
409 | 超出每人限额 | 同一手机号在同一门店最多 3 个待到店预约、当日最多 1 个未结束号码(通过开放平台接入的所有应用合并计算) |
42901 |
429 | 调用频率超限 | 超过 QPS 限制,或认证失败次数过多被临时封禁。请降低频率后重试 |
42902 |
429 | 当日调用量超限 | 当日调用量或获取 token 次数已用尽 |
50001 |
500 | 系统繁忙,请重试 | 请稍后重试。创建类接口须使用相同单号重试;叫下一位须先查询排队列表 |
8. 沙箱环境
- 沙箱独立部署,使用模拟数据,不影响真实门店。
- 测试 appid、secret、sign_key 及测试门店由平台运营提供。
- 平台运营可在沙箱后台模拟其他渠道用户取号,以及叫号、过号、完成操作,以触发
ticket.*回调,用于联调叫号接口、回调地址和验签。 - 沙箱的接口、签名规则、错误码与正式环境一致;测试门店的营业时间、时段名额等以平台运营提供的为准。
沙箱接口地址为 https://sandbox-api.yours.xyz,开发者中心与商户控制台为 https://sandbox.yours.xyz;测试应用凭证由平台运营提供,测试数据及操作方式以平台运营提供的说明为准。
9. 示例代码与工具
| 内容 | 位置 |
|---|---|
| 请求签名示例(PHP、Java、Python、Node.js) | examples/sign/ |
| 回调验签示例(PHP、Python、Node.js、Java) | examples/webhook/ |
| Postman 集合 | docs/postman/ |
如需技术支持,请提供响应中的 request_id(或响应头 X-Request-Id)、请求时间及 appid。不得发送 secret、sign_key 或 access_token。
