📖 接入概览

智慧全景开放平台将全景漫游、空间商城、营销玩法、AI 生产等全部平台能力以 RESTful API 形式开放。第三方系统（小程序、ERP、官网、数字大屏）可通过 API 读取空间数据、下发热点、同步订单，实现「实景空间 + 业务系统」的深度集成。

🔐 鉴权与签名（HMAC-SHA256）

每个租户在「工作台 → 开放平台」可创建应用，获得 AccessKey 与 SecretKey。所有请求必须携带以下 Header：

签名算法

1）将「HTTP方法、路径、排序后的查询串、请求体SHA256、时间戳、Nonce」按换行符拼接为待签名串；2）以 SecretKey 为密钥做 HMAC-SHA256；3）取十六进制小写作为 X-Signature。

// 待签名串 stringToSign
stringToSign = METHOD + "\n" + PATH + "\n" + sortedQuery + "\n"
             + sha256Hex(body) + "\n" + timestamp + "\n" + nonce

signature = HMAC_SHA256(SecretKey, stringToSign).hex().toLowerCase()

// Node.js 签名示例
const crypto = require('crypto');
function sign({ method, path, query = {}, body = '', sk, ts, nonce }) {
  const sorted = Object.keys(query).sort()
    .map(k => k + '=' + encodeURIComponent(query[k])).join('&');
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const s2s = [method, path, sorted, bodyHash, ts, nonce].join('\n');
  return crypto.createHmac('sha256', sk).update(s2s).digest('hex');
}

📦 通用约定

错误码

订单状态机

pending（待支付）→ paid（已支付）→ shipped（已发货/待核销）→ completed（已完成）；售后分支：refunding（退款中）→ refunded（已退款）；支付超时进入 cancelled。

🌐 全景项目接口

🛍 空间商城接口

🎯 营销玩法接口

📍 位置服务（高德地图）

🤖 AI 与算力接口

🟨 JavaScript SDK

浏览器 / Node 通用。安装：npm i @snowland/sdk，或 CDN 引入。SDK 自动完成签名与重试。

import SmartPano from '@smartpano/sdk';

const sl = new SmartPano({ ak: 'ak_live_8f3a…', sk: 'sk_live_29c1…' });

// 拉取项目并嵌入漫游 iframe
const { data } = await sl.pano.detail({ id: 1 });
document.querySelector('#pano').innerHTML =
  sl.embed(data.project, { width: '100%', height: 480, watermark: true });

// 空间内下单
const order = await sl.order.create({
  sku_id: 110, num: 1, coupon_id: 501,
  address: { name: '王先生', phone: '138****0000' }
});
await sl.order.pay({ order_id: order.data.id, channel: 'mock' });

🐍 Python SDK

安装：pip install snowland-sdk。适用于 ERP 订单同步、批量热点下发、数据回流等后端场景。

from snowland import Client

cli = Client(ak="ak_live_8f3a…", sk="sk_live_29c1…")

# 同步昨日订单到 ERP
orders = cli.get("/order/list", params={
    "status": "paid", "page": 1, "page_size": 100
})
for o in orders["data"]["list"]:
    erp.push(o)

# 批量下发商品热点
cli.post("/pano/hotspot/save", json={
    "project_id": 1, "node_id": 101, "type": "product",
    "title": "北欧布艺单人沙发", "yaw": 25, "pitch": -8,
    "goods_id": 11, "sku_id": 110
})