用途
该技能用于在 HubSpot 2027 年 3 月 30 日旧版 API 支持终止前，盘点调用 HubSpot API 的集成、私有应用和内部工具，并标记仍在使用 v1-v4 旧版端点或旧版 OAuth v1 的调用方，最终产出迁移清单。
背景
2026 年 3 月，HubSpot 用基于日期的版本（如 /2026-03/ 路径，每年两次发布，每次支持 18 个月）取代了语义化 API 版本（v1-v4）。所有仍调用 v1-v4 端点（包括旧版 OAuth v1）的调用方将在 2027 年 3 月 30 日变为不受支持。不受支持的 API“不再接收更新、错误修复或稳定性保证”，未迁移的市场应用可能失去认证。一个门户通常有比任何人记得的更多调用方——私有应用、市场应用、中间件（Zapier/Make）、表单嵌入、内部脚本、数据仓库同步。
关键事实
- 当前推荐版本：2026-03
- 发布节奏：每年 3 月和 9 月
- 支持生命周期：当前（6 个月）→ 受支持（至 18 个月）→ 不受支持
- v1–v4 支持终止：2027 年 3 月 30 日
- 同时弃用：旧版 v1 OAuth API（令牌签发/内省）
前提条件
- 超级管理员访问权限（查看集成设置和私有应用日志）
- 可选：私有应用令牌（.env 中的 HUBSPOT_ACCESS_TOKEN）用于账户级用量查询
- 访问任何内部集成的源代码
执行模式
阶段 1：计划
与用户确认：哪些系统已知会接触 HubSpot（CRM 同步、网站表单、分析管道、内部脚本），以及每个系统的负责人。
阶段 2：之前——建立调用方清单
逐一检查每个发现来源，并在清单中记录每个调用方（负责人、功能、使用的端点/版本）：
- 私有应用：设置 > 集成 > 私有应用。打开每个应用 > 日志——API 调用日志显示确切的请求路径（/crm/v3/...、/contacts/v1/...），从而揭示使用的版本。
- 已连接/市场应用：设置 > 集成 > 已连接应用。无法查看其内部；记录每个供应商——认证应用正被 HubSpot 推动迁移，但业务关键的应用需与供应商确认。
- 内部代码库：搜索揭示版本的模式：
grep -rEn "api\.hubapi\.com/[a-z-]+/v[0-9]|/contacts/v1|/email/public/v1|hubapi.com/automation/v[23]" .
- 中间件（Zapier、Make、Workato、n8n）：平台管理的连接器按供应商计划迁移；其中的自定义 HTTP 步骤不会——需手动检查。
- 账户级 API 用量（可选脚本检查）：账户信息 API 报告私有应用的每日 API 用量总计：
resp = requests.get(f"{BASE}/account-info/v3/api-usage/daily", headers=HEADERS)
这确认了多少流量，而非哪些版本——使用步骤 1 的每应用日志获取版本详情。
阶段 3：执行——分类和规划迁移
对每个调用方分类：
- 红色：调用 v1/v2 旧版端点（如 /contacts/v1/、/email/public/v1/、表单 v2）或旧版 OAuth v1。操作：立即迁移——其中许多已有更早的日落日期。
- 黄色：调用 v3/v4 端点。操作：在 2027-03-30 前有效；安排迁移到 2026-03 日期路径。
- 绿色：调用日期路径，或供应商管理并确认正在迁移。操作：监控。
对于黄色/红色的内部代码，迁移通常是机械性的——相同资源，新路径前缀和（有时）重命名字段；查阅 HubSpot 文档中端点的迁移说明。按代码库而非按端点批量处理。
此仓库自身的脚本按设计为黄色：它们针对 /crm/v3/ 和 /automation/v4/，支持至 2027 年 3 月，迁移路径记录在 CONTRIBUTING.md 中。
阶段 4：之后
- 清单中的每个调用方都有状态和负责人。
- 红色项有带日期的迁移工单；黄色项安排在 2027-03 之前。
- 每 6 个月重新运行此审计——每个 3 月/9 月发布都会启动新的支持时钟。
回滚
只读——无需回滚。
技术注意事项
- 私有应用日志是事实来源。代码搜索会遗漏动态构建的 URL；设置中的每应用请求日志显示实际调用的内容。
- 404 vs 403 vs 不受支持。支持终止后，端点可能继续工作一段时间——“不受支持”意味着没有修复或保证，而非立即关闭。不要将“它仍然工作”视为“我们没问题”。
- OAuth 是其中一部分。使用旧版 v1 OAuth 令牌端点的应用必须迁移到基于日期的 OAuth API，即使其数据端点是当前的。
- SDK 版本固定 API 版本。如果集成使用官方 HubSpot SDK，SDK 的主版本决定它调用哪个 API 版本——检查 SDK 变更日志，而不仅仅是你的代码。