房源接入 API

1 接入概览

统一服务平台采取"住建主导、贝壳承建、同业开放"原则。机构通过本 API 推送房源与运营记录，平台完成数据清洗、价格红线校验、合规验真后统一上架；住建后台只读监管，数据接受省社科院/东南大学/省房协月度审计。

三种接入模式

环境

2 认证授权

2.1 资质前置

仅向以下主体颁发凭证：

• 住建厅"运营主体白名单"在册机构（≥A 级）
• 省级国资 / 城投及其授权代理
• 金融机构（银行 / 信托）持有的保租房项目方

申请入口：运营主体白名单 → 申请接入，材料齐全后 5 个工作日完成审核。

2.2 OAuth 2.0 (client_credentials)

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=ziroom_jiangsu_2026
&client_secret=****
&scope=listings:write filings:write

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "listings:write filings:write"
}

2.3 请求签名（敏感写操作）

除 Bearer Token 外，写接口需要附加 X-Signature（HMAC-SHA256），算法：

signature = HMAC_SHA256(
  client_secret,
  HTTP_METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + sha256(body)
)

请求头示例：

Authorization: Bearer eyJhbGciOi...
X-Timestamp: 1717574400
X-Nonce: a3f8c2-...
X-Signature: sha256=8a1f...
X-Operator-Id: ziroom_jiangsu_2026

2.4 限流

3 房屋数据字典

字典由住建厅主导制定，分为静态披露字段（房屋本体属性）与动态运营记录（生命周期事件）。所有接入方按本字典推送，平台清洗后统一展示。

3.1 静态字段（Listing）

3.2 动态运营记录（Event）

3.3 好房子四维度评级

{
  "house_quality": {
    "comfort":  4,   // 舒适：独卫、采光、隔音
    "green":    3,   // 绿色：节能门窗、空气循环
    "smart":    5,   // 科技：智能门锁、智能电表、HDR 监控
    "safety":   4    // 安全：消防、应急通道、保险覆盖
  }
}

评级 1–5；总星 = round(avg)。住建厅季度抽检，连续两季度低于 3 星将被强制下架整改。

3.4 图片资源

推送时使用对象引用，平台拉取后 CDN 化：

{
  "photos": [
    { "url": "https://cdn.ziroom.com/...", "tag": "LIVING_ROOM", "order": 1 },
    { "url": "https://cdn.ziroom.com/...", "tag": "BEDROOM_MASTER", "order": 2 }
  ]
}

分类标签：LIVING_ROOM / BEDROOM_MASTER / BEDROOM_SECOND / KITCHEN / BATHROOM / BALCONY / EXTERIOR / FLOORPLAN

4 核心接口

4.1 房源批量推送（Upsert）

POST /v1/listings:batchUpsert
Authorization: Bearer ...

{
  "listings": [
    {
      "external_id": "ZR-NJ-2024-00188",
      "operator_id": "ziroom_jiangsu_2026",
      "project_name": "江宁·梧桐公馆人才公寓",
      "address": {
        "city": "南京市",
        "district": "江宁区",
        "street": "双龙大道 1688 号",
        "building": "3 栋",
        "room": "1506"
      },
      "geo": { "lng": 118.857, "lat": 31.927 },
      "layout": "1B1H",
      "area_sqm": 45.0,
      "orientation": "S",
      "floor": { "current": 15, "total": 26 },
      "rent_monthly": 2380,
      "service_fee_pct": 0.08,
      "market_price_ref": 3200,
      "house_quality": { "comfort":4, "green":3, "smart":5, "safety":4 },
      "amenities": ["AC","FRIDGE","WASHER","WIFI","SMART_LOCK","ELEVATOR"],
      "photos": [ /* … ≥ 6 张 … */ ],
      "access_mode": "SELF",
      "cert_no": "宁住保字〔2024〕第 0188 号"
    }
  ]
}

响应（部分成功）

{
  "accepted": 198,
  "rejected": 2,
  "results": [
    {
      "external_id": "ZR-NJ-2024-00188",
      "listing_id": "L-JS-NJ-9f3a...",
      "status": "PENDING_REVIEW"
    },
    {
      "external_id": "ZR-NJ-2024-00200",
      "status": "REJECTED",
      "error": { "code": "E_PRICE_REDLINE", "message": "租金 ¥3680 超出江宁区一室一厅红线 ¥3400" }
    }
  ]
}

4.2 房源状态变更

PUT /v1/listings/L-JS-NJ-9f3a.../status

{
  "action": "DELIST",        // LIST | HOLD | DELIST
  "reason": "已成交",
  "effective_at": "2026-06-10T00:00:00+08:00"
}

4.3 上报运营事件

POST /v1/listings/L-JS-NJ-9f3a.../events

{
  "type": "CONTRACT_SIGNED",
  "occurred_at": "2026-06-05T14:32:00+08:00",
  "payload": {
    "filing_no": "NJ-FL-2026-0010088",
    "tenant_hash": "sha256:b1f...",
    "term_months": 12,
    "monthly_rent": 2380,
    "deposit": 0,           // 省级标准：免押金
    "insurance": ["home_property","switch_rental"]
  }
}

4.4 查询房源

4.5 三方备案接口

平台代为对接住建厅备案系统；机构推送即视为已尽备案义务，回执 5 分钟内返回。

5 价格红线校验

每条房源在 batchUpsert 时同步校验，校验源 = 江苏住房租赁数据治理委员会发布的"区域 × 户型 × 季度"上限表。

{
  "city": "南京市",
  "district": "江宁区",
  "layout": "1B1H",
  "redline_monthly": 3400,
  "market_avg": 3120,
  "updated_at": "2026-06-01",
  "audit_by": ["清华大学","东南大学","省社科院"]
}

6 备案回流 Webhook

住建系统回执由平台中转至机构端。机构在控制台配置 callback URL，平台用与请求签名相同的 HMAC 算法签名后投递，3 次重试。

事件类型

Payload 示例

POST https://ziroom.com/hooks/bzf-jiangsu
X-BZF-Signature: sha256=...

{
  "event": "filing.confirmed",
  "occurred_at": "2026-06-05T14:35:12+08:00",
  "data": {
    "listing_id": "L-JS-NJ-9f3a...",
    "filing_no": "NJ-FL-2026-0010088",
    "valid_until": "2027-06-04"
  }
}

7 错误码

8 接入 SLA 与流程

承诺 6–8 周完成接入。流程：

1. Week 0–1：资质审核（白名单备案 / 网安等保 / 数据安全协议）
2. Week 2：颁发沙箱凭证 + 1V1 技术对接群
3. Week 3–4：字典映射 + 接口联调 + 单元测试
4. Week 5：UAT 全链路演练（含 redline / webhook / 备案回流）
5. Week 6：合规审计 + 隐私评估（PIA）+ 安全渗透测试
6. Week 7–8：灰度（10% 房源）→ 全量切流 → 住建备案

运行期 SLA

9 Excel 模板（非 API 渠道）

面向尚未具备 API 能力的小型机构 / 国资项目方，提供统一 Excel 模板（与上述字典字段 1:1 对应）。机构填写后上传，平台后台批量导入。

• 下载模板：listings-template-v1.2.xlsx
• 导入入口：运营主体白名单 → 数据导入
• 单次最多 5000 行；导入后 10 分钟内邮件返回校验报告。