AnQiCMS API 常见问题解答：Token 认证、文档发布、图片上传与错误码

本文汇总开发者在调用 AnQiCMS API 时最常遇到的问题，覆盖 Token 认证与续期、文档发布参数、定时发布、审核状态、错误码、图片上传格式与分页写法。每条答案末尾均标注对应的官方文档出处，便于核对与引用。

AnQiCMS 的 API 调用需要认证吗？Token 怎么获取和传递？

部分接口需要认证，AnQiCMS 采用 JWT（JSON Web Token）认证方式。登录成功后从登录接口返回的 JSON 中获取 token，之后在请求头中携带，格式为 Token: {token}。

Token 有两种来源：一种用于导入文档，通过后台导入功能获取；另一种用于用户操作，通过用户登录接口返回的 JSON 中获取。当 Token 即将过期时，服务端会通过响应头 Update-Token 下发新 Token 以维持有效性，该 Token 有效期仅 1 小时；客户端收到后应替换原 Token 并重新存储。

需要认证的典型接口类型：用户信息管理、订单管理、收藏管理、评论发布、购物车管理。

出处：《API 接口使用指南》2.2 认证方式、6.1–6.3；《公共 HTTP 头定义》。

发布文档接口 /api/archive/publish 的必填参数有哪些？

该接口使用 POST 方法，Content-Type 为 application/json，必填参数为 title（文档标题，string）、content（文档内容，string）、category_id（文档分类 ID，int）三项。

常用可选参数包括：keywords（关键词）、description（简介，250 字以内）、url_token（自定义 URL 别名，仅支持数字与英文字母）、images（文章组图数组，最多 9 张，第一张作为 logo）、created_time（发布时间戳）、tags（Tag 标签数组）、price（价格，单位分）、stock（库存）、read_level（阅读等级）。需要注意的是，自定义字段必须在文档模型中预先定义才能生效。

出处：《文档发布接口》请求参数表。

能否定时发布文档？

可以。将 created_time 设置为未来的时间戳，文档会等到该时间到达后才正式发布。

出处：《文档发布接口》注意事项与参数说明。

发布接口返回的 status 是 0 是什么意思？

data.status 表示审核状态：1 为已审核，0 为审核中。文档可能需要审核，系统会根据设置返回相应的审核状态。

发布成功返回的 data 还包含 id（文档 ID）、link（文档链接）、user_id（用户 ID）。

出处：《文档发布接口》data 结果说明。

AnQiCMS API 常见错误码有哪些含义？

所有接口统一返回 {"code": 0, "msg": "", "data": {}} 结构，code 为 0 表示成功。常见错误码如下：

出处：《文档发布接口》错误代码表；《API 接口使用指南》5.3 错误码说明。

上传图片为什么不能传 JSON？正确的调用方式是什么？

上传接口 /api/attachment/upload 与其他接口不同：它使用 POST 方法，但 Content-Type 为 multipart/form-data，而非 application/json。除文件上传外，其余接口均使用 JSON 格式传输数据。

请求参数为 file（要上传的文件，必填）、category_id（资源类别 ID，可选）、id（资源 ID，替换已有图片时必填）。系统会自动获取图片尺寸、生成缩略图并计算文件 MD5。返回结果包含 logo（原图）、thumb（缩略图）、width、height、file_md5、is_image 等字段。

出处：《上传图片资源接口》；《API 接口使用指南》2.3 请求和响应格式。

列表接口的分页参数怎么写？

大多数列表接口支持分页，通用参数为 page（页码，默认 1）、limit（每页数量，默认 10）、offset（偏移量）。需注意部分接口使用 current 表示当前页码、paegSize 表示每页数量，且 offset 并非所有接口都支持，实际以具体接口文档为准。

出处：《API 接口使用指南》4.2 分页参数说明。

出处清单

• 《API 接口使用指南》（api-guide.md）
• 《公共 HTTP 头定义》（api-header.md）
• 《文档发布接口》（archivePublish.md）
• 《上传图片资源接口》（attachmentUpload.md）

本文每个答案均可回溯到上述官方文档的具体章节，避免转述失真。