房源接入 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）。projects/create 可带 units[] 一次建全，后续 units/create 追加。

3.3 房态日历（逐晚库存）

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,
  "contact_phone": "13800001234",       // 仅入库（虚拟号绑定），永不回显
  "min_stay_nights": 15,               // 最短连住，写入 ext（见 §5）
  "insurance": ["switch_rental", "property"],   // 保险标识（见 §6）
  "units": [
    { "name": "一居 45㎡", "layout_label": "1室1厅", "area_sqm": 45, "rent_monthly": 2400 }
  ],
  "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,
  "stay_bookable": 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 }
→ 200 { "code": 0, "unit": { "id": 3101, /*…*/ } }

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

{ "id": 3101, "rent_monthly": 3380, "price_night": 128,
  "cancel_policy": { "enabled": true, "days_before": 1, "cutoff_time": "18:00" } }
→ 200 { "code": 0, "unit": { /*…*/ } }

• 取消政策：传入 cancel_policy（非法 days_before/cutoff_time 返回 400）；传 null 清除（= 未开通，客户不可取消）。免费取消窗口 = 入住日往前推 days_before 天的 cutoff_time 时刻；客户在窗口内取消自动退款并释放房态。

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": [
    { "date": "2026-12-19", "status": "booked", "price": 80, "source": "booking", "booking_id": 36 },
    { "date": "2026-12-20", "status": "open", "price": 80 }
  ]
}

4.11 房源图片（图集）

{
  "project_id": 1611,
  "unit_id": 3101,                      // 可选；缺省 = 房源级图集
  "file_path": "https://cdn.example.com/p1.jpg",  // 必填，URL ≤ 500 字符
  "is_cover": true,                       // 设为封面（同实体原封面自动让位）
  "sort_order": ""                        // 缺省追加到末尾
}
→ 200 { "code": 0, "photo": { /* id / entity_type / file_path / is_cover / sort_order */ } }

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 或缺省 = 项目级（整栋 / 不限房型）
  "dates": ["2026-12-10", "2026-12-11"],
  "status": "blocked",                 // blocked 关房；open 开房
  "price_night": null                  // blocked 可同时设价；open + 价格 = 夜价覆盖；open + null = 恢复默认
}
→ 200 { "code": 0, "affected": 2, "dates": 2 }

• 已订晚不可改：区间内有 booked（订单占用）返回 400 并列出日期，须先取消订单。
• 未设置过的晚天然可订；「恢复默认价」= 清除该晚价格覆盖，回落默认夜价。
• 覆盖价参与下单计价（2026-09-10 起）：订单金额 = 逐晚「覆盖价 || 默认夜价」合计。周末 / 节假日分档 = 把对应日期批量 open + price_night；平日不传即回落默认。订单占用的晚翻为 booked 时保留当晚覆盖价，取消释放后该晚差异行随之清除（须重设）。
• 可订窗口：单次 ≤ 400 晚、可滚动写更远；C 端日历展示当月起 12 个月，建议按「未来 12 个月」滚动维护。

5.2 最短连住（min_stay_nights）

旅居/短住按连续入住售卖：平台缺省口径为 rental=15 晚、minsu=1 晚，商家可用 ext.min_stay_nights（1–365）按房源覆盖。三处同口径校验：C 端日历选段、下单页、平台下单接口 POST /api/juzhu/booking（不足返回 400「该房源须连住至少 N 晚」）。下单成功即占用这些晚，取消自动释放。

5.3 按晚预订开关（stay_bookable）

房源默认仅 400 电话咨询（C 端不展示价格日历、下单接口拒绝）。projects/create / projects/update 传 "stay_bookable": true 开通后，C 端才展示日历并支持在线下单（catalog / 详情 / 房态日历出参均带 bookable 能力位）。关闭传 false（已生成订单不受影响，可正常确认/取消）。判断由平台服务端唯一执行，tag / 频道不参与。

7 保险标识

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

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

附 · 常见接入疑问（答疑纪要 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                       # 家政开放接口同机制回归