feat: v3.2.0 — 新增 Account + VCard 命名空间(4 语言)

- account:GET /balance、/deposit-address(X-API-Key + X-Secret-Key)
- vcard:读(info/bins/cards/transactions/orders/order/remark)双密钥;
  开卡/充值/注销/卡详情/验证码 走 header 式 HMAC 签名
  (X-Signature = HMAC-SHA256(apiSecret, ts+nonce+method+path+rawQuery+body),
   POST body-raw 保证签名串与字节一致)
- 新增配置 apiKey/apiSecret(MPK 商户密钥,两模块共用)
- 新增 verifyWebhook(params, secret) 校验平台主动推送的虚拟卡事件签名
- go/node/python/php 全部 bump 3.1.0 → 3.2.0;README/CHANGELOG 同步

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: DoBest888

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 本仓库遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 和 [Semantic Versioning](https://semver.org/lang/zh-CN/).
 
+## [3.2.0] - 2026-06-28
+
+### 新增
+
+- 4 个语言 SDK 全部新增 **`.account` namespace** — 账户(2 endpoint):
+  - `GET /api/v1/account/balance` 账户 USD 余额(顺带 TRON 固定充值地址)
+  - `GET /api/v1/account/deposit-address` 获取/分配 TRON 固定充值地址
+- 4 个语言 SDK 全部新增 **`.vcard` namespace** — 虚拟信用卡(12 endpoint):
+  - 读(X-API-Key + X-Secret-Key):`getInfo` / `listBins` / `listCards` / `getCardTransactions` / `listOrders` / `getOrder` / `updateCardRemark`
+  - 资金/敏感(**HMAC 头签名**):`getCardDetails` / `getCardCode`(完整卡号·CVV·有效期 / 3DS 验证码)、`openCard` / `rechargeCard` / `cancelCard`
+- 新增配置项 `apiKey` / `apiSecret`(MPK 商户密钥,Account 与 VCard 共用)
+- **新增 header 式 HMAC 签名**:`X-Signature = HMAC-SHA256(apiSecret, timestamp + nonce + method + path + rawQuery + body)`,头 `X-Key-ID / X-Timestamp / X-Nonce / X-Signature`;POST 采用 body-raw 机制(签名串与实际字节一致)
+- 新增各语言 **`verifyWebhook(params, secret)`** — 校验平台主动推送的虚拟卡 webhook 事件签名(开卡/充值/注销/新交易/新验证码),复刻后端 HMAC 验签 + 提示 sign_ts/nonce 防重放
+
 ## [3.1.0] - 2026-05-23
 
 ### 新增

README.md

@@ -5,7 +5,7 @@
 **面向开发者的综合数字基础服务平台 · 官方多语言 SDK**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![v3.0.0](https://img.shields.io/badge/version-3.0.0-blue.svg)](./CHANGELOG.md)
+[![v3.2.0](https://img.shields.io/badge/version-3.2.0-blue.svg)](./CHANGELOG.md)
 [![Website](https://img.shields.io/badge/website-nexcores.net-2563eb.svg)](https://nexcores.net)
 [![Docs](https://img.shields.io/badge/docs-online-22c55e.svg)](https://nexcores.net/docs)
 
@@ -98,6 +98,8 @@ NexCore 平台共 **9 个业务模块**,本 SDK 当前覆盖**核心 4 个**(其
 | 汇率 Exchange | `/api/v1/rate` / `/api/v1/rates*` / `/api/v1/convert` | X-App-Key + X-App-Secret | **5** |
 | 能量租赁 Energy | `/api/v1/energy/*` | X-API-Key + X-Secret-Key | **8** |
 | SMTP 聚合 Smtp | `/api/v1/smtp/*` | Authorization: Bearer smk_xxx | **5** |
+| 账户 Account | `/api/v1/account/*` | X-API-Key + X-Secret-Key | **2** |
+| 虚拟信用卡 VCard | `/api/v1/vcard/*` | 读=X-API-Key+X-Secret-Key;开卡/充值/注销/卡详情/验证码=HMAC 头签名 | **12** |
 
 所有 endpoint 完全对照 [`/docs`](https://nexcores.net/docs) 在线文档,字段命名与后端 100% 一致.
 
@@ -299,7 +301,7 @@ raw, err := c.Payment.CreateOrder(map[string]any{
 
 ## 版本
 
-当前 SDK 版本:**v3.0.0**(跟主仓库 v3.x 主线一致)
+当前 SDK 版本:**v3.2.0**(跟主仓库 v3.x 主线一致)
 
 ## 反馈
 

go/account.go

@@ -0,0 +1,51 @@
+package nexcore
+
+import (
+	"encoding/json"
+)
+
+// AccountNamespace implements the v1 账户 read endpoints.
+//
+// 对应 NexCore 账户模块的公开只读接口:
+//
+//	GET /api/v1/account/balance          GetBalance        查询账户余额
+//	GET /api/v1/account/deposit-address  GetDepositAddress 查询/获取充值地址
+//
+// 鉴权:X-API-Key + X-Secret-Key 双 header(用 cfg.APIKey / cfg.APISecret).
+// account 与 vcard 命名空间共用同一对 MPK 商户密钥.
+type AccountNamespace struct {
+	c *Client
+}
+
+// headers 构造 X-API-Key + X-Secret-Key(复用与 energy 一致的双密钥读模式).
+func (n *AccountNamespace) headers() (map[string]string, error) {
+	if n.c.cfg.APIKey == "" || n.c.cfg.APISecret == "" {
+		return nil, &Error{Message: "APIKey / APISecret not configured", Code: -1}
+	}
+	return map[string]string{
+		"X-API-Key":    n.c.cfg.APIKey,
+		"X-Secret-Key": n.c.cfg.APISecret,
+	}, nil
+}
+
+// GetBalance returns the account balance.
+//
+// GET /api/v1/account/balance
+func (n *AccountNamespace) GetBalance() (json.RawMessage, error) {
+	h, err := n.headers()
+	if err != nil {
+		return nil, err
+	}
+	return n.c.transport.do("GET", "/api/v1/account/balance", &requestOpts{Headers: h})
+}
+
+// GetDepositAddress returns the account deposit address(es).
+//
+// GET /api/v1/account/deposit-address
+func (n *AccountNamespace) GetDepositAddress() (json.RawMessage, error) {
+	h, err := n.headers()
+	if err != nil {
+		return nil, err
+	}
+	return n.c.transport.do("GET", "/api/v1/account/deposit-address", &requestOpts{Headers: h})
+}

go/client.go

@@ -32,6 +32,13 @@ type Config struct {
 	// WithdrawPlatformPublicKeyPEM 平台 RSA 公钥 PEM(用于回调验签,可选).
 	WithdrawPlatformPublicKeyPEM string
 
+	// APIKey 商户 API Key(MPK 商户密钥的 key 部分);account 与 vcard 命名空间共用.
+	// 双密钥读场景作为 X-API-Key,HMAC 签名写场景作为 X-Key-ID.
+	APIKey string
+	// APISecret 商户 API Secret(MPK 商户密钥的 secret 部分);account 与 vcard 命名空间共用.
+	// 双密钥读场景作为 X-Secret-Key,HMAC 签名写场景作为 HMAC-SHA256 的密钥.
+	APISecret string
+
 	// Timeout HTTP 超时,默认 30s.
 	Timeout time.Duration
 
@@ -47,6 +54,8 @@ type Config struct {
 //	c.Exchange  - 汇率
 //	c.Energy    - TRON 能量租赁
 //	c.SMTP      - SMTP 聚合
+//	c.Account   - 账户(余额 / 充值地址)
+//	c.VCard     - 虚拟信用卡
 //
 // 所有方法返回 json.RawMessage,业务方自行 json.Unmarshal 到具体 struct.
 type Client struct {
@@ -63,6 +72,10 @@ type Client struct {
 	SMTP *SMTPNamespace
 	// Withdraw 提币命名空间(多链收款业务的资金出库端,RSA-2048 签名)
 	Withdraw *WithdrawNamespace
+	// Account 账户命名空间(余额 / 充值地址,双密钥读)
+	Account *AccountNamespace
+	// VCard 虚拟信用卡命名空间(读用双密钥,开卡/充值/注销/敏感信息用 HMAC 签名)
+	VCard *VCardNamespace
 }
 
 // NewClient creates a new NexCore client.
@@ -94,5 +107,7 @@ func NewClient(cfg Config) *Client {
 	c.Energy = &EnergyNamespace{c: c}
 	c.SMTP = &SMTPNamespace{c: c}
 	c.Withdraw = &WithdrawNamespace{c: c}
+	c.Account = &AccountNamespace{c: c}
+	c.VCard = &VCardNamespace{c: c}
 	return c
 }

go/doc.go

@@ -7,6 +7,8 @@
 //   - client.Exchange  — 汇率(X-App-Key + X-App-Secret header)
 //   - client.Energy    — TRON 能量租赁(X-API-Key + X-Secret-Key)
 //   - client.SMTP      — SMTP 聚合(Bearer Token)
+//   - client.Account   — 账户余额 / 充值地址(X-API-Key + X-Secret-Key)
+//   - client.VCard     — 虚拟信用卡(读用双密钥;开卡/充值/注销/敏感信息用 HMAC 签名)
 //
 // 使用:
 //
@@ -39,4 +41,4 @@
 package nexcore
 
 // Version is the SDK version, kept in sync with the public repository tags.
-const Version = "3.1.0"
+const Version = "3.2.0"