房源接入 API

1 接入概览

房源开放接口是平台商家开放接口的房源分支：路径前缀 /api/juzhu/housing/vendor/*，全部为 POST，请求/响应均为 JSON。鉴权、密钥、错误码风格与家政开放接口（/api/juzhu/jiazheng/vendor/*）完全一致，一套密钥两个业务共用。

• 提交即生效：房源与户型实时可查，逐晚房态即时更新；客户订单占用的晚自动锁定，任何接口都不可改。
• 数据归属：房源创建时自动绑定签约商家，所有读写按归属隔离——查询、更新、上下架只能命中自己的房源，他人房源一律 404（不泄露存在性）。
• 上架语义：status ∈ draft（草稿，默认）/ online（上架）/ offline（下架）；C 端目录只出 status=online 且 rating_status=passed（双闸）。目录有 ≤ 15 秒缓存，上下架最迟 15 秒生效。
• 审核语义：新建一律先落草稿（传 online 创建会被拒）；上架前须通过平台评级审核（rating_status：draft → pending → passed / rejected），提审与查进度走开放接口 projects/rating/submit / projects/rating/status（见 4.11）。已上架房源的内容更新免审即时生效。

接入流程

环境

2 HMAC 签名认证（与家政开放接口同机制）

2.1 凭证

每个商家一个 vendor_id + 一把 hmac_key，由平台统一配置并线下下发。hmac_key 等同密码：只放服务端或自己的联调机，不要写进前端代码、不要提交仓库。

2.2 签名算法

1. 取业务参数对象 body，加上 vendor_id；剔除 sign 字段。
2. 扁平化：嵌套对象用 父键.子键 点号展平；null、''（空串）的键不参与签名。
3. 值序列化：字符串原样；数字/布尔转字符串（true→'True'、false→'False'）；数组 → ['a', 'b']（单引号、逗号空格分隔）。
4. 按键名字典序排序，拼成 k1=v1&k2=v2&…（& 连接，无转义）。
5. 追加 timestamp（毫秒时间戳）参与上述串；用 hmac_key 做 HMAC-SHA256，取 hex 小写 为 sign。
6. 请求体 = 业务参数 + vendor_id + timestamp + sign，POST JSON 发送。时间戳与服务器偏差 ±5 分钟 内有效。

// Node 签名示例
const crypto = require('crypto');

function pyStr(v) {
  if (v === true)  return 'True';
  if (v === false) return 'False';
  if (Array.isArray(v)) return '[' + v.map(x => (typeof x === 'string' ? "'" + x + "'" : pyStr(x))).join(', ') + ']';
  return String(v);
}
function flatten(data, prefix) {
  const flat = {};
  for (const [k, v] of Object.entries(data || {})) {
    if (v == null || v === '') continue;          // 空值不参与签名
    const key = prefix ? prefix + '.' + k : k;
    if (v && typeof v === 'object' && !Array.isArray(v)) Object.assign(flat, flatten(v, key));
    else flat[key] = pyStr(v);
  }
  return flat;
}
function sign(secretKey, body) {
  const payload = { ...body };
  delete payload.sign;
  const timestamp = Date.now();
  const flat = flatten(payload);
  flat.timestamp = String(timestamp);
  const stringToSign = Object.keys(flat).sort().map(k => k + '=' + flat[k]).join('&');
  payload.timestamp = timestamp;
  payload.sign = crypto.createHmac('sha256', secretKey).update(stringToSign, 'utf8').digest('hex');
  return payload;                        // 直接作为 POST body
}

const body = sign(HMAC_KEY, { vendor_id: VENDOR_ID });
await fetch(BASE + '/api/juzhu/housing/vendor/projects/list', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
});

响应统一为 JSON：成功 { "code": 0, "message": "success", … }；失败 HTTP 状态码 + { "code": 4xx, "message": "原因" }（见 错误码）。

3 数据字典

字段与平台房源模型一致、即接口契约本身；带 ★ 为商家写入接口接受的字段，标 只读出参 的字段由平台计算下发、传入无效。

3.1 房源（projects）

3.2 户型（units）

户型 = 房源下的实体售卖库存单元：预订、逐晚房态、免费取消政策都挂在户型维度；整栋 / 不限房型走项目级（unit_id=0）。同规格房型多间库存用 total_qty 表达（多间口径 2026-09-10：房型 × N 间，按晚扣减、售满即关，不区分具体房间号）。projects/create 可带 units[] 一次建全，后续 units/create 追加。

3.3 房态日历（逐晚库存 × 间数）

3.4 卡片展示价（最低可售单夜价）

C 端房源卡上的价格由平台计算并随接口下发（price_from_display / price_unit / price_note），贵方无需传、也不要在自己页面另算一套。单位口径：minsu 与带「旅居」tag 的 rental 按晚；其余 rental 按月（起价语义，price_from 缺省时回落户型默认夜价 × 30）。

按晚房源的取值规则：从今天起按自然月向后扫描（最多 12 个月，与 C 端可订窗口同口径），取第一个存在可售间夜的月份，该月内最低单夜价即展示价；扫满仍无可售 → 不展示价格，文案「暂无可订」。

3.5 净可售库存（available_qty，多渠道商家）

如果同一批房间你们同时在别的渠道卖（OTA、直客、自己的小程序…），或者有房间临时不可售（未保洁、维修），用 available_qty 比 qty 更省事：直接把「这一晚平台还能卖几间」推上来，按你们自己的口径算就行。

举个你们反馈里的例子：房型 total_qty=6，平台已售 2、其他渠道售 1、还有 1 间未保洁 → 你们算出「能卖 2 间」，直接推 available_qty: 2：

1. 推送时平台已订 2 → 基线记 2 → 平台显示剩余 2（旧口径会二次扣成 0）；
2. 平台又卖掉 1 间 → 剩余 1；客户取消 → 自动回到 2；
3. 其他渠道又卖掉 1 间 → 你们重推 available_qty: 1，基线刷新为当时的已订数 → 剩余 1。

3.6 默认关房（default_closed，可选开关）

净可售解决的是「推过的晚怎么算」，默认关房解决的是「没推过的晚怎么办」。默认情况下平台是「没推过的晚 = 可订、放出量 = total_qty」——对多渠道商家这很危险：你们在别处卖掉、或临时不可售的晚，只要没推过，平台照样会放出去卖。

把房型的 default_closed 设为 true（写 units.ext，可经 units/update 或后台配置）后：

• 只有你们显式推送过放出量的晚才可订（qty 或 available_qty 都算）；
• 没推过的晚一律不可订（remaining = 0，下单 400）；只设过夜价、没设放出量的晚也算没推过；
• 缺省关闭——不配置的房源行为与现在完全一致；只作用于指定户型的预订，整栋单（不指定户型）语义不变。

建议需要多渠道对账的房型开启，并按「未来 12 个月」滚动推送放出量（见 5.1）。

3.7 房间档案（room_profile）

房源细节统一放在户型级 units.ext.room_profile（来自入驻时的「房源字段」表），经 units/create / units/update 的 room_profile 对象整体写入，C 端详情页「房间档案」卡直接渲染。规则：

• 整体合并：传入的键覆盖同名键，未传的键保持原值；传 null 清除整块。
• 白名单：不在下表内的键直接丢弃（不报错）。空值（null / 空串）视为未传。
• 越界报错：枚举取值非法、数值越界、文本超长、图片地址非法 → 400，message 里带字段中文名与可选值。
• C 端渲染时对文本做转义，正文里可以正常使用中文标点与换行（多行文本用 \n）。

4 房源接口

以下示例省略签名三件套（vendor_id / timestamp / sign），实际每个请求体都必须携带（见 §2，或直接用 §7 调试台）。

4.1 城市 / 行政区枚举

{}
→ 200 {
  "code": 0, "list": [
    { "id": 4, "name": "贵阳", "slug": "guiyang",
      "districts": [ { "id": 41, "name": "观山湖区", "slug": "guanshanhu" } ] }
  ], "total": 1
}

4.2 房源列表

{
  "channel": "rental",      // 可选过滤：channel / status / city_id / keyword
  "status": "online"
}

→ 200
{
  "code": 0, "message": "success",
  "list": [
    {
      "id": 1611, "name": "示例·观山遇见旅居", "channel": "rental",
      "status": "online", "price_from": 2400,
      "min_stay_nights": 15,
      "insurance": ["switch_rental", "property"],
      "insurance_types": [ { "key": "switch_rental", "label": "换租保险", "icon": "🔄" }, /*…*/ ]
    }
  ],
  "total": 1
}

