开放平台常见问题

由平台统一配置后线下下发，一对凭证按业务线授权（房源 / 本地生活 / 搬家），无需分别申请。

商家须为启用状态；数据可见范围与凭证一一对应，只能操作自己名下的房源与商品。

联系平台重置密钥（旧密钥立即失效）。重置后所有在跑任务都要换新密钥重签。

密钥等同密码：只放服务端或自己的联调机；不要写进前端代码、不要提交仓库、不要在群里发。文档与页面（含调试台）都不会展示平台侧存储的真实密钥。

不会。调试台签名在你的浏览器本地完成（内置与平台一致的 HMAC-SHA256 实现），请求只发往你在 Base 里填的地址。勾选「记住」时密钥存本机 localStorage，换机/清缓存即失效。

sign 与 timestamp 必须放在 JSON body 里（不是 HTTP header），与业务参数一起发送。用调试台跑一次对照请求体即可定位。

服务器校验 timestamp 与当前时间的偏差（窗口 ±5 分钟）。常见原因：服务器时钟不准；或把同一次签名复用超过 5 分钟——重试必须重新签名。

按命中率排查：

1. 数组序列化：签名时数组用单引号形式 tags=['旅居', '近地铁']，不是 JSON 的双引号；
2. 空值不参与：null 和 '' 的键在签名时跳过，但 body 里可以带；
3. 嵌套对象：按 父键.子键 点号展平（如 units 数组里的对象）——直接把最终 body 交给签名函数，不要手工拼串；
4. 布尔：true→'True'、false→'False'；
5. UTF-8：中文按 UTF-8 字节参与 HMAC；
6. 密钥：确认用的是本 vendor_id 对应的最新 hmac_key（重置后旧钥匙立即失效）。

最快定位法：打开在线调试台发同一个请求，对比它显示的 stringToSign 与你自己拼的串，第一个不一致的字符就是问题点。

body 里的 vendor_id 在平台侧没有对应密钥：核对是否发错环境（演示 vs 生产）、或商家尚未开通。平台侧核对密钥是否已配置或已被重置。

创建默认 status='draft'（草稿），C 端目录只展示 online。上架路径：units/create 至少 1 个户型并让它能算出默认夜价（户型 price_night 或 rent_monthly；也可由房源 price_from 兜底）→ projects/status 传 online，另有图集 ≥ 7 张 + 评级 passed 两道闸。price_from 自 2026-09 起选填，缺价或缺户型时上架接口直接 400，并点名是哪个户型。

C 端目录 GET /api/juzhu/catalog 有 ≤ 15 秒缓存，上架最迟 15 秒可见、下架最迟 15 秒消失。联调判断可见性请轮询等待，不要立即断言（平台回归脚本就是这么做的）。

channel（业务频道）与 city_id（城市）创建后不可改——接口会明确拒绝。城市挂错请下架后新建房源；district_id（行政区）可以改，但须属于该城市。

这是归属隔离：接口只命中你自己名下的房源。「不存在」和「别人的」统一返回 404，避免探测他人房源。先用 projects/list 确认 id 在自己名下。

真实电话只入库，用于 C 端拨号时服务端实时绑定虚拟号；任何列表/详情接口都不回显，防爬取与泄露。创建/更新接口可以提交它（须 11 位手机号），但读回来永远看不到。

两条路：① Webhook 事件推送（推荐）——在接入单里提供通知 URL，客户下单 / 支付 / 取消时平台主动推 HMAC 签名事件（booking.created / booking.paid / booking.cancelled），收到先验签（同一套算法）再处理，5s 内回 2xx 即送达，失败自动重试 3 次；② 拉取兜底——bookings/list 定时拉 status='pending' 对账（建议每分钟）。拿到订单后 bookings/confirm 确认或 bookings/cancel 拒单（拒单自动释放房态）；在线支付单未支付时确认会被拒。联系人手机号只回掩码。

订单详情见 房源接入 API §5 订单履约，可用页内调试台直接试。

