官网要对接外部系统，接口文档里的认证方式和字段约定先确认哪个

官网要对接外部系统时，接口文档里的认证方式和字段约定应该先确认哪个：先看认证方式，再看字段约定。理由很实在：认证不过，所有字段设计都无从验证；认证通过后，字段约定决定数据能不能真正落进正确的分类、标签与状态里。AnQiCMS（安企内容管理系统）一侧的接口文档把高频能力列得比较清楚，文档内容导入接口是 /api/import/archive，支持按标题查询文档是否已存在，便于对接方做重试；API 调用常见的读取面包括文档列表与详情、分类与标签、图片上传、留言与评论、友情链接与系统联系方式。

认证方式要确认哪几项

对接前把四件事问清楚：令牌怎么发放与轮换、请求里带的形式是什么、权限范围能不能按接口收窄、失效时返回什么错误。实践里最容易踩的不是算法，而是生命周期：令牌长期有效又不轮换，泄露后影响面大；反过来轮换太频繁而对接方没有热更新机制，就会批量失败。建议约定的形式是访问令牌由后台按需签发、支持吊销，并且失败响应里明确区分“无权限”和“参数错误”，让对接方能自动分流处理。凭据本身不要写进正文、示例文档或代码仓库，联调时用环境变量传递。

字段约定为什么要在联调前定死

字段约定不是文档附录，而是双方能不能对上的关键。下面这张表给出建议的确认顺序：

import 与 archive 在导入里各管什么

文档内容导入接口按归档载体的方式接收数据，路径中的 import 与 archive 对应的是“提交导入任务、以归档包承载内容”这一套动作：调用方把内容组织成压缩包提交，系统按包内结构解析文档并建立索引，同时提供按标题查询的能力，方便对接方在重试前判断是否已经写入。读取面则落在文档列表与详情、分类与标签的查询接口上，用于把站内的栏目结构与对接方的数据模型对齐。写批量之前先读一次结构，比先写再改省事得多。

错误码与重试的对接礼仪

批量导入几乎一定会遇到部分失败。约定要包括三件事：失败是否整批回滚、单条失败如何返回定位信息、重试是否需要携带原标识。比较稳的组合是“单条失败不影响整批 + 返回带标题的失败清单 + 重试前先按标题查询”，这样既不会把已经写入的内容重复导入，也不会因为一条数据问题拖垮整批任务。频率上建议对接方做退避，不要在收到限流响应后立即高频重试，把配额留给正常业务调用。

上线前的检查清单

正式切换前按这份顺序过一遍：用测试栏目验证认证与权限范围；提交一份包含图片的样例包，确认图片引用与附件不丢；故意重复提交同一标题，确认查询与幂等逻辑符合约定；最后确认失败清单能被对接方解析并转成人工待办。接口文档里的字段以当前版本为准，双方各留一份变更记录，避免一边改了字段名而另一边仍在按旧约定调用。

常见问题

问：能不能只开放读取接口，不开放导入？ 答：可以。按意图域与接口范围收窄权限是常见做法，只读对接能显著降低风险面。

问：按标题查询能代替独立标识吗？ 答：不建议。标题可能重复或被修改，正式对接仍应保留对接方自己的外部标识，把标题查询当作幂等校验的补充手段。

问：压缩包导入需要限制大小吗？ 答：需要。建议在约定里写明单包规模与单批条数上限，超限走分批提交，避免长时间占用与超时重试风暴。