4.3 房源详情

{ "id": 1611 }
→ 200 { "code": 0, "project": { /* 同 4.1，另含 address/tags/ext 等 */ }, "units": [ /* 户型数组 */ ] }

4.4 创建房源（默认草稿，不入 C 端）

{
  "name": "观山湖·遇见旅居",
  "channel": "rental",
  "city_id": 4,
  "district_id": 41,
  "address": "观山湖区 · 示例大道 88 号",
  "tags": ["旅居", "近地铁"],
  "price_from": 2400,             // 选填（2026-09）；不传则各户型自带价
  "contact_phone": "13800001234",       // 仅入库（虚拟号绑定），永不回显
  "min_stay_nights": 15,               // 房源默认值；户型级优先（见 3.2 / §5.2）
  "insurance": ["switch_rental", "property"],   // 保险标识（见 §6）
  "units": [
    { "name": "一居 45㎡", "layout_label": "1室1厅", "area_sqm": 45, "rent_monthly": 2400 },
    // 短租房源可只给夜价（rental 同样生效，2026-09）：
    { "name": "庭院房", "area_sqm": 30, "price_night": 268, "min_stay_nights": 3 }
  ],
  "status": "draft"                      // 缺省 draft；draft/offline 不出 C 端
}

→ 200 { "code": 0, "message": "success", "project": { "id": 1611, "status": "draft", /*…*/ } }

