Tigshop API Token 使用教程

适用对象：需要用程序（ERP、WMS、数据看板、自动化脚本等）对接 Tigshop 后台接口的技术人员

适用版本：Tigshop v5.8.21 及以上

---

一、这个功能是什么

平时你在后台点击页面时，系统靠“登录态”来识别你的身份，这个登录态会过期，也没办法交给程序使用。

API Token 就是为程序准备的一把“长期钥匙”：

• 在后台自助生成一串固定的密钥字符串
• 程序在调用接口时把它放进请求头，就能直接以你这个管理员的身份访问后台接口
• 不需要写死账号密码，不需要模拟登录，不会因为登录过期而中断

典型使用场景：

场景	说明
ERP / 进销存对接	定时同步商品、库存、订单
数据报表 / BI	定时拉取订单和交易数据
自动化运维脚本	批量改价、批量上下架
第三方系统回写	外部系统把发货、审核结果写回商城

重要前提：API Token 拥有的权限，和生成它的那个管理员账号完全一样。请把它当作账号密码同等级别的机密来保管。

---

二、快速开始（三步走）

1. 后台生成一个 Token，复制保存
2. 调用接口时带上请求头 X-Api-Token
3. 拿到返回的 JSON 数据

curl -X GET "https://你的商城域名/adminapi/product/product/list?page=1&size=10" \
  -H "X-Api-Token: 08180425f3c1b7e94a2d6f0c5b8e1a37" \
  -H "X-ADMIN-TYPE: admin"

下面是详细说明。

---

三、第一步：在后台生成 Token

3.1 进入管理页面

登录商城管理后台，依次进入：

权限 → 个人中心 → 切换到“API Token”标签页

3.2 生成 Token

点击左上角 生成 Token 按钮，填写两项内容：

字段	是否必填	说明
名称/备注	必填	用来标记这个 Token 的用途，例如“ERP库存同步”“数据报表脚本”。最多 50 字
有效期	选填	可选 7 天 / 30 天 / 60 天 / 90 天 / 永不过期，默认已选中 30 天

提交后页面会显示完整的 Token，形如：

08180425f3c1b7e94a2d6f0c5b8e1a37

Token 是 32 位十六进制字符串。

⚠️ Token 明文只显示这一次。 请立即点击“复制”并保存到你的配置文件或密钥管理工具中。关闭窗口后，列表里只会显示前 8 位（例如 08180425****…），无法再次查看完整内容。如果不小心弄丢了，只能吊销后重新生成一个。

3.3 查看和管理已有 Token

列表中每一行展示：

列	说明
Token	只显示前 8 位，后面用 * 掩码
名称	生成时填写的备注
创建时间	Token 生成时间
最后使用	最近一次被程序调用的时间；从未调用则显示“从未使用”
过期时间	到期时间，或“永不过期”；已过期会标红
状态	有效 / 已过期 / 已吊销
操作	有效状态下可以“吊销”

吊销：点击“吊销”并确认后，该 Token 立即失效且无法恢复，所有正在使用它的程序会立刻报错。请确认对接方已切换到新 Token 后再吊销旧的。

3.4 数量限制

每个管理员账号最多同时拥有 10 个未吊销的 Token。达到上限时生成会失败，提示“每个管理员最多拥有 10 个有效Token”，请先吊销不再使用的旧 Token。

---

四、第二步：用 Token 调用接口

4.1 接口地址规则

所有后台接口都以 /adminapi 开头：

https://你的商城域名/adminapi/{模块}/{控制器}/{方法}

例如商品列表：

https://你的商城域名/adminapi/product/product/list

API Token 只能用于后台管理接口（/adminapi 开头），不能用于商城前台的会员接口。

4.2 请求头说明

请求头	是否必填	值	说明
X-Api-Token	必填	你的 Token	身份凭证
X-ADMIN-TYPE	必填	admin / shop / vendor	账号类型：平台管理员填 admin，店铺（商家）管理员填 shop，供应商填 vendor
X-Shop-Id	商家端必填	店铺 ID	仅当 X-ADMIN-TYPE 为 shop 时需要
X-Vendor-Id	供应商端必填	供应商 ID	仅当 X-ADMIN-TYPE 为 vendor 时需要
Content-Type	POST 时必填	application/json	请求体为 JSON
X-Locale-Code	可选	如 zh-cn / en	多语言站点用于指定返回语言

请求头名称不区分大小写。

X-ADMIN-TYPE 必须与 Token 所属管理员的真实身份一致。填错会导致“用户已经被禁用”或权限不足的报错。

4.3 另一种传递方式（兼容写法）

除了 X-Api-Token，也可以放在标准的 Authorization 头里：

Authorization: Bearer 08180425f3c1b7e94a2d6f0c5b8e1a37

