SaaS 开放 API：早期别急着全开放，先定义高价值边界

开场：客户说要 API，不代表你应该立刻开放所有东西

早期 SaaS 很快会遇到客户问：“你们有没有 API？”这句话听起来像成熟产品的标志，于是团队开始设计开放平台、文档、密钥、Webhook 和各种接口。

但 API 一旦开放，就会形成长期承诺。接口改动、权限漏洞、数据一致性、客户调试和兼容维护，都会变成真实成本。

早期不是不能开放 API，而是要先弄清：客户到底要通过 API 完成什么业务动作。

先拆 API 需求背后的场景

不要只记录“客户要 API”。要追问：

• 是要把数据导入你的系统，还是从你的系统导出？
• 是实时同步，还是每天一次即可？
• 是由客户技术团队开发，还是第三方服务商开发？
• 接入后会影响哪个关键流程？
• 没有 API 时，客户现在怎么解决？
• 这个需求会影响成交、留存还是扩展？

API 是手段，不是需求本身。

如果客户只是想减少一次 Excel 上传，可能先做批量导入更合适。如果客户需要订单状态实时回传，Webhook 可能比完整 API 更有价值。

先开放高价值对象

早期不要把所有数据模型都开放。先找最常被系统外部使用的核心对象。

例如：

开放对象越少，边界越清楚，支持成本越低。

写清 API 不支持什么

API 文档不能只写支持项，也要写不支持项。

例如：

• 不支持跨租户访问。
• 不支持绕过权限创建管理员。
• 不支持直接删除历史审计记录。
• 不保证无限频率调用。
• 不支持通过 API 修改账单套餐。
• 不承诺所有后台功能都有对应接口。

这些边界能减少客户误用，也保护你的产品结构。

权限和审计必须优先

API 不是普通按钮。一个错误脚本可以在几秒钟内改掉大量数据。

最小安全要求包括：

• 每个 API key 绑定租户。
• API key 可停用和轮换。
• 区分读权限和写权限。
• 关键写操作记录操作者、时间和来源。
• 对批量写入设置限制。
• 错误响应不要暴露敏感信息。

早期可以少开放接口，但不能用一个全能密钥解决所有问题。

用客户集成包降低支持成本

如果 API 面向非专业客户，文档再完整也可能带来大量支持问题。

可以准备一个集成包：

• 认证说明。
• 常见对象字段表。
• 示例请求和响应。
• 错误码说明。
• 测试环境或测试租户。
• 调用频率限制。
• 上线前检查清单。

这比只给一个接口地址更可靠。

判断 API 是否值得做

用这张表判断优先级：

如果只有一个客户临时提出，而且场景不清晰，不要急着做成公共 API。

常见误区

第一个误区，是把开放 API 当成熟标志。成熟不是接口多，而是边界稳定。

第二个误区，是为单个大客户做一套不可复用接口。短期成交可能换来长期维护负担。

第三个误区，是忽略权限。API 权限错误比页面权限错误影响更大。

第四个误区，是没有版本策略。哪怕早期只支持一个版本，也要避免随意破坏客户集成。

从 0 做 SaaS，API 应该服务高价值工作流，而不是为了显得平台化。先开放少数稳定对象，把权限和审计做好，再逐步扩展。