4.5 更新房源

{
  "id": 1611,
  "price_from": 2680,
  "tags": ["旅居", "近地铁", "含早"],
  "insurance": ["hotel_cancel", "property"],
  "min_stay_nights": 20,
  "online_booking": true,
  "online_payment": true
}
→ 200 { "code": 0, "project": { /* 更新后全量 */ } }

不可改：city_id、channel、owner_vendor_id；改 name 会同步重生成唯一 slug。

4.6 上下架

{ "id": 1611, "status": "online" }     // online 上架 / offline 下架 / draft 转草稿
→ 200 { "code": 0, "message": "success", "id": 1611, "status": "online" }

4.7 新增户型

{ "project_id": 1611, "name": "两居 68㎡", "layout_label": "2室1厅",
  "area_sqm": 68, "rent_monthly": 3200, "total_qty": 3,
  "room_profile": { "max_guests": 4, "beds": "卧室1：1.8×2.0m 大床" } }   // 房间档案（见 3.7）
→ 200 { "code": 0, "unit": { "id": 3101, /*…含 room_profile 已解析对象…*/ } }

4.8 更新户型（调价 / 间数 / 取消政策等）

{ "id": 3101, "rent_monthly": 3380, "price_night": 128, "total_qty": 5,
  "min_stay_nights": 3,                     // 户型级最短连住（2026-09）；null 清除回落房源级
  "default_closed": false,                   // 默认关房（见 3.6）；null 清除
  "room_profile": { "window_type": "exterior", "smoking": "no" },   // 房间档案（见 3.7），只合并传入的键
  "cancel_policy": { "enabled": true, "days_before": 1, "cutoff_time": "18:00" } }
