合作方 API 接入规格清单

我见过的每一场翻车的合作方 API 接入，都有同一个前兆：平台团队只为 happy path 写了规格，其他情况全靠挥手糊弄。下面这份清单，是我现在要求第三方触碰生产流量之前必须先过的关，全部站在平台这一侧的契约视角来写。

发布于 2026-03-09 · ✓ 已更新 2026-05-06 · 阅读约 7 分钟 · 作者：Spec Coding 编辑部 · 审校：编辑与事实核查政策

Sandbox 访问是第一道门，不是锦上添花

合作方拿到的第一样东西是 sandbox，而这个 sandbox 必须是有分量的。我见过团队耸耸肩就把生产凭据交出去，理由是"sandbox 对齐还在 roadmap 上"。这种做法的直接后果，就是某个 fintech 合作方凌晨两点把一份真实卡号的 CSV 喂进来做集成测试。

规格必须承诺的是：隔离的凭据，绝对摸不到生产数据库；一份播种好的数据集，结构上和生产一致，但值完全和生产无关；前两周不设任何速率限制。合作方应当能够随意压测 sandbox，而不必开一张工单。如果 sandbox 一上来就激进限流，你就是在教他们在还没看过真实错误码之前，先去写一堆脆弱的重试逻辑。

凭据是"生命周期"，不是"一次下发"

把 API key 交出去是最容易的那一步。规格必须写清楚接下来会发生什么：

• 初次下发按环境和合作方联系人分别作用域化，绝不允许在多人之间共享。
• 轮换周期默认 90 天，第 60 天和第 80 天发出自动提醒，第 90 天强制轮换。
• 吊销路径在我们这一侧是一个单独的 endpoint，能在 60 秒内让 key 失效，文档里连同出问题时该拨的电话号码一起写上。
• 单 key 速率独立计量，这样一把被泄露的 key 不会把合作方正常流量挤死。

如果合作方在第一天就答不上来他们那边谁负责轮换，停下来。这是第一面红旗。

数据共享协议必须签，不是发邮件

这一块是大多数平台团队当成"法务的事"，然后自己去收拾烂摊子的部分。规格要以书面方式回答这些问题：合作方允许存哪些字段、能保留多久、下线时必须删除什么、我们是否拥有审计权来验证删除是否执行。欧盟合作方要加 DPA。涉及支付的要加 PCI 范围条款。涉及健康数据的要按各司法辖区要求补齐。

实际的检验方法是：如果合作方明天出了一次数据泄露，你能否向监管机构准确说出哪些用户的哪些数据被暴露？如果答案是"得问他们一下"，那这份协议就没写完。

速率计划要描述"背压"，不只是"上限"

一个"每天 1000 次请求"的免费档位根本不是速率计划，那只是一根减速带。规格应该描述四件清清楚楚的事：持续上限、突发容忍度（超过上限多少、能撑多久）、每一档承诺的 SLA，以及合作方超限时的背压策略。我们是返回 429 并带 Retry-After？是排队？还是退化到陈旧缓存？三选一、写进文档，而不是等合作方在他们自己的黑五大促里去发现。

合作方必须过的上线准入门槛

生产访问权限是"挣来"的，不是"申请就给"的。我的清单：

• 在他们计划用于生产的 endpoint 上，至少跑完 10,000 次成功的 sandbox 请求。
• 他们那一侧的负载测试结果，证明能在我们文档化的速率上限下稳定运行。
• 指定一位一小时内可达的生产支持联系人，并配一位 backup。
• 书面确认我们稳定的错误分类法，以及他们会在哪些 code 上重试。
• 他们那一侧针对三种最可能故障模式（认证、限流、上游超时）的 runbook。

错误响应契约就是集成本身

合作方会在你返回的错误码之上构建重试逻辑、告警和面向用户的错误文案。这份契约必须在各版本之间保持稳定。挑一小组合作方可以依赖的 code：AUTH_INVALID、RATE_LIMITED、RESOURCE_NOT_FOUND、UPSTREAM_TIMEOUT、VALIDATION_FAILED、INTERNAL_ERROR。其余信息性内容都可能变。把这写进规格，改动当作 breaking change 来管。那些学会基于错误文案而不是错误码来分支的合作方，是你自己造出来的麻烦。

事故沟通机制要"先于"需要就位