系统会自动识别：如果值是 32 位十六进制字符串，就按 API Token 处理；否则按后台登录的 JWT 处理。

推荐使用 X-Api-Token，因为它的报错信息更明确（Token 错误时会直接提示“API Token无效或已过期”），而用 Authorization 传错值时，系统会误判成 JWT 并返回登录态相关的报错，不利于排查。

4.4 调用示例

cURL——GET 请求（查询商品列表）

curl -X GET "https://你的商城域名/adminapi/product/product/list?page=1&size=10" \
  -H "X-Api-Token: 08180425f3c1b7e94a2d6f0c5b8e1a37" \
  -H "X-ADMIN-TYPE: admin"

cURL——POST 请求

curl -X POST "https://你的商城域名/adminapi/{模块}/{控制器}/{方法}" \
  -H "X-Api-Token: 08180425f3c1b7e94a2d6f0c5b8e1a37" \
  -H "X-ADMIN-TYPE: admin" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

cURL——商家（店铺）身份调用

curl -X GET "https://你的商城域名/adminapi/product/product/list?page=1&size=10" \
  -H "X-Api-Token: 08180425f3c1b7e94a2d6f0c5b8e1a37" \
  -H "X-ADMIN-TYPE: shop" \
  -H "X-Shop-Id: 3"

Python

import requests

BASE_URL = "https://你的商城域名/adminapi"
HEADERS = {
    "X-Api-Token": "08180425f3c1b7e94a2d6f0c5b8e1a37",
    "X-ADMIN-TYPE": "admin",
    "Content-Type": "application/json",
}

resp = requests.get(
    f"{BASE_URL}/product/product/list",
    headers=HEADERS,
    params={"page": 1, "size": 10},
    timeout=30,
)
result = resp.json()

if result["code"] == 0:
    data = result["data"]
    print("总数：", data["total"])
    for item in data["records"]:
        print(item["productId"], item["productName"])
else:
    print("调用失败：", result["message"])

PHP

<?php

$baseUrl = 'https://你的商城域名/adminapi';
$token = '08180425f3c1b7e94a2d6f0c5b8e1a37';

$ch = curl_init($baseUrl . '/product/product/list?page=1&size=10');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Token: ' . $token,
        'X-ADMIN-TYPE: admin',
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['code'] === 0) {
    print_r($result['data']);
} else {
    echo '调用失败：' . $result['message'];
}

Java（OkHttp）

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
        .url("https://你的商城域名/adminapi/product/product/list?page=1&size=10")
        .addHeader("X-Api-Token", "08180425f3c1b7e94a2d6f0c5b8e1a37")
        .addHeader("X-ADMIN-TYPE", "admin")
        .get()
        .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

---

五、第三步：读取返回结果

所有接口返回统一的 JSON 结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

字段	说明
code	0 表示成功；非 0 表示失败（业务错误通常为 1001）
message	提示信息，失败时为失败原因
data	业务数据，结构由具体接口决定

请务必先判断 code 是否为 0，再读取 data。

分页类接口的 data 是标准分页结构：

{
  "code": 0,
  "message": "success",
  "data": {
    "records": [{}],
    "total": 128,
    "size": 10,
    "current": 1,
    "pages": 13
  }
}

分页参数通用约定：

参数	说明
page	页码，从 1 开始，默认 1
size	每页条数，默认 15，最大 100（传更大的值会被强制按 100 处理）
keyword	关键词搜索（部分接口支持）
sortField / sortOrder	排序字段 / 排序方向（asc、desc）

---

六、权限说明

这是最容易踩坑的部分，请重点阅读。

1. Token 完全继承生成它的管理员的权限。 那个管理员能在后台做什么，Token 就能调用什么接口；管理员不能做的，Token 也调不通（返回 code: 1001 并提示无权限）。
2. 权限变更立即生效。 每次接口调用都会实时读取该管理员当前的角色权限，在后台调整角色权限后无需重新生成 Token。
3. 账号状态直接影响 Token。 管理员被禁用或删除后，其名下所有 Token 立即无法调用。
4. 强烈建议为对接单独创建一个管理员账号，只分配这次对接真正需要的角色权限，再用它生成 Token。这样即使 Token 泄露，影响范围也是可控的；换人交接时也只需吊销这一个账号的 Token。

---

七、Token 管理接口（可选，用于自动化）

如果你希望用程序管理 Token（例如自动轮换），可以直接调用下面三个接口。它们同样支持用 API Token 调用。

7.1 生成 Token

POST /adminapi/authority/adminUser/apiToken/generate

请求体：

{
  "name": "ERP库存同步",
  "expiresInDays": 30
}

参数	类型	说明
name	string	名称/备注，不传则默认为 default
expiresInDays	int	有效天数；不传或传 null 表示永不过期