→ 200 { "code": 0, "unit": { /*…含 default_night_price / min_stay_nights / room_profile 生效值…*/ } }

• 最短连住：传入 min_stay_nights（rental 1-365 / minsu 15-365，越界 400）；传 null 或空串清除，回落房源级 → 频道默认。整栋单（不指定户型）按排序最前的户型执行。出参附 min_stay_nights_source（unit/project/default）。
• 房间档案：传入 room_profile（见 3.7），只合并传入的键、未传的保持原值；传 null 清除整块；未知键静默丢弃，取值/长度非法 400。
• 取消政策：传入 cancel_policy（非法 days_before/cutoff_time 返回 400）；传 null 清除（= 未开通，客户不可取消）。免费取消窗口 = 入住日往前推 days_before 天的 cutoff_time 时刻；客户在窗口内取消自动退款并释放房态。
• 总间数（多间口径 2026-09-10）：total_qty 须为 1-999；调低到低于未来晚已订间数会返回 400（先处理订单再缩容）。

4.9 删除户型

{ "id": 3101 }
→ 200 { "code": 0, "message": "success" }

4.10 房态查询（商家视角）

{ "project_id": 1611, "unit_id": 0, "month": "2026-12" }
→ 200 {
  "code": 0, "month": "2026-12", "base_price_night": 80,
  "min_stay_nights": 15, "insurance": ["switch_rental", "property"],
  "days": [
    // 多间口径：房型 total_qty=3，19 晚被订 2 间（部分可订），20 晚已关房
    { "date": "2026-12-19", "status": "open", "price": 80, "qty": 3, "booked_qty": 2, "remaining": 1 },
    { "date": "2026-12-20", "status": "blocked", "price": 80, "qty": 3, "booked_qty": 0, "remaining": 0 },
    { "date": "2026-12-21", "status": "open", "price": 80, "qty": 3, "booked_qty": 0, "remaining": 3 }
  ]
}

4.11 房源图片（图集）

4.11.1 全量覆盖图集（推荐，2026-09）

{
  "project_id": 1611,
  "unit_id": 3101,                     // 可选；缺省 = 房源级图集（只动房源级，不会碰户型级）
  "photos": [
    { "url": "https://cdn.example.com/p1.jpg", "category": "bedroom", "sort": 0, "is_cover": true,
      "external_id": "IMG-1001" },      // 你们那边的稳定图 id（URL 带签名会变，靠它认同一张图）
    { "url": "https://cdn.example.com/p2.jpg", "category": "living", "sort": 1,
      "width": 1920, "height": 1080, "size_bytes": 480000 }   // 声明值可选，见下「校验」
  ]
}
→ 200 {
  "code": 0, "applied": 8, "added": 5, "updated": 3, "removed": 2,
  "cover": "https://cdn.example.com/p1.jpg", "truncated": false,
  "gallery_total": 12, "warnings": [],
  "photos": [ { /* 覆盖后的完整图集（含 category_label），可直接用来核对 */ } ]
}

4.11.2 单张追加 / 更新

{
  "project_id": 1611,
  "unit_id": 3101,                      // 可选；缺省 = 房源级图集
  "file_path": "https://cdn.example.com/p1.jpg",  // 必填，URL ≤ 500 字符
  "is_cover": true,                       // 设为封面（同实体原封面自动让位）
  "category": "bedroom",                 // 图片分类（可选，缺省 other）
  "external_id": "IMG-1001",             // 稳定图 id（可选）：幂等匹配键
  "sort_order": 0                         // 不传 = 追加到末尾（2026-09 起传入即生效）
}
→ 200 { "code": 0, "updated": true, "photo": { /* 命中已有图时原地更新（updated=true） */ } }

图集元素字段：id / entity_type / entity_id / file_path / category / category_label / external_id / is_cover / sort_order。category_label 为中文名，C 端直接渲染。

4.12 评级提审 / 审核状态

