HPDC - HopoDevelopClub | 开发者开放平台 & 凭证控制中心

HPDC (HopoDevelopClub) 是 Hopo 生态专为开发者打造的开放技术互联平台，支持 Shopo 三方聚合支付、Shopo 开放电商网关 以及 HopoAuth 统一身份认证 (OIDC SSO)。

Shopo 三方聚合支付

提供秒级创建收银台、订单状态查询、退款及带 HMAC 签名的 Webhook 异步回调能力。

Shopo 商家开放 API

商品发布与批量检索、商户订单处理及多仓库存毫秒级同步联动。

HopoAuth 统一认证 (SSO)

基于国际标准 OIDC / OAuth 2.0 PKCE 架构，实现全生态跨子域单点登录与 AQL 校验。

AQL 管理员特权校验平台

在线申请专属 AQL 密钥凭证，实现登录即自动授予目标站点原生最高 Admin 权限。

接入标准四步流程

获取凭证：在 HopoAuth & AQL 凭证申请中心申请获得 Client ID、Client Secret 与 AQL Key / Secret。
环境准备：根据业务语言下载对应的 HPDC SDK 工具包（支持 Node.js、Python、Java 等）。
沙盒测试：使用测试端点与 HMAC-SHA256 在线签名工具完成接口连通与数据校验。
上线发布：将生产 API 域名切换为 https://dev.hopostudio.xyz 即可正式投入运营。

HopoAuth 客户端与 HopoAQL 凭证申请管理中心

在此统一申请并管理您的 Hopo 生态应用凭证（包含 HopoAuth OAuth 2.0 Client 凭据与 HopoAQL 管理员特权校验密钥）。

需使用 HopoAuth 账号自行登录

使用 HopoAuth 账号完成认证（SYS 类客户端 dev_hopo），即可申请与管理全生态凭证。

AQL 管理员快速登录校验规范与门禁机制

AQL（Admin Quickly Login）是 Hopo 生态链标准协议：当系统管理员登录接入了 AQL 的站点时，自动授予该站点最高原生 Admin 权限。

核心判别特征：不管用户是谁，只要在 HopoAuth 中的角色为管理员 (`is_admin === 1`)，返回的动态密文在第 7 位 (index 6) 为 'a' 且第 15 位 (index 14) 为 '8'，站点端即可完成识别与角色提权。

HopoSys 前后端门禁与鉴权代码 (Node.js / Express)

// 1. 项目本地配置 config.js
const appConfig = {
    aql_support: true, // 门禁开关：只有开启且配置了 aql_api 时才执行 AQL
    aql_api_key: "aql_live_5f273b692244",
    aql_secret: "sec_aql_c52b50c178a25561351acea0ce3dc30c"
};

// 2. Web 登录回调处理
function handleHopoAuthCallback(userData) {
    // 门禁判断：若项目未开启 AQL 支持，直接跳过
    if (!appConfig.aql_support || !appConfig.aql_api_key) {
        return { role: 'user', username: userData.username };
    }

    // 动态提取 AQL 校验 Token
    const aqlToken = userData['beBPqGduwTpzrbhp'];
    
    // 管理员角色判定：第 7 位为 'a' 且 第 15 位为 '8'
    if (aqlToken && aqlToken.charAt(6) === 'a' && aqlToken.charAt(14) === '8') {
        console.log("[AQL 触发] 识别到管理员账号，自动赋予该站点原生 Admin 权限！");
        return { role: 'admin', username: userData.username, is_admin: true };
    }

    return { role: 'user', username: userData.username };
}

API Key 密钥鉴权与 HMAC-SHA256 签名规范

HPDC 开放平台的所有 RESTful 请求均需在 HTTP 请求头中携带合法的身份鉴权信息。

Header 名称	类型	是否必填	说明与示例
`X-Shopo-Api-Key`	String	必填	商户 API Key（例：`hop_live_981273918237`）
`X-Shopo-Signature`	String	必填	HMAC-SHA256 签名散列串（使用 API Secret 签名）
`X-Shopo-Timestamp`	Integer	必填	当前 Unix 时间戳（秒），防重放攻击（有效期 ±300s）

计算签名示例 (JavaScript)

const crypto = require('crypto');

function generateSignature(secretKey, timestamp, requestBody) {
    const rawPayload = `${timestamp}.${typeof requestBody === 'string' ? requestBody : JSON.stringify(requestBody)}`;
    return crypto.createHmac('sha256', secretKey).update(rawPayload).digest('hex');
}

创建支付收银台会话

调用此接口生成带有唯一 session_id 的收银台链接，引导用户跳转完成付款。

请求参数 (Body JSON)

字段名	类型	必填	描述
`merchant_id`	String	必填	商户唯一标识号（例：`mer_shopo_8829`）
`out_trade_no`	String	必填	商户系统内部唯一订单号（32位以内）
`total_amount`	Integer	必填	支付金额（单位：分，例：29900 表示 299.00 元）
`currency`	String	必填	三位货币代码，默认 `CNY` 或 `USD`
`notify_url`	String	必填	支付成功后异步 Webhook 接收地址（须以 https:// 开头）

响应结果示例 (HTTP 200 OK)

{
  "code": 200,
  "status": "success",
  "data": {
    "session_id": "cs_pay_998123719283",
    "out_trade_no": "ORDER_20260804_0091",
    "payment_url": "https://pay.hopostudio.xyz/checkout/cs_pay_998123719283",
    "total_amount": 29900,
    "currency": "CNY",
    "expires_at": "2026-08-10T12:00:00Z"
  }
}

查询支付订单状态