平台一出事故，合作方就立刻看出你到底成熟到哪个地步。规格必须承诺的是：自动订阅的 status page；一份他们能看懂的严重性分级（SEV1 意味着他们的用户无法交易，SEV2 意味着体验降级，SEV3 仅对内部影响）；以及一个你真正在度量的平均通知时延。我给 SEV1 定 15 分钟、SEV2 定 60 分钟。如果你达不到这个数，就把真实数字写进规格，别再自欺欺人。

平台侧的每合作方监控

不要指望合作方主动告诉你他们坏了。签约当天就把 dashboard 立起来，每个合作方盯三个信号：错误率、p95 延迟、流量形状异常。最后那一条能抓到最有意思的故障——某个合作方凌晨 3 点流量突然翻三倍，要么是他们生意爆棚，要么是重试循环失控了。不管哪种，你都想在他们之前先看到。

接入规格本身的验收标准

- Given a new partner has completed the data-sharing agreement and received sandbox credentials
  When they submit production access request with load test evidence
  Then the platform confirms rate plan, error taxonomy acknowledgement, incident contacts, and offboarding terms before issuing production keys

- Given a partner in production for 30+ days
  When anomaly detection flags unusual traffic shape or error rate
  Then the on-call engineer receives a notification with partner context and the documented escalation contact within 15 minutes

具体案例：接入一个 fintech 合作方

最近的一次项目是这么走完的。一家支付合作方想集成我们的账本 API。第 1 天他们拿到 sandbox 密钥、看起来像真实商户交易但没有任何真实引用的种子数据，以及一个共享的 Slack 频道。第 4 天他们申请生产密钥。我们拒了：他们的负载测试是一条单线程发了 50 个请求。我们要求按我们文档化的 burst 上限再加 20% 余量做并发测试。

第 9 天他们带着像样的结果、一份指定的 on-call 轮值表和一份 runbook 回来。我们下发了生产密钥，首周把流量放到 5%。我们盯着 dashboard，第 11 天发现一个流量形状异常（在他们本不该重试的 502 上触发了一次重试风暴），标出来，他们修掉。第二周把上限解除。总耗时：14 天。接入引发的事故：零。对比上一年我们赶进度接入的那个合作方，上线当天把我们的 status endpoint 打掉了 40 分钟。门槛本身就是意义所在。

几乎没人写的下线条款

这一段是我接手过的每一份规格都缺的内容。趁现在写下来，别等真要用的时候。任意一方提前 30 天书面通知。通知发出后 7 天内，以文档化格式提供一次数据导出。终止后 24 小时内，吊销所有 key。终止后 30 天内，残留数据删除以书面形式确认，如果我们要求则行使审计权。合规签署（SOC2 证据、适用时的 PCI 证明）按监管留存时限保留。

如果这份清单你只带走一段，就带这一段。合作方是会离开的，从进来那一刻就要为此做打算。

最后一句话

合作方接入不是一次握手加一封凭据邮件。它是一份规格，而这份规格对 sandbox、速率计划、错误契约、监控和下线的明确程度，必须不亚于你内部服务规格对其他任何事情的明确程度。愿意尊重一套严谨接入流程的合作方，才是你想要的合作方。对这些门槛推来推去的，恰好是在提前告诉你：他们的集成在生产环境会是什么表现。

把 onboarding 写成准入门，而不是欢迎邮件

合作方 API onboarding 最常见的问题是大家都以为“对接完成”了，但没人知道 sandbox、限流、签名、监控和联系人是否齐全。规格里要有一张 go-live gate，少一项就不上线。

Partner go-live gate:
- sandbox credentials issued and rotated once
- webhook signature verified against replay fixture
- rate limit tested at 80% and 120%
- support contact and escalation channel recorded
- production allowlist approved by security
- rollback: disable partner key without touching other tenants

边界：不要把销售承诺写成技术可用。合作方还没提供稳定测试环境、错误码文档或值班联系人时，工程状态只能是 blocked。

生产前要跑一次撤销演练

合作方上线前，我会要求撤销演练：禁用 partner key、撤下 allowlist、停止 webhook、确认其他租户不受影响。这个回滚测试比欢迎邮件重要得多，因为真正出问题时，第一步往往是把合作方安全地隔离出去。

可复制产物：契约评审包

当工作涉及 API 行为、schema、事件、重试或消费者预期时使用。它会把兼容性和发布证据提前摊开。

API 契约评审包：合作方 API 接入规格清单

本次要做的决策：
- 确认契约变化是否兼容，消费者需要什么迁移动作，发布后如何观察风险。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

契约边界：没有兼容性分类、消费者影响、重试行为和回滚说明，不进入发布。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。