# third-iot-client

**Repository Path**: xsz_88/third-iot

## Basic Information

- **Project Name**: third-iot-client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鼎芯物联网SDK使用文档

## 1. 项目简介

鼎芯物联网SDK是一个专门用于集成鼎芯（EIOTCLUB）物联网平台API的Java SDK，提供了完整的卡片管理、套餐管理、eSIM管理、短信发送等功能。

**核心特性：**

- 完整API覆盖：支持卡片、套餐、代理商、短信、eSIM、CloudESIM、CDR等全部鼎芯API
- 多种调用方式：动态代理、泛型代理、链式调用三种API调用方式
- Spring Boot集成：支持自动配置，开箱即用
- 类型安全：支持泛型，提供类型安全的API调用
- 签名认证：内置签名工具，自动处理API签名

## 2. 项目结构

```
third-iot-client/
├── seetong-framework/
│   ├── seetong-common-iot/          # 通用组件（DTO、异常、签名工具等）
│   └── spring-boot-dingxin-starter/ # 鼎芯Spring Boot Starter
└── seetong-service/
    └── seetong-service-iot/          # 示例应用
```

## 3. 快速开始

### 3.1 安装

#### 3.1.1 Maven仓库配置

在项目的`pom.xml`中添加以下仓库配置：

```xml
<repositories>
    <repository>
        <id>topsee-releases</id>
        <name>Topsee Releases</name>
        <url>http://nexus.seetong.com/repository/maven-releases/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>topsee-snapshots</id>
        <name>Topsee Snapshots</name>
        <url>http://nexus.seetong.com/repository/maven-snapshots/</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>
```

#### 3.1.2 添加依赖

```xml
<dependency>
    <groupId>com.seetong.iot</groupId>
    <artifactId>spring-boot-dingxin-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

### 3.2 配置

在`application.yml`中添加配置：

```yaml
dingxin:
  app-key: your_app_key
  secret: your_secret
  api-base-url: https://oapi.eiotclub.com/api/v3/
  auth-url: https://sim.eiotclub.com/eshop/api/user/auth/login/whitelist
  h5-base-url: https://sim.eiotclub.com
  token-expire: 7200
  timestamp-tolerance: 300
```

**配置说明：**

| 配置项                 | 说明           | 默认值                               |
|---------------------|--------------|-----------------------------------|
| app-key             | 应用身份标识       | 必填                                |
| secret              | 应用密钥         | 必填                                |
| api-base-url        | API基础URL     | https://oapi.eiotclub.com/api/v3/ |
| auth-url            | 认证URL        | -                                 |
| h5-base-url         | H5基础URL      | -                                 |
| token-expire        | Token过期时间（秒） | 7200                              |
| timestamp-tolerance | 时间戳容错时间（秒）   | 300                               |

### 3.3 使用示例

SDK提供三种API调用方式：

#### 方式一：动态代理（推荐）

```java
import com.seetong.dingxin.client.EiotClient;
import com.seetong.common.iot.dto.IotResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Map;

@Service
public class CardService {

    @Autowired
    private EiotClient eiotClient;

    public void queryCardInfo(String iccid) {
        IotResponse<Map<String, Object>> response = eiotClient.getApi().cardDetail(Map.class, iccid);
        if (response.isSuccess()) {
            System.out.println("卡片信息: " + response.getData());
        }
    }

    public void queryCardList(Integer pageNum, Integer pageSize) {
        IotResponse<Map<String, Object>> response = eiotClient.getApi().cardList(Map.class, pageNum, pageSize);
        System.out.println("卡片列表: " + response.getData());
    }
}
```

#### 方式二：链式调用

```java
import com.seetong.dingxin.client.EiotClient;
import com.seetong.common.iot.dto.IotResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Map;

@Service
public class ChainService {

    @Autowired
    private EiotClient eiotClient;

    public void chainExample(String iccid) {
        IotResponse<Map<String, Object>> response = eiotClient.getChain()
            .path("card/getCardsInfo")
            .param("iccid", iccid)
            .post();
        System.out.println("响应: " + response.getData());
    }
}
```

#### 方式三：直接POST请求

```java
import com.seetong.dingxin.client.EiotClient;
import com.seetong.common.iot.dto.IotResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

@Service
public class DirectService {

    @Autowired
    private EiotClient eiotClient;

