API 接口参考：查询、批量导入与访问统计 - 小南短链帮助中心

📖 MCP & API 🎯 进阶 ⏱ 8 分钟

API 接口参考：查询、批量导入与访问统计

短链列表查询、Excel/JSON 批量导入、访问记录与基础数据接口详解。

本文介绍小南短链开放平台的查询、批量导入、访问统计与基础数据四组接口。所有接口的基础地址均为 https://open.xnanlink.com，调用时需在请求头携带 Token 完成鉴权，返回统一的 JSON 格式。

1. 短链查询

1.1 POST /api/link/list — 查询短链列表

分页查询账号下的短链列表，支持按域名、类型、访问码、状态、创建时间区间、点击次数区间等条件组合过滤。请求体类型为 application/json。

参数	类型	必填	说明
pageNum	integer (int32)	否	页码
pageSize	integer (int32)	否	每页数量
domain	string	否	当前选中的域名，为 null 则查全部
linkType	string	否	短链类型
visitCode	string	否	短链访问码
status	integer (int32)	否	状态：0 正常、1 停止访问、2 被封禁
createdTimeStart	string (date-time)	否	创建时间-开始
createdTimeEnd	string (date-time)	否	创建时间-结束
totalClickCntMin	integer (int64)	否	最小访问次数
totalClickCntMax	integer (int64)	否	最大访问次数

返回数据为标准分页结构：data 中包含 pageNum、pageSize、total 和结果集 list。列表项的主要字段说明：

id / linkType / sourceLink：短链 ID、短链类型、原始链接
visitPrefix / visitCode：访问前缀（域名部分）与短链访问码
ownDomain / sslFlag：是否自有域名（0 否 / 1 是）、是否开启 SSL（0 否 / 1 是）
status：状态，0 正常、1 停止访问、2 被封禁
totalClickCnt / todayClickCnt：累计点击次数与今日点击次数
expireDate / createdTime：过期时间与创建时间

curl 请求示例：

curl -X POST 'https://open.xnanlink.com/api/link/list' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "domain": "lxs.la",
    "status": 0
  }'

响应示例：

{
  "code": "OK",
  "message": "成功",
  "data": {
    "pageNum": 1,
    "pageSize": 20,
    "total": 158,
    "list": [{
      "id": 100001,
      "linkType": "COMMON",
      "sourceLink": "https://www.example.com/page?id=123",
      "visitPrefix": "lxs.la",
      "visitCode": "abc123",
      "ownDomain": 0,
      "sslFlag": 1,
      "status": 0,
      "totalClickCnt": 3580,
      "todayClickCnt": 42,
      "createdTime": "2026-01-15T10:30:00"
    }]
  },
  "success": true
}

2. 批量导入

批量导入提供 Excel 文件与 JSON 入参两种方式，导入结果统一通过导入历史接口追踪，不再需要的任务可以连同关联短链一并删除。

2.1 POST /api/link/import — Excel 文件导入

通过 multipart/form-data 上传 Excel 文件批量导入短链，文件字段与官方模板一致。唯一的表单字段为 file（必填，binary 类型）。接口返回本次导入的任务 ID，后续可凭它查询导入进度和结果。

curl -X POST 'https://open.xnanlink.com/api/link/import' \
  -H 'Token: YOUR_TOKEN' \
  -F 'file=@links.xlsx'

# 响应
{
  "code": "OK",
  "message": "成功",
  "data": 200001,
  "success": true
}

2.2 POST /api/link/import/json — JSON 入参导入

通过 JSON 请求体批量导入短链，字段与 Excel 模板一致。请求体中的 rows 数组每一项支持以下字段：

domain：域名
visitCode：访问码，可省略由系统生成
sourceLink：原始链接
expireDate：过期时间，可省略

curl -X POST 'https://open.xnanlink.com/api/link/import/json' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "rows": [
      {
        "domain": "lxs.la",
        "visitCode": "code1",
        "sourceLink": "https://www.example.com/1",
        "expireDate": "2026-12-31"
      },
      {
        "domain": "lxs.la",
        "sourceLink": "https://www.example.com/2"
      }
    ]
  }'

两种导入方式如何选择：

Excel 导入：适合运营同学手工整理数据，或从其他系统导出表格后一键上传
JSON 导入：适合程序化对接，由业务系统直接组装数据调用，无需生成中间文件

2.3 POST /api/link/import/list — 导入历史

分页查询批量导入的历史记录，支持按文件名（fileName）和导入状态（importStatus）过滤。返回的每条记录包含：

字段	类型	说明
id	integer (int64)	任务 ID
fileName	string	文件名
totalCount	integer (int32)	总数量
successCount	integer (int32)	成功数量
failCount	integer (int32)	失败数量
importStatus	integer (int32)	导入状态
failDataOssPath	string	失败数据下载路径（OSS）
createdTime	string (date-time)	创建时间

