快速开始

1. 获取凭证

平台为每个经销商租户分配一组 Open API 凭证：

字段	Header / 用途
AppKey	RT-AccessCode
AppSecret	HMAC 签名密钥（仅创建时展示一次，请妥善保存）

在管理后台 API 凭证 页面查看或重置。可选配置：

• 回调 URL（Webhook 接收地址）
• IP 白名单
• QPS 限流

2. 基础约定

环境	Base URL
本地（mall-cloud 网关）	http://127.0.0.1:9000
正式环境	https://admin.smartlink233.com/prod-api（以实际网关为准）
测试环境	https://admin.aiotclaw.net/dev-api（以实际网关为准）

完整请求路径 = Base URL + /open-api/v1/...，例如本地连通性检查：

POST http://127.0.0.1:9000/open-api/v1/health

注意：文档站域名仅为文档，不能作为 API Base URL。

其他约定：

• 协议：HTTPS（本地可为 HTTP）+ POST + Content-Type: application/json
• 路径前缀：/open-api/v1
• 身份：AppKey 绑定经销商租户，无需传 shopId
• 支付：下单固定走经销商 BALANCE 余额 扣款

3. 首次连通性测试

POST /open-api/v1/health
Content-Type: application/json
RT-AccessCode: {AppKey}
RT-RequestID: {UUID}
RT-Timestamp: {毫秒时间戳}
X-Signature: {签名}

{}

成功响应示例：

{
  "code": "000000",
  "message": "success",
  "data": {
    "status": "UP",
    "tenantId": "...",
    "clientName": "..."
  }
}

4. 推荐联调顺序

1. health — 验证签名与网络
2. account/balance — 确认余额
3. package/list — 拉取可售套餐
4. esim/order — 测试下单（注意 transactionId 幂等）
5. esim/query — 查单
6. esim/profile/list — 查看已分配 Profile
7. 配置 webhook/set — 接收 ORDER_PAID / DELIVERY_UPDATED

5. Apifox 导入

1. 导入 openapi.yaml
2. 环境变量：OPENAPI_APP_KEY、OPENAPI_APP_SECRET、OPENAPI_BASE_URL
3. 下载 Apifox 前置脚本 并粘贴到项目「前置操作」

详见 鉴权与签名。