    public void directPostExample(String iccid) {
        Map<String, Object> params = new HashMap<>();
        params.put("iccid", iccid);
        IotResponse<Map<String, Object>> response = eiotClient.post("card/getCardsInfo", params);
        System.out.println("响应: " + response.getData());
    }
}
```

## 4. API接口列表

### 4.1 卡片API

| 方法名                     | 说明            |
|-------------------------|---------------|
| cardList                | 查询账户下所有卡片     |
| cardDetail              | 单卡信息查询        |
| packageOrderRecord      | 查询卡片套餐订购记录    |
| listOrderPackageByIccid | 查询卡片可订购套餐信息   |
| queryAccountWarningCard | 查询账户下国际卡片预警信息 |
| queryCardNumber         | 卡总数统计         |
| switchOptions           | 查询卡片可切换的运营商列表 |
| switchOperator          | 切换卡片的运营商      |
| imeiUnlock              | 卡片IMEI池解锁     |
| plockAddImei            | IMEI卡池添加IMEI  |
| bindDevice              | 机卡绑定          |
| unbindDevice            | 机卡解绑          |
| transferPkg             | 卡片转移套餐        |
| refreshUsage            | 刷新套餐用量        |
| cancelSession           | 取消当前会话        |
| batchReset              | 批量重置卡         |
| cardProduct             | 查询卡片归属的产品     |

### 4.2 套餐API

| 方法名                            | 说明            |
|--------------------------------|---------------|
| orderPackage                   | 套餐订购接口        |
| refundPackage                  | 套餐退款接口        |
| queryRefundAmount              | 查询可退款金额       |
| queryPackage                   | 查询套餐订购订单状态    |
| listOrderPackageByProduct      | 查询指定产品下可订购的套餐 |
| queryOrderPackageByPackageCode | 根据套餐编码查询套餐信息  |
| getOrderPackageDetails         | 批量查询订单对应套餐详情  |

### 4.3 代理商API

| 方法名          | 说明       |
|--------------|----------|
| agentBalance | 查询客户账户余额 |

### 4.4 短信API

| 方法名        | 说明   |
|------------|------|
| smsSendSms | 发送短信 |

### 4.5 eSIM API

| 方法名                   | 说明           |
|-----------------------|--------------|
| esimGoods             | 查询可订购的eSIM商品 |
| esimOrder             | 购买eSIM       |
| esimRefundPackage     | eSIM订单退款     |
| esimQueryPackage      | 查询eSIM订单详情   |
| esimQueryRefundAmount | 查询eSIM订单可退金额 |

### 4.6 CloudESIM API

| 方法名                        | 说明                  |
|----------------------------|---------------------|
| cloudesimList              | 查询账户下所有云esim卡片      |
| cloudesimDetail            | 单云esim卡片详情          |
| cloudesimAvailablePackages | 查询云esim卡片可购买套餐      |
| cloudesimOrderRecords      | 查询云esim卡片订购记录       |
| cloudesimRefreshUsage      | 账户下云esim卡片刷新套餐用量    |
| cloudesimCancelSession     | 账户下云esim卡片取消当前会话    |
| cloudesimOrder             | 账户下云esim卡套餐购买       |
| cloudesimQueryPackage      | 账户下云esim卡片订单状态      |
| cloudesimRefundPackage     | 账户下云esim卡订单退款       |
| cloudesimQueryRefundAmount | 查询账户下云esim卡片订单可退款金额 |

### 4.7 CDR API

| 方法名          | 说明          |
|--------------|-------------|
| cdrFlowQuery | ICCID流量查询接口 |

## 5. 认证服务

```java
import com.seetong.dingxin.service.DingXinAuthManager;
import com.seetong.common.iot.dto.dingxin.AuthRequest;
import com.seetong.common.iot.dto.dingxin.AuthResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class AuthService {

    @Autowired
    private DingXinAuthManager authManager;

    public AuthResponse authenticate(AuthRequest request) {
        return authManager.authToken(request);
    }

    public String generateSign(Map<String, Object> params) {
        return authManager.getSign(params);
    }
}
```

## 6. 异常处理

SDK使用自定义异常类`IotException`，包含错误码和错误信息：

```java
import com.seetong.common.iot.exception.IotException;
import com.seetong.common.iot.dto.IotResponse;

try {
    IotResponse<Map<String, Object>> response = eiotClient.getApi().cardDetail(Map.class, iccid);
} catch (IotException e) {
    System.out.println("错误码: " + e.getErrorCode());
    System.out.println("错误信息: " + e.getMessage());
}
```

## 7. 版本管理

| 版本             | 日期         | 描述   |
|----------------|------------|------|
| 1.0.0-SNAPSHOT | 2026-03-18 | 初始版本 |

## 8. 注意事项

1. 请确保配置了正确的app-key和secret
2. 所有API调用都会自动进行签名验证，无需手动处理
3. 请合理处理异常情况
4. 建议在生产环境中使用RELEASE版本，开发测试环境使用SNAPSHOT版本
5. 分页查询时，每页最大500条数据

## 9. 部署与引用

### 9.1 部署到Maven仓库

项目已配置自动部署到Topsee Maven仓库：

- **SNAPSHOT版本**: http://nexus.seetong.com/repository/maven-snapshots/
- **RELEASE版本**: http://nexus.seetong.com/repository/maven-releases/

### 9.2 构建项目

```bash
# 编译项目
mvn clean compile

# 安装到本地仓库
mvn clean install

# 部署到远程仓库
mvn clean deploy
```

## 10. 技术栈

- **Java**: 1.8+
- **Spring Boot**: 2.7.18
- **Lombok**: 1.18.24
- **Hutool**: 5.8.37
- **Fastjson2**: 2.0.57
- **Commons Codec**: 1.15

## 11. 联系方式

如有问题，请联系技术支持。