根据商户订单号 out_trade_no 主动向网关查询支付单的最新实时交易状态。

响应结果示例 (HTTP 200 OK)

{
  "code": 200,
  "status": "success",
  "data": {
    "out_trade_no": "ORDER_20260804_0091",
    "trade_state": "SUCCESS",
    "transaction_id": "hop_tx_881923019283",
    "total_amount": 29900,
    "paid_at": "2026-08-10T09:45:12Z",
    "payment_method": "WECHAT_PAY"
  }
}

申请订单退款

针对已成功支付的订单发起全额或部分退款，资金将原路返回给买家。

请求体示例 (JSON)

{
  "out_trade_no": "ORDER_20260804_0091",
  "out_refund_no": "REFUND_20260810_001",
  "refund_amount": 29900,
  "refund_reason": "用户申请商品退货"
}

关闭 / 撤销支付单

对于未支付或超时的支付会话执行主动关闭，防止用户重复付款。

{ "out_trade_no": "ORDER_20260804_0091", "reason": "订单已超时关闭" }

Webhook 异步通知与验签规范

当用户完成支付后，网关会通过 POST 请求向商户提供的 notify_url 发送异步回调。

重要：商户接收到通知后，必须计算并对比 X-Shopo-Signature 确保报文未被篡改，处理成功后需返回 HTTP 200 及 {"code":"SUCCESS"}。

商品列表分页查询

查询商户店铺下的在线商品库及库存规格。

{
  "code": 200,
  "data": {
    "total": 42,
    "list": [
      { "product_id": "prod_1001", "name": "Hopo Developer Pro 会员", "price": 19900, "stock": 999 }
    ]
  }
}

发布与更新商品

创建新商品或基于 product_id 更新现有商品属性。

创建商户电商订单

在 Shopo 电商中控创建订单并锁定对应库存。

库存联动同步接口

支持多仓 ERP 实时增量或全量同步 SKU 库存数量。

OpenID 发现端点 (OIDC Discovery)

获取 HopoAuth 身份认证服务标准 OIDC 终结点元数据配置。

发起 OAuth 2.0 / OIDC 统一授权流

引导用户浏览器重定向至 HopoAuth 统一登录收银台。

授权码兑换 Token (Code to Token)

通过授权码 Code 换取 Access Token 及 ID Token (RS256 JWT)。

获取用户基本信息与 AQL 校验位

携带 Bearer Access Token 获取当前登录用户的 Profile 及 AQL 特权密文。

统一撤销令牌与全局会话注销

注销全局 SSO 会话 Cookie 并吊销当前发放的授权令牌。

全局报错状态码字典速查

HTTP Code	错误码 (Error)	释义与解决方案
`400`	`invalid_request`	请求参数缺失或格式不正确
`401`	`invalid_signature`	HMAC 签名计算错误或已过期
`403`	`forbidden_ip`	发起调用的客户端 IP 不在白名单中
`404`	`order_not_found`	订单号或商户资源不存在
`500`	`server_error`	服务内部异常，请联系技术支持

在线 HMAC-SHA256 签名调试计算器

API Secret 密钥

待签名 JSON 字符串 (Payload)

生成的 Hash 签名结果

HPDC 官方多语言 SDK 工具包

官方 SDK 深度封装了 HopoAuth 统一认证 (OIDC SSO)、⚡ AQL 管理员特权校验、Shopo 聚合支付 以及 HMAC 异步通知自动验签中间件。

Node.js SDK

npm install @hopostudio/hpdc-sdk

Python SDK

pip install hopo-hpdc

Java SDK

com.hopostudio:hpdc-java-sdk:1.2.0

Go SDK

go get github.com/hopostudio/hpdc-go

Node.js 快速接入示例 (HopoAuth + ⚡ AQL 自动提权)

auth-example.js

const { HopoAuthClient } = require('@hopostudio/hpdc-sdk');

const hopo = new HopoAuthClient({
    clientId: 'vps_hopo',
    clientSecret: 'efa65993b7d6934dd4c123de',
    aqlApiKey: 'aql_live_5f273b692244',
    aqlSecret: 'sec_aql_c52b50c178a25561351acea0ce3dc30c'
});

// 1. 发起登录
app.get('/login', (req, res) => {
    const loginUrl = hopo.getAuthorizationUrl({
        redirectUri: 'https://vps.hopostudio.xyz/auth/callback'
    });
    res.redirect(loginUrl);
});

// 2. 回调处理与 AQL 自动识别
app.get('/auth/callback', async (req, res) => {
    const { user, isAdminByAql } = await hopo.handleCallback(req.query.code, 'https://vps.hopostudio.xyz/auth/callback');
    req.session.user = user;
    req.session.role = isAdminByAql ? 'admin' : 'user';
    res.redirect('/dashboard');
});

Shopo 聚合支付与 Webhook 自动验签示例

payment-example.js

const { ShopoClient } = require('@hopostudio/hpdc-sdk');

const shopo = new ShopoClient({
    apiKey: 'hop_live_981273918237',
    apiSecret: 'sec_live_abcdef123456'
});

// 1. 创建支付会话
const session = await shopo.createPaymentSession({
    merchantId: 'mer_shopo_8829',
    outTradeNo: 'ORDER_20260810_001',
    totalAmount: 29900,
    notifyUrl: 'https://myshop.com/api/pay/webhook'
});

// 2. Webhook 自动防重放与 HMAC-SHA256 验签中间件
app.post('/api/pay/webhook', shopo.webhookMiddleware(async (event) => {
    console.log('⚡ 支付成功回调:', event.out_trade_no);
    // 处理业务订单发货...
}));

HPDC 平台快速入门