不传 slug 时平台按名称自动生成并在同频道内保证唯一（冲突自动加 -2/-3… 后缀）；传了自定义 slug 也一样做唯一化，无需自己处理。

这些晚已被订单占用（booked），任何接口都不能改成可订/关房——须先走订单取消；取消后平台自动释放房态。这是防超卖的硬约束，商家侧与开放接口同口径。

未设置过的晚默认可订（房型开了「默认关房」则相反，见下）。夜价优先级：户型级覆盖 > 项目级覆盖 > 默认夜价；默认夜价两个频道一致 = 户型 price_night > 月租/30 > 起价/30（2026-09 起 rental 的 price_night 同样生效，不再只认月租折算）。「恢复默认价」= 传 status:'open' 且不带 price_night，平台清除该晚价格覆盖。

放出量两种口径（2026-09）：qty = 该晚对平台开放的总量（含平台已订）；available_qty = 净可售（推荐多渠道商家）——直接推「还能卖几间」，平台记基线、之后只扣平台自己卖掉的，取消自动加回，并按物理余量封顶防超售。两者只能传一个。remaining 一律只读。default_closed=true（房型 ext）开启「默认关房」：未推送放出的晚一律不可订，缺省关闭。

图集（2026-09）：换图 / 撤图走 photos/sync 全量覆盖——传该实体当前完整图集，平台自动移除不在列表内的旧图；匹配键 external_id 优先、URL 兜底（URL 带签名会变）。分类 bedroom/kitchen/bathroom/living/nearby/other，排序按 sort 从小到大归一化。上架需合计 ≥7 张 + 封面，单次上限 100 张（超出截取前 100 并告警）；单图 ≤10MB、分辨率 ≥800×600，推送时可带声明值即时校验、上架时抽检 2 张真拉取核对。

缺省口径：rental=15 晚（旅居/长租）、minsu=15 晚（民宿）。商家可覆盖，2026-09 起生效顺序为「户型 > 房源 > 频道默认」：户型级传 units 的 min_stay_nights，房源级 ext.min_stay_nights 降级为默认值。rental 为 1–365 晚，minsu 为 15–365 晚、不得低于 15 晚。整栋单（不指定户型）按排序最前的户型，与取消政策同一套回退。同一口径在 C 端日历选段、下单页、平台下单接口三处校验，不足直接 400。

仅三个平台统一枚举：switch_rental 换租保险、hotel_cancel 酒店取消险、property 财产保险。传未知 key 返回 400 并列出可用枚举；清空传 []。配置后随 catalog / 详情 / 房态日历下发 C 端展示（含名称与图标）。

商家开放接口一律「分」（如 29900 = 299 元），平台在接口边界做分↔元换算入库；房源接口则用「元」（rent_monthly 元/月、price_night 元/晚）。两条业务线单位不同，别混。

家政商品 products/status 用 on / off / sold_out（delete 接口实际是把状态置 off）；房源 projects/status 用 online / offline / draft。语义各自独立，别把房源的状态值传给家政接口。

不支持。开放接口统一只接受 HMAC-SHA256 签名（vendor_id + timestamp + sign 放在请求体里），按商家隔离数据，没有 token / 账号密码等替代方式。这也是唯一需要对接的鉴权机制。

node scripts/housing_vendor_hmac_regression.cjs [base_url]   # 房源全生命周期（创建→上架→房态→下架→越权）
node scripts/vendor_hmac_regression.cjs                      # 家政开放接口

脚本走真实 HTTP 签名链路并自动清理演示数据；自检签名实现是否正确，跑通它即可。

接口与签名完全一致，仅 Base 不同。演示环境（本页同源 sytest.meizu.life）数据可随时清理重建，用测试商家练手；生产 Base 以平台接入单为准。

接入群报四样：vendor_id、接口路径、请求里的 timestamp、返回的 message 与 HTTP 状态码。不要发 hmac_key，也不要发完整业务数据截图。