上架闸之一是平台评级审核（rating_status：draft → pending → passed / rejected；rental=好房子 4 维，minsu=旅居彩贝 5 维）。提审与查进度直接走开放接口，不必线下催单：

{
  "id": 1611,
  "dims": { "comfort": 4.5, "green": 4, "tech": 4.6, "safety": 4.4 }
                  // minsu 频道为 scenery / facilities / service / location / culture
}
→ 200 { "code": 0, "rating_status": "pending", "rating_code": "SY-RENT-1611", "dims": { /*…*/ } }

{ "id": 1611 }
→ 200 {
  "rating_status": "rejected", "rating_code": "SY-RENT-1611",
  "dims": { /* 已提交自评分 */ }, "missing_dims": [],
  "dims_meta": [ { "key": "comfort", "label": "舒适", "icon": "🛋" } /*…*/ ],
  "note": "安全维度证明材料不足",   // 驳回原因；passed/rejected 的复核时间见 reviewed_at
  "submitted_at": "2026-09-10T03:20:11Z", "reviewed_at": "2026-09-10T07:41:00Z"
}

• dims 须覆盖该频道全部维度、数值 0–5；缺维度 / 越界 / 未知维度返回 400 并指明字段。
• 被驳回（rejected）修订后可重新提审；提审会清除上一轮 note。平台复核通过（passed）后 projects/status online 才会放行。

5 订单履约（商家接单）

客户在 C 端提交预订单后，商家经开放接口完成接单闭环：定时拉取订单 → 确认生效或拒单 → 拒单自动释放房态。订单按签约商家隔离，联系人手机号只回掩码（139****5678）。

{
  "status": "pending",        // 可选过滤：status / pay_status / project_id
  "project_id": 1611
}
→ 200 { "code": 0, "list": [ {
  "id": 36, "order_no": "BKG-RENTAL-00036", "project_name": "观山湖·遇见旅居",
  "checkin": "2026-12-19", "checkout": "2027-01-08", "nights": 20,
  "price_total": 1600, "commission_rate": 8.00, "commission_fee": 128.00,
  "status": "pending", "pay_status": null,
  "contact_name": "张**", "contact_phone": "139****5678"
} ] }

• 佣金（规则 20）：commission_rate / commission_fee 为下单时锁定的费率与佣金快照（元），结算按快照执行、商家后续费率调整不追溯；未差异化商家按全局基准（缺省 10%）。

{ "id": 36 } → 200 { "code": 0, "booking": { /* 同上，单条 */ } }

{ "id": 36 } → 200 { "code": 0, "status": "confirmed" }

{ "id": 36 }
→ 200 { "code": 0, "status": "cancelled", "pay_status": null }

订单状态与支付口径

Webhook 事件通知（平台 → 商家）

客户动作触发的订单变更，平台会主动推送签名事件到你为商家配置的通知地址（接入单里提供 URL 即可），不必轮询等单：

推送为 POST JSON，body 即开放接口同款结构：event + vendor_id + order（订单对象，手机号不外传）+ timestamp + sign。验签与开放接口同一算法（对去掉 sign/timestamp 的参数扁平排序后 HMAC-SHA256），收到后先验签再处理：

// Node 验签示例（与平台 hmac_auth.cjs 同算法）
app.post('/hooks/booking', (req, res) => {
  const body = req.body;
  const payload = { ...body };
  delete payload.sign;
  const flat = flatten(payload);              // 与请求签名同一套 flatten
  flat.timestamp = String(body.timestamp);
  const expect = crypto.createHmac('sha256', HMAC_KEY)
    .update(Object.keys(flat).sort().map(k => k + '=' + flat[k]).join('&')).digest('hex');
  if (expect !== String(body.sign).toLowerCase()) return res.status(401).end();
  // 处理 body.event / body.order …
  res.status(200).end('ok');                    // 2xx 即视为送达
});

6 房态日历与短住规则

5.1 批量设置房态 / 夜价 / 放出间数

