junhong_cmp_fiber/docs/gateway-api-reference.md

Gateway API 参考文档

概述

本文档提供 Gateway 客户端所有 API 接口的完整参考，包括请求参数、响应格式和使用示例。

API 分类：

• 流量卡管理（7 个接口）
• 设备管理（7 个接口）

基础信息：

• 协议：HTTPS
• 请求方法：POST
• 内容类型：application/json
• 编码方式：UTF-8
• 加密方式：AES-128-ECB + Base64
• 签名方式：MD5

---

流量卡管理 API

1. 查询流量卡状态

查询流量卡的当前状态信息。

方法: QueryCardStatus

请求参数:

type CardStatusReq struct {
    CardNo string `json:"cardNo" validate:"required"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）

响应参数:

type CardStatusResp struct {
    ICCID      string `json:"iccid"`
    CardStatus string `json:"cardStatus"`
    Extend     string `json:"extend,omitempty"`
}

参数	类型	说明
ICCID	string	流量卡 ICCID
CardStatus	string	卡状态（准备、正常、停机）
Extend	string	扩展字段（广电国网特殊参数）

使用示例:

resp, err := client.QueryCardStatus(ctx, &gateway.CardStatusReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Printf("卡状态: %s\n", resp.CardStatus)

---

2. 查询流量使用情况

查询流量卡的流量使用详情。

方法: QueryFlow

请求参数:

type FlowQueryReq struct {
    CardNo string `json:"cardNo" validate:"required"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）

响应参数:

type FlowUsageResp struct {
    UsedFlow int64  `json:"usedFlow"`
    Unit     string `json:"unit"`
    Extend   string `json:"extend,omitempty"`
}

参数	类型	说明
UsedFlow	int64	已用流量
Unit	string	流量单位（MB）
Extend	string	扩展字段

使用示例:

resp, err := client.QueryFlow(ctx, &gateway.FlowQueryReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Printf("已用流量: %d %s\n", resp.UsedFlow, resp.Unit)

---

3. 查询实名认证状态

查询流量卡的实名认证状态。

方法: QueryRealnameStatus

请求参数:

type CardStatusReq struct {
    CardNo string `json:"cardNo" validate:"required"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）

响应参数:

type RealnameStatusResp struct {
    Status string `json:"status"`
    Extend string `json:"extend,omitempty"`
}

参数	类型	说明
Status	string	实名认证状态
Extend	string	扩展字段

使用示例:

resp, err := client.QueryRealnameStatus(ctx, &gateway.CardStatusReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Printf("实名状态: %s\n", resp.Status)

---

4. 流量卡停机

对流量卡执行停机操作。

方法: StopCard

请求参数:

type CardOperationReq struct {
    CardNo string `json:"cardNo" validate:"required"`
    Extend string `json:"extend,omitempty"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）
Extend	string	❌	扩展字段（广电国网特殊参数）

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.StopCard(ctx, &gateway.CardOperationReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Println("停机成功")

---

5. 流量卡复机

对流量卡执行复机操作。

方法: StartCard

请求参数:

type CardOperationReq struct {
    CardNo string `json:"cardNo" validate:"required"`
    Extend string `json:"extend,omitempty"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.StartCard(ctx, &gateway.CardOperationReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Println("复机成功")

---

6. 获取实名认证跳转链接

获取流量卡实名认证的跳转链接。

方法: GetRealnameLink

请求参数:

type CardStatusReq struct {
    CardNo string `json:"cardNo" validate:"required"`
}

参数	类型	必填	说明
CardNo	string	✅	流量卡号（ICCID）

响应参数:

type RealnameLinkResp struct {
    Link   string `json:"link"`
    Extend string `json:"extend,omitempty"`
}

参数	类型	说明
Link	string	实名认证跳转链接（HTTPS URL）
Extend	string	扩展字段

使用示例:

resp, err := client.GetRealnameLink(ctx, &gateway.CardStatusReq{
    CardNo: "898608070422D0010269",
})
if err != nil {
    return err
}

fmt.Printf("实名链接: %s\n", resp.Link)

---

7. 批量查询（预留）

批量查询流量卡信息（暂未实现）。

方法: BatchQuery

请求参数:

type BatchQueryReq struct {
    CardNos []string `json:"cardNos" validate:"required,min=1,max=100"`
}

参数	类型	必填	说明
CardNos	[]string	✅	流量卡号列表（最多100个）

响应参数:

type BatchQueryResp struct {
    Results []CardStatusResp `json:"results"`
}

状态: ⚠️ 暂未实现，调用将返回错误

---

设备管理 API

1. 获取设备信息

通过卡号或设备 ID 查询设备的在线状态、信号强度、WiFi 信息等。

方法: GetDeviceInfo

请求参数:

type DeviceInfoReq struct {
    CardNo   string `json:"cardNo,omitempty"`
    DeviceID string `json:"deviceId,omitempty"`
}

参数	类型	必填	说明
CardNo	string	二选一	流量卡号（ICCID）
DeviceID	string	二选一	设备 ID/IMEI

响应参数:

type DeviceInfoResp struct {
    IMEI          string `json:"imei"`
    OnlineStatus  int    `json:"onlineStatus"`
    SignalLevel   int    `json:"signalLevel"`
    WiFiSSID      string `json:"wifiSsid,omitempty"`
    WiFiEnabled   int    `json:"wifiEnabled"`
    UploadSpeed   int    `json:"uploadSpeed"`
    DownloadSpeed int    `json:"downloadSpeed"`
    Extend        string `json:"extend,omitempty"`
}

参数	类型	说明
IMEI	string	设备 IMEI
OnlineStatus	int	在线状态（0:离线, 1:在线）
SignalLevel	int	信号强度（0-31）
WiFiSSID	string	WiFi 名称
WiFiEnabled	int	WiFi 启用状态（0:禁用, 1:启用）
UploadSpeed	int	上行速率（KB/s）
DownloadSpeed	int	下行速率（KB/s）
Extend	string	扩展字段

使用示例:

resp, err := client.GetDeviceInfo(ctx, &gateway.DeviceInfoReq{
    DeviceID: "123456789012345",
})
if err != nil {
    return err
}

fmt.Printf("设备状态: %s, 信号: %d\n", 
    map[int]string{0:"离线", 1:"在线"}[resp.OnlineStatus],
    resp.SignalLevel,
)

---

2. 获取设备卡槽信息

查询设备的所有卡槽及其中的卡信息。

方法: GetSlotInfo

请求参数:

type DeviceInfoReq struct {
    CardNo   string `json:"cardNo,omitempty"`
    DeviceID string `json:"deviceId,omitempty"`
}

参数	类型	必填	说明
CardNo	string	二选一	流量卡号（ICCID）
DeviceID	string	二选一	设备 ID/IMEI

响应参数:

type SlotInfoResp struct {
    IMEI   string     `json:"imei"`
    Slots  []SlotInfo `json:"slots"`
    Extend string     `json:"extend,omitempty"`
}

type SlotInfo struct {
    SlotNo     int    `json:"slotNo"`
    ICCID      string `json:"iccid"`
    CardStatus string `json:"cardStatus"`
    IsActive   int    `json:"isActive"`
    Extend     string `json:"extend,omitempty"`
}

参数	类型	说明
IMEI	string	设备 IMEI
Slots	[]SlotInfo	卡槽信息列表
SlotNo	int	卡槽编号
ICCID	string	卡槽中的 ICCID
CardStatus	string	卡状态（准备、正常、停机）
IsActive	int	是否为当前使用的卡槽（0:否, 1:是）

使用示例:

resp, err := client.GetSlotInfo(ctx, &gateway.DeviceInfoReq{
    DeviceID: "123456789012345",
})
if err != nil {
    return err
}

for _, slot := range resp.Slots {
    fmt.Printf("卡槽%d: %s (%s)%s\n",
        slot.SlotNo,
        slot.ICCID,
        slot.CardStatus,
        map[int]string{0:"", 1:" [当前使用]"}[slot.IsActive],
    )
}

---

3. 设置设备限速

设置设备的上行和下行速率限制。

方法: SetSpeedLimit

请求参数:

type SpeedLimitReq struct {
    DeviceID      string `json:"deviceId" validate:"required"`
    UploadSpeed   int    `json:"uploadSpeed" validate:"required,min=1"`
    DownloadSpeed int    `json:"downloadSpeed" validate:"required,min=1"`
    Extend        string `json:"extend,omitempty"`
}

参数	类型	必填	说明
DeviceID	string	✅	设备 ID/IMEI
UploadSpeed	int	✅	上行速率（KB/s），最小1
DownloadSpeed	int	✅	下行速率（KB/s），最小1
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.SetSpeedLimit(ctx, &gateway.SpeedLimitReq{
    DeviceID:      "123456789012345",
    UploadSpeed:   100,
    DownloadSpeed: 500,
})
if err != nil {
    return err
}

fmt.Println("限速设置成功")

---

4. 设置设备 WiFi

设置设备的 WiFi 名称、密码和启用状态。

方法: SetWiFi

请求参数:

type WiFiReq struct {
    DeviceID string `json:"deviceId" validate:"required"`
    SSID     string `json:"ssid" validate:"required,min=1,max=32"`
    Password string `json:"password" validate:"required,min=8,max=63"`
    Enabled  int    `json:"enabled" validate:"required,oneof=0 1"`
    Extend   string `json:"extend,omitempty"`
}

参数	类型	必填	说明
DeviceID	string	✅	设备 ID/IMEI
SSID	string	✅	WiFi 名称（1-32字符）
Password	string	✅	WiFi 密码（8-63字符）
Enabled	int	✅	启用状态（0:禁用, 1:启用）
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.SetWiFi(ctx, &gateway.WiFiReq{
    DeviceID: "123456789012345",
    SSID:     "MyWiFi",
    Password: "password123",
    Enabled:  1,
})
if err != nil {
    return err
}

fmt.Println("WiFi设置成功")

---

5. 设备切换卡

切换设备当前使用的卡到指定的目标卡。

方法: SwitchCard

请求参数:

type SwitchCardReq struct {
    DeviceID    string `json:"deviceId" validate:"required"`
    TargetICCID string `json:"targetIccid" validate:"required"`
    Extend      string `json:"extend,omitempty"`
}

参数	类型	必填	说明
DeviceID	string	✅	设备 ID/IMEI
TargetICCID	string	✅	目标卡 ICCID
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.SwitchCard(ctx, &gateway.SwitchCardReq{
    DeviceID:    "123456789012345",
    TargetICCID: "898608070422D0010270",
})
if err != nil {
    return err
}

fmt.Println("切换卡成功")

---

6. 设备恢复出厂设置

将设备恢复到出厂设置状态。

方法: ResetDevice

请求参数:

type DeviceOperationReq struct {
    DeviceID string `json:"deviceId" validate:"required"`
    Extend   string `json:"extend,omitempty"`
}

参数	类型	必填	说明
DeviceID	string	✅	设备 ID/IMEI
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.ResetDevice(ctx, &gateway.DeviceOperationReq{
    DeviceID: "123456789012345",
})
if err != nil {
    return err
}

fmt.Println("恢复出厂设置成功")

---

7. 设备重启

远程重启设备。

方法: RebootDevice

请求参数:

type DeviceOperationReq struct {
    DeviceID string `json:"deviceId" validate:"required"`
    Extend   string `json:"extend,omitempty"`
}

参数	类型	必填	说明
DeviceID	string	✅	设备 ID/IMEI
Extend	string	❌	扩展字段

响应参数: 无（成功返回 nil，失败返回 error）

使用示例:

err := client.RebootDevice(ctx, &gateway.DeviceOperationReq{
    DeviceID: "123456789012345",
})
if err != nil {
    return err
}

fmt.Println("重启设备成功")

---

通用响应结构

所有 API 的底层响应都遵循统一的 Gateway 响应格式：

type GatewayResponse struct {
    Code    int             `json:"code"`
    Msg     string          `json:"msg"`
    Data    json.RawMessage `json:"data"`
    TraceID string          `json:"trace_id"`
}

参数	类型	说明
Code	int	业务状态码（200 = 成功）
Msg	string	业务提示信息
Data	json.RawMessage	业务数据（原始 JSON）
TraceID	string	链路追踪 ID

成功响应示例:

{
  "code": 200,
  "msg": "成功",
  "data": {
    "iccid": "898608070422D0010269",
    "cardStatus": "正常"
  },
  "trace_id": "abc123xyz"
}

失败响应示例:

{
  "code": 404,
  "msg": "卡号不存在",
  "data": null,
  "trace_id": "abc123xyz"
}

---

错误码说明

Gateway 业务错误码

错误码	说明	解决方案
200	成功	-
400	请求参数错误	检查请求参数格式和内容
401	认证失败	检查 AppID 和 AppSecret
404	资源不存在	检查卡号或设备 ID 是否正确
500	服务器内部错误	联系 Gateway 服务提供方

客户端错误码

客户端封装的统一错误码（pkg/errors/codes.go）：

错误码	常量	说明
1110	CodeGatewayError	Gateway 连接失败
1111	CodeGatewayTimeout	Gateway 请求超时
1112	CodeGatewayBusinessError	Gateway 业务错误
1113	CodeGatewayInvalidResp	Gateway 响应解析失败
1114	CodeGatewaySignError	Gateway 签名验证失败

---

请求流程

完整请求流程

1. 构造业务请求参数
   ↓
2. 序列化为 JSON
   ↓
3. AES-128-ECB 加密（Base64 编码）
   ↓
4. 生成 MD5 签名（参数排序 + appSecret）
   ↓
5. 构造最终请求体
   {
     "appId": "xxx",
     "data": "encrypted_base64_string",
     "sign": "md5_signature",
     "timestamp": 1706620800000
   }
   ↓
6. POST 请求到 Gateway
   ↓
7. 解析响应 JSON
   ↓
8. 检查业务状态码
   ↓
9. 解密并解析业务数据
   ↓
10. 返回结果或错误

签名算法

1. 将请求参数按 key 字母序排序
2. 拼接为 key1=value1&key2=value2 格式
3. 末尾追加 &appSecret=xxx
4. 计算 MD5 哈希
5. 转为大写字符串

示例:

参数: {cardNo: "123", appId: "abc"}
排序: appId=abc&cardNo=123
追加: appId=abc&cardNo=123&appSecret=secret
MD5:  D41D8CD98F00B204E9800998ECF8427E

---

相关文档

• Gateway 客户端使用指南 - 详细的使用指南和最佳实践
• 错误处理指南 - 统一错误处理规范