获取访问凭证

平台所有开放接口（除登录接口本身）都需要在请求头中携带访问凭证。本页说明怎么拿到它。

接口说明

使用平台分配的账号密码换取访问凭证 token。调用成功后，data.token 即为后续请求所需的凭证。

什么时候需要调用

程序启动 / 首次调用业务接口之前
凭证失效时（见使用凭证）
密码被修改后

请求地址

text

POST https://yunshangwenshi.auto-control.com.cn/api/account/sign-in

请求方法

POST

请求头

请求头	值	必填	说明
`Content-Type`	`application/json`	是	请求体为 JSON
`Accept`	`application/json`	否	期望返回 JSON

登录接口不需要带 Authorization

这是唯一一个不需要访问凭证的接口 —— 凭证本身就是从这里获取的。

请求参数

请求体为 JSON：

参数名	类型	必填	说明	示例
`username`	String	是	平台分配的账号	`your_account`
`password`	String	是	账号密码（依赖 HTTPS 加密传输）	`your_password`

返回字段

顶层

字段名	类型	说明	示例
`requestId`	String	本次请求的唯一标识，报障时请提供	`ec7d3b00-725c-485a-ae68-3a6e2b4e7e97`
`code`	Int	状态码，`200` 表示成功	`200`
`message`	String \| null	提示信息，成功时通常为 `null`	`null`
`data`	Object	凭证数据对象，见下表	—
`errorDetail`	String \| null	错误详情，成功时为 `null`	`null`
`timestamp`	Long	服务端响应时间戳（毫秒）	`1789466324170`
`success`	Boolean	是否成功	`true`

`data` 对象

字段名	类型	说明	示例
`token`	String	访问凭证（JWT），后续请求放在 `Authorization` 头	`eyJhbGciOiJIUzUxMiJ9...`
`tokenType`	String	凭证类型，固定为 `Bearer`	`Bearer`
`userId`	Int	用户 ID	`626`
`customerId`	Long	客户（租户）ID，用于核对数据归属	`1667372262`
`username`	String	账号名	`autotest`
`authorities`	Array<String>	权限列表，可能为空数组	`[]`
`roles`	String	角色标识	`SYSTEM_ADMIN`
`expert`	String	专家标识，无值时为空串	`""`
`generationTime`	Long	凭证签发时间（毫秒）；接口返回值可能为 `0`	`0`

authorities 与 roles 是两个不同的字段

authorities 是数组，业务账号上常见为空数组 []
roles 是字符串，承载实际角色标识（如 SYSTEM_ADMIN）

判断账号角色请用 roles，不要依赖 authorities 是否非空。

请求示例

curl

bash

curl -X POST 'https://yunshangwenshi.auto-control.com.cn/api/account/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{"username":"<你的账号>","password":"<你的密码>"}'

HTTP 报文

http

POST /api/account/sign-in HTTP/1.1
Host: yunshangwenshi.auto-control.com.cn
Content-Type: application/json

{
  "username": "<你的账号>",
  "password": "<你的密码>"
}

Python

python

import requests

BIZ_HOST = "https://yunshangwenshi.auto-control.com.cn"


def sign_in(username: str, password: str) -> str:
    """登录并返回访问凭证 token。"""
    resp = requests.post(
        f"{BIZ_HOST}/api/account/sign-in",
        json={"username": username, "password": password},
        timeout=10,
    )
    resp.raise_for_status()
    body = resp.json()

    # 注意：登录失败时 HTTP 状态码仍是 200，必须判断 body 里的 code
    if body.get("code") != 200:
        raise RuntimeError(
            f"登录失败: code={body.get('code')} message={body.get('message')} "
            f"errorDetail={body.get('errorDetail')} requestId={body.get('requestId')}"
        )

    data = body["data"]
    print(f"userId={data['userId']} customerId={data['customerId']} roles={data.get('roles')}")
    return data["token"]


if __name__ == "__main__":
    token = sign_in("<你的账号>", "<你的密码>")
    print(token[:32] + "...")

Java

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class IotAuth {

    private static final String BIZ_HOST = "https://yunshangwenshi.auto-control.com.cn";
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    /** 登录并返回 access token；失败时抛出带 code/message 的异常。 */
    public static String signIn(String username, String password) throws Exception {
        String payload = String.format(
                "{\"username\":\"%s\",\"password\":\"%s\"}", username, password);

        HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(BIZ_HOST + "/api/account/sign-in"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(10))
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> resp = CLIENT.send(req, HttpResponse.BodyHandlers.ofString());
        return parseTokenOrThrow(resp.body());   // 用 Jackson/Gson 解析，勿手写正则
    }
}

关于 SDK

平台未提供官方 SDK。上述示例依赖标准 HTTP 客户端； Java 示例中的 JSON 解析请使用 Jackson / Gson 等成熟库。

返回示例

成功

json

{
  "requestId": "ec7d3b00-725c-485a-ae68-3a6e2b4e7e97",
  "code": 200,
  "message": null,
  "data": {
    "customerId": 1667372262,
    "username": "autotest",
    "userId": 626,
    "authorities": [],
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI2MjYiLCJjdXN0b21lcklkIjoiMTY2NzM3MjI2MiIs...<已截断>",
    "tokenType": "Bearer",
    "roles": "SYSTEM_ADMIN",
    "expert": "",
    "generationTime": 0
  },
  "errorDetail": null,
  "timestamp": 1789466324170,
  "success": true
}

失败（账号或密码错误）

失败时 HTTP 状态码仍然是 200

必须判断返回体的 code。见错误码。

json

{
  "requestId": "50a0b4a2-67b3-4f39-9b82-b60ecbf8a50c",
  "code": 401,
  "message": "AuthError",
  "data": null,
  "errorDetail": "Bad credentials",
  "timestamp": 1789466363395,
  "success": false
}

字段	取值	说明
HTTP 状态码	`200`	注意：不是 401
`code`	`401`	业务码，认证失败
`message`	`AuthError`	固定取值
`errorDetail`	`Bad credentials`	固定取值

注意事项

不要把账号密码写进客户端

移动端 / 浏览器 / 桌面客户端中不要直接调用本接口，应由你的服务端代持凭证
不要把 username / password 提交到代码仓库或写入前端配置文件
建议使用环境变量或密钥管理服务下发

一次登录，多处复用

登录接口用于「换取 token」，不是「每次请求前置调用」。建议在服务端做 token 缓存（见使用凭证）。

修改密码对已签发凭证的影响

平台未说明修改密码是否会立即使已签发的 token 失效。 安全起见请假定旧 token 在有效期内仍然可用，密码变更后主动清理缓存并重新登录。

下一步

→ 使用凭证：token 放在哪个请求头、有效期多久、失效了怎么办。

获取访问凭证 ​

接口说明 ​

请求地址 ​

请求方法 ​

请求头 ​

请求参数 ​

返回字段 ​

顶层 ​

data 对象 ​

请求示例 ​

curl ​

HTTP 报文 ​

Python ​

Java ​

返回示例 ​

成功 ​

失败（账号或密码错误） ​

注意事项 ​

下一步 ​