Tổng Kho eSIM
自主集成

自主集成

无需安装官方包，通过签名、可运行示例和测试集合，即可在编写代码前了解 API 响应。

会员 OpenAPI

直接使用会员账户集成，无需创建组织或越南法人资料。

管理员按会员授予 OpenAPI 权限。在主侧栏打开 API 密钥，选择正式或测试模式后创建密钥；私密密钥仅显示一次。两种模式共用密钥数量限制。关闭权限将阻止两种模式，但仍可撤销密钥。

正式模式使用会员真实 VND 钱包，无信用额度。测试使用独立虚拟钱包和模拟 eSIM，可在测试页添加余额、创建或重置示例。测试订单不会出现在真实购买历史中。

会员专属套餐价格为最终价格，不再叠加等级折扣。没有专属套餐价格时，使用当前标价和等级折扣。下单时由服务器确定价格。

发票遵循会员流程，默认为消费者销售。创建订单时，可通过 invoice_buyer 提供符合当前校验规则的个人资料。获得 OpenAPI 权限不要求越南法人资料。

身份验证与防止重复交易

正式：https://api.tongkhoesim.com 搭配 tke_member_live_。测试：https://api-testing.tongkhoesim.com 搭配 tke_member_test_。两者均使用 HMAC-SHA256 和 X-TKE-Key、X-TKE-Timestamp、X-TKE-Nonce、X-TKE-Signature。请准确签名方法、路径/查询和原始正文哈希，勿将私密密钥放入浏览器代码。

创建订单、更换套餐、取消及申请退款的 POST 必须带有 Idempotency-Key。重试同一意图时保持相同的键和正文。去重按 API 密钥隔离，因此不要更换 API 密钥来重试待处理交易。 会员测试示例创建和重置也需要 Idempotency-Key；reset 必须包含 {reason} 正文。

在 include 中指定 lpa 以获取安装码；实际返回安装码时，普通取消窗口才会关闭。qr 仅在同时指定 lpa 时补充 QR 图片，列表端点会忽略 qr。仅在准备交付时索取安装码；尚不想披露时省略 include。退款申请仍须满足业务条件，并非获取安装码后可随意取消的途径。

会员 API 端点

API 路径: GET /v1/catalog/packages
所需权限: catalog:read
API 路径: GET /v1/catalog/packages/{code}
所需权限: catalog:read
API 路径: GET /v1/orders
所需权限: orders:read
API 路径: POST /v1/orders
所需权限: orders:write
API 路径: GET /v1/orders/{id}
所需权限: orders:read
API 路径: POST /v1/orders/{id}/resend
所需权限: orders:write
API 路径: GET /v1/esims
所需权限: esims:read
API 路径: GET /v1/esims/{id}
所需权限: esims:read
API 路径: GET /v1/esims/{id}/usage
所需权限: esims:read
API 路径: GET /v1/esims/{id}/plan-options
所需权限: esims:read
API 路径: POST /v1/esims/{id}/change-plan
所需权限: esims:write
API 路径: POST /v1/esims/{id}/cancel
所需权限: esims:write
API 路径: GET /v1/esims/{id}/refund-requests
所需权限: esims:read
API 路径: POST /v1/esims/{id}/refund-requests
所需权限: esims:write
API 路径: GET /v1/wallet/balance
所需权限: wallet:read

测试模式

GET /v1/testmode/status
esims:read
POST /v1/testmode/seed
orders:write
POST /v1/testmode/reset
orders:write
POST /v1/testmode/esims/{id}/simulate
esims:write

控制台仅接受 api-testing 上的合作伙伴 tke_test_ 和会员 tke_member_test_ 测试密钥。所有正式密钥均被阻止。私密密钥仅保留在页面内存中，不写入存储或日志。

请求签名

HMAC 页面提供完整公式、bash/Node/Python/PHP/Go 示例及后端测试向量。

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"

可运行示例

examples/sign.mjs 和 examples/sign.py 仅需标准运行时，无额外依赖。读取 /hmac-test-vectors.json，逐个计算签名并输出 PASS/FAIL。

bash
node examples/sign.mjs      # plain Node (node:crypto), nothing to install
python examples/sign.py     # plain Python (hmac/hashlib), nothing to install

开箱即用的请求集合

Postman 和 .http 在构建时直接由 openapi.json 生成。每个接口均包含请求和 4 个签名头，填入密钥并计算签名即可。

下载 Postman 集合 下载 tongkhoesim.http
使用 .http 集合
  1. 在 VS Code REST Client 扩展或 JetBrains HTTP Client 中打开 tongkhoesim.http。
  2. 填入 tke_test_ 对应的 @key_id 和 @secret，@base_url 已指向 api-testing.tongkhoesim.com。
  3. 使用 HMAC 示例或 examples/sign.* 计算 timestamp/nonce/signature，再填入对应变量。
  4. 直接在编辑器发送请求，无需 Postman 或额外代码。

仍需要 SDK？

使用 openapi-generator 从 openapi.json 生成客户端，保持与规范一致。

bash
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.tongkhoesim.com/openapi.json \
  -g typescript-fetch \
  -o ./tke-sdk