全局说明

SmartHub API 是一套基于 HTTPS 协议的 RESTful 风格 API。

您可以使用最喜欢的 HTTP/REST 库(比如 Apache Http Client )来访问 SmartHub 的 API，或者使用

HTTP/REST 客户端(比如 Postman )来访问 SmartHub 的 API。

版本

SmartHub API 的版本号放入 URI 中，样例:

https://xxx.smh.smarthing.com/v1/users

Schema

所有的 SmartHub API 都基于 HTTPS 协议

生产环境域名：https://api.smh.smarthing.com

演示环境域名：https://trial.api.smh.smarthing.com。

所有的 Request 和 Response 数据都是通过 JSON 格式。

所有的时间字段都是格式化为 ISO 8601 格式返回: yyyy-MM-dd'T'HH:mm:ssZ

认证

SmartHub API 提供以下的认证方式。

ApiKeyAuth

请务必保证认证信息的安全，不要分享给别人

认证失败返回

使用无效凭据进行身份验证将返回 401 Unauthorized:

{
  "type": "about:blank",
  "title": "Invalid api key",
  "status": 401
}

请求认证用户无权访问的资源时将返回 403 Forbidden:

{
    "type": "about:blank",
    "title": "Access forbidden",
    "status": 403
}

根端点

可以通过访问根端点来获得 SmartHub API 提供的所有端点类别:

客户端错误

在 API 调用时存在 3 种可能的客户端错误:

发送非法的 JSON 格式将返回 400 Bad Request 响应

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Body should be a JSON object"
}

发送错误的 JSON 值类型将返回 400 Bad Request 响应

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Body should be a JSON object"
}

发送无效字段将返回 422 Unprocessable Entity 响应

{
    "type": "about:blank",
    "title": "Validation Failed",
    "status": 422,
    "errors": [
        {
            "resource": "customFieldVO",
            "field": "custom1",
            "code": "invalid"
        }
    ]
}

所有错误对象都具有资源和字段属性，以便客户端可以知道问题所在。还存在一个错误代码表示该字段有什么问题。以下是可能的验证错误代码：

错误代码	描述
missing	资源不存在
missing_field	资源的必填字段未设置
invalid	字段格式无效，详情请见该资源的具体文档描述
already_exists	该资源已存在

资源也可能自定义错误码。自定义错误会提供 message 字段描述错误，并且部分错误还提供一个 documentation_url
字段提供更详细的描述。

HTTP 重定向

SmartHub API 必要时候会使用 HTTP

重定向。客户端应该假定任何请求都可能导致重定向。接收HTTP重定向不是错误，客户端应遵循该重定向。重定向会在响应头中携带 Location

字段，该字段指向客户端应重复请求的资源的 URI。

状态码	描述
`301`	永久重定向。原始的 `URI` 已经迁移到 `Location` 指定的新的 `URI`中，此资源以及将来对此资源的所有请求都应定向到新 `URI`。
`302`,`307`	临时重定向。请求应该使用 `Location` 中指定的 `URI` 并且将来可以继续使用。

HTTP 动词

在可能的情况下，SmartHub API 会尽可能的为每个动作使用适当的 HTTP 动词。

动词	描述
`HEAD`	获取资源的头信息，不包含资源内容
`GET`	获取资源
`POST`	创建资源
`PUT`	替换资源或集合。对于 `body` 为空的请求，请确保头字段 `Content-Length` 值为 0。
`DELETE`	删除资源

超媒体

所有的资源都可能包含 *_url 属性链接到其他资源。这些用于提供显式 URL ，以便 API 客户端不需要自己构建 URL，
并强烈建议 API客户端使用这些。这样可以使得开发人员升级 API 更容易。
所有的 URL 都符合 URL 6570 URI 模板规范。

分页

默认情况下，返回多个项的请求将返回 30 个项。客户端可以使用 ?page 参数指定更过的页。对于一些资源，客户端也可以通过 ?size 参数指定每页的大小，最大设置为 100。

页码参数 ?size 从 1 开始计算，不传默认返回第 1 页。

Link header

强烈建议使用 Link Header 提供的 URL进行资源访问。

Link Header 包含分页信息。