curl -X POST 'https://open.xnanlink.com/api/link/import/list' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "pageNum": 1,
    "pageSize": 20
  }'

# 响应
{
  "code": "OK",
  "message": "成功",
  "data": {
    "pageNum": 1,
    "pageSize": 20,
    "total": 5,
    "list": [{
      "id": 200001,
      "fileName": "links_batch_1.xlsx",
      "totalCount": 500,
      "successCount": 498,
      "failCount": 2,
      "importStatus": 2,
      "createdTime": "2026-01-20T14:00:00"
    }]
  },
  "success": true
}

2.4 POST /api/link/import/delete — 删除导入任务

根据导入任务 ID 删除导入任务，参数 taskId（必填）通过 URL 查询参数传递。

curl -X POST 'https://open.xnanlink.com/api/link/import/delete?taskId=200001' \
  -H 'Token: YOUR_TOKEN'

小贴士

删除导入任务会同时删除该任务关联的所有短链，已发布出去的短链将无法访问。执行前请确认这批短链已不再使用，操作不可恢复。

3. 访问统计

3.1 POST /api/link/visit-log — 查询访问记录

分页查询短链的访问记录，支持按访问码（visitCode）、IP 地址（ip）以及日期范围（dateRange 或 startDate / endDate）过滤。

每条访问记录包含以下字段，可用于分析流量来源与用户画像：

visitTime：访问时间
ip：访问者 IP 地址
geo：地理位置
os：操作系统
deviceType：设备类型
origin：访问来源

curl 请求示例：

curl -X POST 'https://open.xnanlink.com/api/link/visit-log' \
  -H 'Content-Type: application/json' \
  -H 'Token: YOUR_TOKEN' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "visitCode": "abc123",
    "dateRange": 1
  }'

响应示例：

{
  "code": "OK",
  "message": "成功",
  "data": {
    "pageNum": 1,
    "pageSize": 20,
    "total": 358,
    "list": [{
      "visitTime": "2026-01-20T15:30:00",
      "ip": "192.168.1.1",
      "geo": "北京",
      "os": "iOS",
      "deviceType": "iPhone",
      "origin": "直接访问"
    }]
  },
  "success": true
}

4. 基础数据

基础数据接口提供创建、更新短链时需要的下拉选项数据，两者均为 GET 请求，无需请求体。

4.1 GET /api/link/domain/list — 获取域名列表

获取当前可用的域名列表，每一项包含域名（domain）、描述（desc）、SSL 状态（sslFlag，0 否 / 1 是）和是否热门（hot）。

curl -X GET 'https://open.xnanlink.com/api/link/domain/list' \
  -H 'Token: YOUR_TOKEN'

# 响应
{
  "code": "OK",
  "message": "成功",
  "data": [
    { "domain": "lxs.la", "desc": "默认域名", "sslFlag": 1, "hot": true },
    { "domain": "s.la", "desc": "备用域名", "sslFlag": 1, "hot": false }
  ],
  "success": true
}

4.2 GET /api/link/routing/rule — 分流规则下拉

获取分流规则下拉列表，包含「按设备」「按地区」等规则大类及其子规则（如 PC 端 / 移动端、中国大陆 / 海外）。创建或更新短链时，将选中的规则编码填入 rules 参数即可实现按条件分流跳转。

curl -X GET 'https://open.xnanlink.com/api/link/routing/rule' \
  -H 'Token: YOUR_TOKEN'

# 响应
{
  "code": "OK",
  "message": "成功",
  "data": [
    {
      "code": "DEVICE",
      "name": "按设备",
      "children": [
        { "code": "PC", "name": "PC 端" },
        { "code": "MOBILE", "name": "移动端" }
      ]
    },
    {
      "code": "REGION",
      "name": "按地区",
      "children": [
        { "code": "CN", "name": "中国大陆" },
        { "code": "OVERSEAS", "name": "海外" }
      ]
    }
  ],
  "success": true
}

5. 常见问题

导入失败的数据如何获取？

调用 POST /api/link/import/list 查询导入历史，返回记录中的 failDataOssPath 字段即为失败数据的下载路径。下载后可查看每行失败原因，修正后重新导入即可。

访问记录能查多久以前的数据？

访问记录的保留时长与套餐相关。查询时可通过 dateRange 快捷选择日期范围，或用 startDate / endDate 精确指定区间。如需查询更久远的数据，建议定期通过接口拉取并落库归档。

列表查询最大分页容量是多少？

建议 pageSize 控制在 100 以内，常规场景使用 20-50 即可。需要拉取全量数据时，请按 pageNum 逐页遍历，直到已获取条数达到返回的 total，避免单次请求数据量过大导致超时。

6. 下一步

掌握了完整的 API 能力后，你还可以了解更省心的接入方式：

什么是 MCP？用自然语言管理短链——不写代码，在 AI 客户端里对话即可创建、查询短链
MCP 与 API 的区别：如何选择？——对比两种接入方式的适用场景，选出最适合团队的方案