API 接口参考：短链管理 - 小南短链帮助中心

📖 MCP & API 🎯 进阶 ⏱ 8 分钟

API 接口参考：短链管理

短链的创建、更新、状态管理与删除接口详解，附完整参数与示例。

1. 接口一览

短链管理分组共 8 个接口，覆盖短链从创建到删除的完整生命周期：

方法	路径	说明
POST	`/api/link/create`	生成短链
POST	`/api/link/quick-create`	快捷生成短链
POST	`/api/link/update`	更新短链
POST	`/api/link/update-status`	修改短链状态
POST	`/api/link/batch-update-domain`	批量修改域名前缀
POST	`/api/link/delete`	删除短链
GET	`/api/link/detail`	短链详情
GET	`/api/link/check-visit-code`	检查短链后缀是否重复

通用约定：

Base URL：https://open.xnanlink.com
鉴权：所有请求携带请求头 Token: YOUR_TOKEN，POST 请求另需 Content-Type: application/json
响应：统一 JSON 结构 code（OK 表示成功）、message、data、success

2. 生成短链

2.1 POST /api/link/create

创建一条新的短链，支持自定义访问码、路由规则、过期时间等。请求参数如下：

参数	类型	必填	说明
`sourceLink`	string	是	原始链接
`domain`	string	是	选择的域名
`linkType`	string	否	短链类型
`visitCode`	string	否	自定义访问码，不传则随机生成
`rules`	array	否	路由规则列表，子字段见下表
`expireDate`	string	否	过期时间，不传则按套餐默认
`jumpType`	string	否	跳转类型，仅微信外链有效

rules 数组的每个元素包含以下子字段：

子字段	类型	说明
`ruleId`	integer (int64)	规则 ID
`routingType`	string	路由类型（如按设备、按地区）
`matchRule`	string	匹配规则
`url`	string	命中该规则时跳转的目标 URL

请求示例：

curl -X POST 'https://open.xnanlink.com/api/link/create' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "sourceLink": "https://www.example.com/page?id=123",
    "domain": "lxs.la",
    "linkType": "COMMON",
    "visitCode": "mycode"
  }'

响应示例：

{
  "code": "OK",
  "message": "成功",
  "data": true,
  "success": true
}

2.2 POST /api/link/quick-create

快捷生成短链，仅需 sourceLink 与 domain 两个必填参数（另可选 linkType），访问码、过期时间等全部使用默认值：

curl -X POST 'https://open.xnanlink.com/api/link/quick-create' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "sourceLink": "https://www.example.com/page?id=123",
    "domain": "lxs.la"
  }'

与 create 的选择建议：

quick-create：适合「给我一条短链就行」的场景，如消息推送、日常缩短链接，参数最少、接入最快
create：适合需要品牌化后缀（自定义访问码）、按设备/地区分流（路由规则）、活动限时（过期时间）等精细控制的场景

3. 更新短链

3.1 POST /api/link/update

更新已存在的短链信息，包括原始链接、域名、访问码、路由规则等。请求参数如下：

参数	类型	必填	说明
`linkId`	integer (int64)	是	短链 ID
`sourceLink`	string	是	原始链接
`domain`	string	是	选择的域名
`visitCode`	string	否	自定义访问码
`rules`	array	否	路由规则列表，子字段同 create 接口
`expireDate`	string	否	过期时间
`jumpType`	string	否	跳转类型

请求示例：

curl -X POST 'https://open.xnanlink.com/api/link/update' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "linkId": 100001,
    "sourceLink": "https://www.example.com/updated",
    "domain": "lxs.la",
    "visitCode": "newcode",
    "expireDate": "2026-12-31"
  }'

响应示例：

{
  "code": "OK",
  "message": "成功",
  "data": true,
  "success": true
}

3.2 POST /api/link/update-status

批量修改短链状态。参数为 linkIds（短链 ID 数组，至少 1 个）和 status（整数）。状态取值：