# 只有一页结果
Link: <https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="last",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="first"
X-Total-Count: 10
# 有多页结果
Link: <https://xxx.smh.smarthing.com/points?page=2&size=20>;
rel="next",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="prev",<https://xxx.smh.smarthing.com/points?page=5&size=20>;
rel="last",<https://xxx.smh.smarthing.com/points?page=0&size=20>;
rel="first"
X-Total-Count: 110

rel 值定义如下：

名称	描述
`next`	下一页
`last`	最后一页
`first`	首页
`prev`	前一页

限流

每个用户 API 次数限制为每小时 5000 次。这个限制是应用于账户的。HTTP 的响应头会显示限流状态:

头字段名称	描述
`X-RateLimit-Limit`	每小时允许的最大请求数
`X-RateLimit-Remaining`	当前速率限制窗口中剩余的请求数量
`X-RateLimit-Reset`	当前速率限制窗口重置的时间(UTC秒)

如果超过速率限制，会返回如下错误信息:

X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3600
{
  "type":"about:blank",
  "title":"API rate limit exceeded",
  "status":429
}

跨域访问

SmartHub API 支持跨域访问(CORS)，支持其他任何网站的 AJAX请求。以下是从一个 http://example.com 网站访问 SmartHub API 的样例:

以下是 CORS 的预检查返回样例:

时区

SmartHub API 所有请求都使用 UTC 时区做为创建时间或操作时间。

Push

SmartHub 平台提供消息 Push 功能, 需要账户在 SmartHub 平台上配置推送的 URL, 如: https://xxx.smh.smarthing.com/v1/mo-sms。推送的请求格式见 API 文档中的 Push 分类。每一种推送分类都需要配置特定的 URL。

Push 认证

SmartHub Push 时会在 request body 中带上签名字段 signature，生成规则如下：

字段名称	类型	生成规则
signature	String	HEX(SHA256(`pushKey` + datePush))

pushKey由账户在 SmartHub 平台上配置

datePush 是请求体里的字段，这里转换为精确到秒的数字

SHA256 表示使用 SHA256 进行 hash ，注意这里 hash 后的结果为字节数组

HEX 表示对8bit字节数组逐个字节进行十六进制编码拼接

签名代码样例（Java实现）：

public class Signature {
    public static byte[] SHA256(byte[] data) throws java.security.NoSuchAlgorithmException {
        return java.security.MessageDigest.getInstance("SHA-256").digest(data);
    }

    public static String HEX(byte[] octets) {
        StringBuilder sb = new StringBuilder();

        for(byte b: octets) {
            if (b >= 0 && b < 16) sb.append("0");
            sb.append(Integer.toHexString(b & 0xFF));
        }

        return sb.toString();
    }

    public static String makeSignature(String pushKey, long epocSeconds) throws Exception {
        return HEX(SHA256((pushKey + epocSeconds).getBytes("UTF8")));
    }

    public static void main(String[] args) throws Exception {
        System.out.println(makeSignature("UzE4MDkxNDA2MTE1M", 1725499848L));
        // Output: 58210277eeea982589a3f2c5711ce5ac23a866298d77fcb5c30bb1e0aa9c345f
    }
}

Push Ftp Cdr

SmartHub 平台提供向客户ftp服务器推送话单功能，需要客户有对应的ftp服务器并将相关配置与平台对接。推送的流量话单为CDR_D_xx.cdr格式，短信话单CDR_S_xx.cdr格式。文件内容如下：

data cdr:

{"giccid":"8944501503181377993","data_usage":1302,"start_time":1713888842473,"duration":0,"mcc":"460","mnc":"10","country_code":"CN","apn":"apn1","imsi":"460001234567890","sim_group":"groupA"}

sms cdr:

{"giccid":"8944500310194312699","event_time":1711889742473,"from_msisdn":"882360010341361","to_msisdn":"449086237252","imsi":"460001234567890","sim_group":"groupA"}

版本#

Schema#

认证#

认证失败返回#

根端点#

客户端错误#

HTTP 重定向#

HTTP 动词#

超媒体#

分页#

Link header#

限流#

跨域访问#

时区#

Push#

Push 认证#

Push Ftp Cdr#

版本