优时开放平台 控制台
开发文档 / 接口文档

优时开放平台 对外接口文档(v1)

本文档面向接入优时开放平台的第三方开发者(以下简称「接入方」),说明 access_token 获取、请求签名、预约取号接口调用及回调通知接收。

字段、取值及错误码以本文档为准。兼容性变更(新增字段、新增接口)不升级版本,接入方须忽略无法识别的字段。不兼容变更将发布 /v2,旧版本保留不少于 6 个月,并提前通知。

目录

  1. 概述
  2. 获取 access_token
  3. 请求签名
  4. 通用约定
  5. 接口列表
  6. 回调通知
  7. 错误码总表
  8. 沙箱环境
  9. 示例代码与工具

1. 概述

1.1 环境地址

环境 地址
正式环境 https://open-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 接入流程

  1. 申请应用:联系平台运营创建应用。平台运营负责绑定商户、开通所需 scope,并按需配置 IP 白名单、回调地址、限流额度和预约配额。接入方获得 appid、secret、sign_key。
  2. 沙箱联调:使用平台运营提供的测试 appid,在沙箱环境完成获取 token、签名、调用接口、接收回调的全流程(见第 8 节)。
  3. 配置正式环境:商户管理员可在商户控制台查看调用日志和回调日志、重置 secret / sign_key、配置 IP 白名单和回调地址、停用应用。scope、限流和配额由平台运营调整。
  4. 上线:切换至正式环境地址和凭证。

调用 /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 秒的请求,可由相同单号的重试接管处理并返回最终结果。

其他写接口(取消、签到、叫号等)不使用单号,重试规则见各接口说明。

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.* 回调,用于联调叫号接口、回调地址和验签。
  • 沙箱的接口、签名规则、错误码与正式环境一致;测试门店的营业时间、时段名额等以平台运营提供的为准。

沙箱地址、测试数据及操作方式以平台运营提供的说明为准。


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。