0：正常，短链可正常访问
1：停止访问，短链暂时禁用，可随时恢复
2：被封禁

curl -X POST 'https://open.xnanlink.com/api/link/update-status' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "linkIds": [100001, 100002],
    "status": 1
  }'

3.3 POST /api/link/batch-update-domain

将多条短链的域名批量替换为新域名，适合切换品牌域名或迁移域名的场景。参数为 linkIds（短链 ID 数组，至少 1 个）和 domain（新域名）：

curl -X POST 'https://open.xnanlink.com/api/link/batch-update-domain' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "linkIds": [100001, 100002, 100003],
    "domain": "new.la"
  }'

4. 删除短链

POST /api/link/delete 用于删除短链。请求体直接是短链 ID 数组（不是对象），支持一次删除多条：

curl -X POST 'https://open.xnanlink.com/api/link/delete' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '[100001, 100002]'

小贴士

删除操作不可恢复，短链删除后立即失效且无法找回。如果只是想暂时停用短链，请改用 update-status 接口将状态设为 1（停止访问），后续可随时恢复。

5. 查询与校验

5.1 GET /api/link/detail

根据短链 ID 查询单条短链的详细信息，查询参数为 linkId（必填）：

curl -X GET 'https://open.xnanlink.com/api/link/detail?linkId=100001' \
  -H 'Token: YOUR_TOKEN'

{
  "code": "OK",
  "message": "成功",
  "data": {
    "linkId": 100001,
    "linkType": "COMMON",
    "sourceLink": "https://www.example.com/page?id=123",
    "domain": "lxs.la",
    "visitCode": "abc123",
    "jumpType": "301",
    "expireDate": "2026-12-31T00:00:00"
  },
  "success": true
}

data 对象的字段说明：

字段	类型	说明
`linkId`	integer (int64)	短链 ID
`linkType`	string	短链类型
`sourceLink`	string	原始链接
`domain`	string	域名
`visitCode`	string	访问码
`rules`	array	路由规则列表
`jumpType`	string	跳转类型
`expireDate`	string (date-time)	过期时间

5.2 GET /api/link/check-visit-code

检查指定域名下的短链访问码是否已被使用。查询参数为 domain（必填）、visitCode（必填）和 linkId（可选，更新场景下传入以排除自身）。

返回值语义：data 为 true 表示该访问码已存在（不可用），false 表示可用：

curl -X GET 'https://open.xnanlink.com/api/link/check-visit-code?domain=lxs.la&visitCode=mycode' \
  -H 'Token: YOUR_TOKEN'

{
  "code": "OK",
  "message": "成功",
  "data": false,
  "success": true
}

6. 常见问题

自定义访问码有什么格式限制？

访问码是短链域名后的路径部分，建议使用字母与数字的组合，保持简短易记。同一域名下访问码必须唯一，创建或更新前建议先调用 check-visit-code 接口确认可用，避免因重复导致创建失败。

路由规则 rules 如何配置分流？

每条规则包含 routingType（路由类型，如按设备、按地区）、matchRule（匹配规则）和 url（命中后跳转的目标地址）。可先调用 GET /api/link/routing/rule 获取分流规则下拉数据（如 DEVICE 按设备：PC 端/移动端，REGION 按地区：中国大陆/海外），再按需组装 rules 数组。未命中任何规则的访问将跳转到 sourceLink。

批量操作有数量上限吗？

update-status、batch-update-domain、delete 等批量接口的 ID 数组至少需要 1 个元素。单次请求建议控制在合理数量内（如数百条以内），数据量很大时建议分批调用，既能降低单次请求超时风险，也便于失败重试。

7. 下一步

短链管理之外的接口能力，请继续阅读：

API 接口参考：查询、批量导入与访问统计——短链列表分页查询、Excel/JSON 批量导入、访问记录与基础数据接口