返回：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12,
    "token": "08180425f3c1b7e94a2d6f0c5b8e1a37",
    "name": "ERP库存同步",
    "expiresAt": 1767225600
  }
}

token 字段是明文 Token，只在这一次返回中出现，请立即保存。expiresAt 是秒级时间戳，null 表示永不过期。

7.2 查询 Token 列表

GET /adminapi/authority/adminUser/apiToken/list

返回当前管理员名下的所有 Token（含已吊销、已过期）：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 12,
      "tokenPrefix": "08180425",
      "name": "ERP库存同步",
      "createdAt": 1764633600,
      "lastUsedAt": 1764720000,
      "expiresAt": 1767225600,
      "isActive": 1
    }
  ]
}

字段	说明
tokenPrefix	Token 前 8 位，用于识别是哪一个（不返回完整 Token）
createdAt / lastUsedAt / expiresAt	秒级时间戳；lastUsedAt、expiresAt 可能为 null
isActive	1 有效，0 已吊销

7.3 吊销 Token

POST /adminapi/authority/adminUser/apiToken/revoke

请求体：

{
  "id": 12
}

只能吊销自己名下的 Token，吊销后立即失效且不可恢复。

---

八、安全建议

建议	说明
只放服务端	绝不要把 Token 写进前端页面、App 包体或公开的代码仓库
一用途一 Token	每个对接系统单独生成一个，出问题时可以精准定位和单独吊销
设置有效期	优先选 30/60/90 天并定期轮换，尽量避免“永不过期”
用最小权限账号	为对接单独建管理员账号，只给必要的角色权限
强制 HTTPS	Token 在请求头中明文传输，必须走 HTTPS
泄露立即吊销	怀疑泄露时第一时间在后台吊销，再生成新的替换
不写死在代码里	放在环境变量或配置中心，方便轮换

轮换 Token 的推荐顺序：

先生成新 Token → 更新对接系统配置并验证通过 → 再吊销旧 Token

这样不会产生服务中断。

---

九、注意事项与限制

• Token 明文只在生成时显示一次，无法找回
• 每个管理员最多同时持有 10 个未吊销的 Token
• 吊销操作立即生效且不可恢复
• 因服务端存在校验缓存，Token 到达过期时间后可能仍有最长约 1 小时的可用窗口。如需立刻失效，请使用“吊销”功能，吊销是即时生效的
• “最后使用”时间为异步更新，可能有短暂延迟，不适合作为精确审计依据
• 单页数据量上限 100 条，拉取全量数据请翻页
• Token 仅适用于 /adminapi 后台接口

---

十、常见问题排查

报错/现象	可能原因	处理方式
提示 API Token无效或已过期	Token 抄写错误（多了空格/换行）、已被吊销、已过期	核对 Token 是否为完整的 32 位；在后台确认状态；必要时重新生成
提示登录已过期/token异常	用 Authorization: Bearer 传了非 32 位十六进制的值，被当成登录 JWT 处理	改用 X-Api-Token 请求头
提示 用户已经被禁用	管理员账号被停用；或 X-ADMIN-TYPE、X-Shop-Id 与账号真实身份不匹配	检查账号启用状态，核对身份类型相关请求头
返回 code: 1001 且提示无权限	Token 所属管理员的角色缺少该接口权限	在后台为该管理员的角色补齐对应功能权限
返回 404	接口路径写错，或漏掉了 /adminapi 前缀	核对完整路径
返回 code: 1001 且提示参数相关错误	请求参数缺失或类型不对；POST 未设置 Content-Type: application/json	按接口要求补全参数和请求头
生成 Token 时提示数量上限	未吊销的 Token 已达 10 个	先吊销不再使用的 Token

---

十一、如何查询有哪些可用接口

Tigshop 后台接口数量很多，本文档不逐一列举。获取接口清单有两种方式：

1. 在线接口文档：访问 https://你的商城域名/doc.html，其中包含全部后台接口的路径、参数和返回结构（如生产环境未开放该地址，请联系我们）。
2. 从后台页面反查：在浏览器中打开对应的后台页面，按 F12 打开开发者工具的“网络”面板，操作一次即可看到该功能实际调用的接口地址和参数，直接照抄到你的程序里即可。

---

十二、升级说明（从低于 v5.8.21 的版本升级）

该功能依赖新增的数据表 admin_api_token。如果你是从旧版本升级：

1. 执行升级脚本 database/5.8.20-5.8.21update.sql 中的 admin_api_token 建表语句
2. 确认 Redis 服务正常运行（Token 校验依赖 Redis 缓存）
3. 重启 Java 服务后，即可在“个人中心”看到“API Token”标签页

如需协助，请联系 Tigshop 技术支持。