Tổng Kho eSIM
身份验证

HMAC 请求签名

包括 GET 在内的全部 /v1/* 接口都必须进行 HMAC-SHA256 签名，无例外。服务端采用恒定时间比较，防止时序攻击。

需要可直接运行的文件？请查看 自主集成页面 ，下载使用相同签名公式的示例、Postman 和 .http 文件。

查看集成指南

必需请求头

前 4 个请求头每次请求都必须提供，列表来自 openapi.json 的安全定义。

请求头类型含义
X-TKE-Key每次请求公开 key_id（tke_live_… / tke_test_… / tke_member_live_… / tke_member_test_…）
X-TKE-Timestamp每次请求Unix 毫秒时间戳（整数字符串）
X-TKE-Nonce每次请求每次请求唯一的 UUID v4 或 v7
X-TKE-Signature每次请求小写十六进制 HMAC-SHA256
Idempotency-Key5 个接口

客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 api_key_id（§11），不同密钥属于不同命令。

以下接口必须提供 Idempotency-Key
POST/v1/ordersPOST/v1/orders/bulkPOST/v1/esims/{id}/cancelPOST/v1/esims/{id}/change-planPOST/v1/esims/{id}/refund-requests

签名规范公式

HMAC-SHA256 认证（§4）。发送四个请求头：X-TKE-Key（公开 key_id）、X-TKE-Timestamp（epoch 毫秒）、X-TKE-Nonce（每个请求一个 UUID）、X-TKE-Signature（小写十六进制）。signing_string = method path timestamp nonce body_hash；body_hash = SHA256(raw_body) 的十六进制值。使用恒定时间比较。path 包含查询字符串。

各部分以换行符连接 \n （LF），签名对象为 SHA256(raw_body) 而非直接签名请求体；服务端对收到的原始字节重新计算哈希进行校验。

text
signing_string = method + "\n"
               + path + "\n"        # 包含查询串，不含协议和主机
               + timestamp + "\n"   # = header X-TKE-Timestamp (epoch ms)
               + nonce + "\n"       # = header X-TKE-Nonce
               + body_hash          # SHA256(raw_body) hex lowercase

signature = HMAC_SHA256(secret, signing_string)   → hex lowercase
无请求体（GET、DELETE）或请求体为空时， raw_body = "" → body_hash = SHA256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

HMAC 签名代码示例

替换您的 secret 和 key_id，发送与哈希完全一致的字节，签名后不要重新序列化。

bash
#!/usr/bin/env bash
# Yeu cau: openssl. Ky POST /v1/orders.
KEY_ID="tke_test_ab12cd34..."
SECRET="tke_secret_test_0123456789abcdef"
METHOD="POST"
PATH_Q="/v1/orders"
BODY='{"items":[{"package_code":"THAY-BANG-MA-GOI-CUA-BAN","quantity":2}]}'
TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"

BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'
'"$PATH_Q"$'
'"$TS"$'
'"$NONCE"$'
'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS "https://api.tongkhoesim.com$PATH_Q"   -H "X-TKE-Key: $KEY_ID"   -H "X-TKE-Timestamp: $TS"   -H "X-TKE-Nonce: $NONCE"   -H "X-TKE-Signature: $SIG"   -H "Idempotency-Key: $(uuidgen)"   -H "Content-Type: application/json"   --data-raw "$BODY"

后端测试向量

使用后端生成的权威测试向量验证签名实现。

用以下相同 method、path、timestamp、nonce、body 签名并比对，不一致时检查 signing_string。

示例密钥： tke_secret_test_0123456789abcdef
POST /v1/orders
methodPOST
path/v1/orders
timestamp1720680000000
nonce11111111-1111-4111-8111-111111111111
raw_body{"items":[{"package_code":"VN_5GB_30D","quantity":2}]}
body_hashc197853f7fe46a9f2de1478e565c48ef9369d0152af5117434be8ccfa9391b31
signing_string
POST
/v1/orders
1720680000000
11111111-1111-4111-8111-111111111111
c197853f7fe46a9f2de1478e565c48ef9369d0152af5117434be8ccfa9391b31
signature（预期结果）
97147afdebb5d15cf8441278ef524ce15c715ca95962ddb1cb2604a1672fc5d5
GET /v1/wallet/balance
methodGET
path/v1/wallet/balance
timestamp1720680000000
nonce22222222-2222-4222-8222-222222222222
raw_body（空）
body_hashe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
signing_string
GET
/v1/wallet/balance
1720680000000
22222222-2222-4222-8222-222222222222
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
signature（预期结果）
ab16941884d407924c7b15dea008d6f1d8c0c1be96dca3745344218a99257dbe