{
  "project_id": 1611,
  "unit_id": 0,                        // 0 或缺省 = 项目级（整栋 / 不限房型，容量恒 1）
  "dates": ["2026-12-10", "2026-12-11"],
  "status": "blocked",                 // 可选：blocked 关房 / open 开房；缺省 = 保持各晚现状（只改价/净可售）
  "price_night": null,                 // blocked 可同时设价；open + 价格 = 夜价覆盖；open + null = 不改价
  "qty": null,                         // ★ 放出总量覆盖（1-999，仅房型级）：open + qty = 该晚只放 N 间；不传 = 用 total_qty
  "available_qty": null                  // ★ 净可售（0-999，推荐，见 3.5）：与该晚的 qty 二选一；写回 qty 会把基线清空
}
→ 200 {
  "code": 0, "affected": 2, "dates": 2,
  "days": [                          // 推完即可对账（不必再查一次日历）
    { "date": "2026-12-10", "status": "open", "qty": 2, "qty_base": 2,
      "available_qty": 2, "booked_qty": 2, "remaining": 2 }
  ]
}

• status 可选（2026-09-22）：只推价格 / 净可售时可以不传 status——对应间夜保持原状态（blocked 晚保持关房、open 晚保持可订），无差异行的晚按默认 open 建行。status: open 且价、放出量均不传 = 显式「恢复默认」。
• dates 支持对象数组（2026-09-22）：逐晚独立值，一次请求混合推送不同房态 / 价格——

  [{ "stay_date": "2026-12-10", "available_qty": 0, "status": "open" },
   { "stay_date": "2026-12-11", "price_night": 188 }]

  字段缺省含义与顶层一致（status 缺省 = 保持现状）。平铺字符串数组 + 顶层字段形态继续可用（所有晚同值）。
• 统一用 available_qty 管理房态（推荐）：available_qty: 0 + status: open 即「该晚 0 间可售」——剩余派生为 0、C 端显示售罄，效果等同关房，且随时可推一个正数恢复；不必在 open / blocked 之间切换语义。
• 已订晚（booked_qty>0）不可关房：返回 400 并列出日期，须先取消订单；改价 / 调放出量不受限。
• 未设置过的晚天然可订、放出 = 房型 total_qty（除非该房型开了「默认关房」，见 3.6）；「恢复默认」= status=open 且价、放出量均不传：清除差异行，有占用的晚保留占用计数、仅清覆盖回默认。
• qty 与已订（多间口径 2026-09-10）：qty 低于该晚已订间数返回 400（先取消订单或调高）；qty 改变只影响当晚可订余量，已订单不受影响。剩余 = max(0, qty||total_qty − booked_qty)。
• available_qty（2026-09 方案 B）：不受「不得低于已订」限制（它本身就是净数，推送时点的已订自动进基线）；qty 与 available_qty 同时传返回 400。详见 3.5。
• 覆盖价参与下单计价（2026-09-10 起）：订单金额 = 逐晚「覆盖价 || 默认夜价」合计 × 间数。周末 / 节假日分档 = 把对应日期批量 open + price_night；平日不传即回落默认。订单占用不清除当晚覆盖价，取消释放后商家差异行（价 / qty / 关房）原样保留。
• 可订窗口：单次 ≤ 400 晚、可滚动写更远；C 端日历展示当月起 12 个月，建议按「未来 12 个月」滚动维护。

5.2 最短连住（min_stay_nights）

旅居/短住按连续入住售卖：平台缺省口径为 rental=15 晚、minsu=15 晚。商家可覆盖，2026-09 起生效顺序为「户型 > 房源 > 频道默认」：户型级写 units.ext.min_stay_nights（units/create / units/update 直接传 min_stay_nights），房源级 projects.ext.min_stay_nights 降级为房源默认值。取值范围：rental 1–365 晚，minsu 15–365 晚、不得低于 15 晚（越界返回 400）。

