开放接口签名、额度和资源路径说明

必填请求头

• X-WH-App-Key：控制台创建凭证时返回的 appKey。
• X-WH-Timestamp：当前请求时间戳，用于防止过期请求。
• X-WH-Signature：按请求方法和路径计算出的签名。

签名输入

signingKey = sha256(appSecret)
signature = HMAC-SHA256(signingKey, METHOD + "\n" + PATH + "\n" + TIMESTAMP)

PATH 使用带 /api 前缀的接口路径，不包含查询参数。

环境变量

• baseUrl：https://open.whbdvr.com
• appKey：控制台开放接口页创建凭证后返回。
• appSecret：只在创建凭证时展示一次，请仅用于本地调试环境。

示例请求

GET {{baseUrl}}/api/external/open-api/tenant/profile
GET {{baseUrl}}/api/external/open-api/orders

预请求脚本

const method = pm.request.method.toUpperCase();
const path = pm.request.url.getPath();
const timestamp = Date.now().toString();
const appKey = pm.environment.get('appKey');
const appSecret = pm.environment.get('appSecret');
const signingKey = CryptoJS.SHA256(appSecret).toString();
const payload = [method, path, timestamp].join('\n');
const signature = CryptoJS.HmacSHA256(payload, signingKey).toString();

pm.request.headers.upsert({ key: 'X-WH-App-Key', value: appKey });
pm.request.headers.upsert({ key: 'X-WH-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-WH-Signature', value: signature });

如果请求带查询参数，签名仍使用路径部分，例如 /api/external/open-api/orders。

JavaScript SDK

SDK 封装签名、请求头和当前开放资源方法，适合 Node.js 服务端直接复用。不要在浏览器里放入 appSecret。

const { WhiteholeOpenApiClient } = require('./whitehole-open-api-sdk');

const client = new WhiteholeOpenApiClient({
  baseUrl: process.env.WH_OPEN_API_BASE_URL,
  appKey: process.env.WH_OPEN_API_APP_KEY,
  appSecret: process.env.WH_OPEN_API_APP_SECRET,
  retry: 2,
  retryOnStatusCodes: [429, 500, 502, 503, 504],
});

const overview = await client.getBusinessOverview({
  startDate: '2026-05-01',
  endDate: '2026-05-07',
});

SDK 覆盖

• 导出 SDK_VERSION、OPEN_API_ERROR_CODES、WhiteholeOpenApiClient、signOpenApiRequest 和 requestOpenApi。
• 内置门店资料、商品、库存、会员、订单和经营报表资源方法。
• 提供 buildPageQuery 统一分页参数，列表接口默认限制 pageSize 不超过 100。
• 支持 retry、retryDelayMs 和 retryOnStatusCodes，可对 OPEN_API_LIMIT_EXCEEDED 场景按服务端状态做退避重试。
• 提供 whitehole-open-api-sdk.d.ts 类型声明和 whitehole-open-api-sdk.CHANGELOG.md 版本变更记录。
• 提供 whitehole-open-api-sdk.RELEASE.md 发布说明和 whitehole-open-api-sdk.verify.js 发布前校验脚本。
• 提供 whitehole-open-api-sdk.package.json 包清单和 whitehole-open-api-sdk.README.md，发布到私有 npm 仓库前可重命名为标准包文件。
• 请求带查询参数时，签名仍只使用路径部分，和开放接口服务端校验规则一致。

私有包发布准备

当前官网以静态文件交付 SDK。若要发布到企业内部 npm 仓库，请把 SDK 文件放入独立目录，并将包清单重命名为 package.json 后再打包。

cp whitehole-open-api-sdk.package.json package.json
node whitehole-open-api-sdk.verify.js
npm pack --dry-run

包内文件

• whitehole-open-api-sdk.js：CommonJS SDK 主文件。
• whitehole-open-api-sdk.d.ts：TypeScript 类型声明。
• whitehole-open-api-sdk.README.md：包使用说明。
• whitehole-open-api-sdk.CHANGELOG.md：版本变更记录。
• whitehole-open-api-sdk.RELEASE.md：发布检查说明。

外部 BI 同步经营指标

适合已经购买开放接口和经营报表模块的门店，把经营概览、经营趋势和指标分组同步到外部 BI 或集团看板。

WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
WH_BI_WEBHOOK_URL=https://bi.example.com/whitehole \
node whitehole-open-api-bi-sync-example.js

场景覆盖

• 调用 getBusinessOverview、getBusinessTrend 和 getBusinessMetricGroups。
• 按 WH_SYNC_START_DATE 和 WH_SYNC_END_DATE 控制同步日期。
• 未配置 WH_BI_WEBHOOK_URL 时只在服务端输出 JSON，便于本地调试。

ERP 同步商品和库存

适合已经购买开放接口和商品与库存模块的门店，把商品列表和库存流水同步到外部 ERP 或采购系统。

WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
WH_ERP_WEBHOOK_URL=https://erp.example.com/whitehole \
node whitehole-open-api-erp-inventory-example.js

场景覆盖

• 调用 listProducts 和 listStockRecords。
• 通过 WH_SYNC_PAGE_SIZE 控制单页数量，SDK 会把 pageSize 限制在 100 以内。
• 未配置 WH_ERP_WEBHOOK_URL 时只在服务端输出 JSON，便于本地调试。

会员营销系统同步增长与复购

适合已经购买开放接口和会员与营销模块的门店，把会员列表、消费记录和增长复购汇总同步到外部营销系统。

WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
WH_MARKETING_WEBHOOK_URL=https://marketing.example.com/whitehole \
node whitehole-open-api-member-marketing-example.js

场景覆盖

• 调用 listMembers、listMemberConsumes 和 getMemberGrowthRetention。
• 按 WH_SYNC_START_DATE 和 WH_SYNC_END_DATE 控制消费与复购统计窗口。
• 未配置 WH_MARKETING_WEBHOOK_URL 时只在服务端输出 JSON，便于本地调试。

Node.js 服务端示例

下载示例后，在服务端设置 WH_OPEN_API_APP_KEY 和 WH_OPEN_API_APP_SECRET 环境变量，再执行脚本测试签名请求。

WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
node whitehole-open-api-node-example.js

示例覆盖

• 使用 Node.js 原生 crypto 生成 sha256(appSecret)。
• 使用 HMAC-SHA256 计算 X-WH-Signature。
• 示例请求 /api/external/open-api/tenant/profile 和 /api/external/open-api/orders。

PHP 服务端示例

下载示例后，在 PHP 服务端设置 WH_OPEN_API_APP_KEY 和 WH_OPEN_API_APP_SECRET 环境变量，再用命令行执行脚本。

WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
php whitehole-open-api-php-example.php

示例覆盖

• 使用 hash('sha256') 生成 sha256(appSecret)。
• 使用 hash_hmac('sha256') 计算 X-WH-Signature。
• 示例请求 /api/external/open-api/tenant/profile 和 /api/external/open-api/orders。

Java 服务端示例

下载示例后，使用 JDK 11 或更高版本编译运行。示例只依赖 JDK 标准库，通过环境变量读取凭证。

javac WhiteholeOpenApiExample.java
WH_OPEN_API_APP_KEY=your-app-key \
WH_OPEN_API_APP_SECRET=your-app-secret \
java WhiteholeOpenApiExample

示例覆盖

• 使用 MessageDigest 生成 sha256(appSecret)。
• 使用 Mac.getInstance("HmacSHA256") 计算 X-WH-Signature。
• 示例请求 /api/external/open-api/tenant/profile 和 /api/external/open-api/orders。