快速开始

从申请到调用，四步走通。本页示例可原样粘贴运行。

当前可原样跑通的示例端点：/api/gstack/v1/whoami

其余端点（会话调试类）与资源类端点或在接口目录「已开放」区，或尚未开放。本页示例仅保证 whoami 一条可原样跑通。

申请接入，拿到 ak / sk

在「申请接入」页提交表单，获得申请单号与一次性 claimSecret；审核签发后，在「密钥管理」页领取 ak 与 sk。 sk 只在领取时显示一次，请立即妥善保存。

去申请接入

理解签名规范

每个请求需带 4 个签名头，签名值 = hex(HMAC-SHA256(sk, 待签串))。待签串为 5 段、以换行分隔、无尾随换行：

待签串（stringToSign）

METHOD
PATH
TIMESTAMP
NONCE
hex(SHA256(body))

完整规则（时间窗、nonce 一次性、失败排查）见鉴权说明。

调用示例（可原样粘贴）

把下面的 AK / SK 换成你的凭据即可运行。示例调用 GET /api/gstack/v1/whoami。

python3（仅标准库）

import hashlib, hmac, os, time, urllib.request

AK   = "ak_live_在此填入你的 AK"
SK   = "sk_在此填入你的 SK"
BASE = "https://api.nanniwan.com"
PATH = "/api/gstack/v1/whoami"          # 完整路径，不含 query

body = b""                              # GET，无 body
ts    = str(int(time.time()))           # Unix 秒
nonce = os.urandom(16).hex()            # 长度 >= 16
body_sha = hashlib.sha256(body).hexdigest()

string_to_sign = "GET\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + body_sha   # 5 段，无尾随换行
signature = hmac.new(SK.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

req = urllib.request.Request(BASE + PATH, method="GET")
req.add_header("X-Gstack-Ak", AK)
req.add_header("X-Gstack-Timestamp", ts)
req.add_header("X-Gstack-Nonce", nonce)
req.add_header("X-Gstack-Signature", signature)
req.add_header("X-Gstack-Sign-Version", "v1")

with urllib.request.urlopen(req) as resp:
    print(resp.status, resp.read().decode())

预期结果

HTTP 200，返回体含由 Key 推导的 data.principal（如 {"type":"merchant","id":123}）。

排查常见问题

· 401 SIGN_MISSING：四个签名头缺失，或 nonce 长度不足。
· 401 SIGN_EXPIRED：本机时钟偏差超时，校准时间后重试。
· 401 SIGN_MISMATCH：待签串不一致（常见：path 带了 query，或 body 未参与签名）。
· 401 NONCE_REPLAYED：nonce 重复，请每次请求生成新的随机串。