整栋单（下单不指定户型）按排序最前的户型取值——与取消政策同一套回退，因此「最短连住」和「取消政策」两条住宿规则都可以只在户型上配，不必记住哪个在房源、哪个在户型。

三处同口径校验：C 端日历选段、下单页、平台下单接口 POST /api/juzhu/booking（不足返回 400「该房源须连住至少 N 晚」）。下单成功即占用这些晚，取消自动释放。户型数组与房态日历出参均随行返回生效值 min_stay_nights，页面直接读，不要回落到房源级或自设默认值。

5.3 房源交易能力（online_booking / online_payment）

projects/create / projects/update 按房源配置两个独立布尔能力：online_booking = 客户在线选房并提交订单、商家确认后线下收款；online_payment = 客户在线选房后进入收银台、支付完成再由商家确认。两项可同时开启，但至少开启一项，与 rental/minsu 频道无关；新建时两项均省略则默认仅开启 online_booking。两项都开时，C 端由客户选择；接口下单用 transaction_mode: "booking" | "payment" 指定，缺省优先 booking。catalog / 详情 / 房态日历出参均返回两个能力位，并保留 bookable 作为“至少一项可用”的兼容汇总字段。

7 保险标识

商家为房源配置的「入住保障」，随 catalog / 详情 / 房态日历下发 C 端展示。枚举由平台统一维护，接口只接受以下 key，未知 key 返回 400：

配置入口：projects/create / projects/update 传 insurance 数组；清空传 []。出参同时给出 insurance（key 数组）与 insurance_types（含 label/icon，可直接渲染）。

Webhook 通知与审核自动上架（2026-09-22）

审核通过自动上架（auto_publish）

默认行为：评级复核通过后，商家仍需自行调 projects/status 推 online。若希望复核通过即自动上架，在 projects/create 或 projects/update 传 auto_publish: true（存 ext.auto_publish，随时可传 false 关闭）。自动上架复用与商家推送完全相同的上架闸（评级通过 / 逐户型默认夜价 > 0 / 图片抽检）与交易方式校验：闸全过 → 直接 online；任一不过 → 保持 draft，具体原因通过 rating.reviewed webhook 的 auto_publish.reason 带回，商家补齐后自行推送上架即可。

评级审核结果 Webhook（rating.reviewed）

评级复核（通过 / 驳回）完成时，平台向商家 webhook_url POST 一条签名通知，商家无需再轮询 rating/status。webhook_url 由商家自助配置：B 端后台「房源管理」（b-listing-mgmt.html）顶部「🔔 Webhook 通知」卡填写并保存，支持一键发送 webhook.test 连通性测试（同步回传送达结果）；推送与测试统一经平台出网防护层（内网 / 环回 / 云元数据地址拒绝）。

推送 5 秒超时，失败重试 3 次（5s/30s/120s）后放弃——webhook 只通知不担保必达，商家以 projects/rating/status 拉取对账兜底。响应返回任意 2xx 即视为送达。

附 · 常见接入疑问（答疑纪要 2026-09-10）

以下为首批接入方答疑结论，与线上实现同步校准；与本页正文冲突处以正文为准。

8 在线调试台

在本页直接签名并调用真实接口：选择接口 → 填业务参数 JSON（无需自己写 vendor_id/timestamp/sign）→ 发送。签名在你的浏览器本地完成，hmac_key 只留在本机（可选「记住」，存 localStorage，换机不带）。

9 错误码

10 联调与回归

平台提供端到端回归脚本（Node，走真实 HTTP 签名链路），接入方可用它自检签名实现是否正确：

# 覆盖：regions 枚举→创建→评级提审/状态→上架→C 端可见→保险/连住更新→房态/夜价→
#       下单逐晚计价→订单闭环(webhook)→下架→越权负例→清理
node scripts/housing_vendor_hmac_regression.cjs [base_url]   # 默认 http://127.0.0.1:8766
node scripts/vendor_hmac_regression.cjs                       # 家政开放接口同机制回归