SDK
API 变更通知
破坏性变更预告、废弃方法说明及迁移指南，帮助您提前规划升级
变更策略
翠鸟 API 遵循以下变更原则，确保您的集成稳定可靠：
- 废弃期（Deprecation Period）：在破坏性变更正式生效前，至少提前 6个月 发出废弃通知
- 通知渠道：开发者邮件列表、控制台公告、API 响应头
Deprecation字段 - API 版本：当前稳定版为
v1，主版本号变更时旧版本将继续支持至少12个月 - 向后兼容：在同一主版本内，我们承诺不移除或修改已有字段，只新增字段
订阅翠鸟开发者邮件列表（控制台 — 账号设置 — 通知偏好）可第一时间收到变更通知。
待生效的破坏性变更
BREAKING
线索评分字段重命名：
score → engagement_score
生效日期：2024-09-01
为统一命名规范，线索对象中的 score 字段将重命名为 engagement_score。过渡期间两个字段同时存在，2024-09-01 起 score 字段将从响应中移除。
// 迁移前
{ "score": 72 }
// 迁移后
{ "engagement_score": 72 }
影响范围：所有读取 Lead 对象 score 字段的代码；Java SDK v3.x 的 Lead.getScore() 方法。
迁移步骤：将所有 .score 字段访问改为 .engagement_score；SDK 升级至 v3.2.0+ 后使用 Lead.getEngagementScore()。
BREAKING
分析端点路径调整：
/v1/stats/* 迁移至 /v1/analytics/*
生效日期：2024-10-15
早期版本的 /v1/stats/* 端点将被完全移除，请迁移至功能更完善的 /v1/analytics/* 端点。新端点提供更丰富的过滤选项和更精确的数据粒度。
迁移映射：
GET /v1/stats/overview→GET /v1/analytics/overviewGET /v1/stats/resources→GET /v1/analytics/resourcesGET /v1/stats/leads→GET /v1/analytics/leads
已废弃的方法（待移除）
DEPRECATED
SDK：
ResourceClient.upload(File) 方法
移除日期：2024-07-01
原 ResourceClient.upload(File file) 方法不支持进度回调和大文件分片上传，请迁移至新方法。
// 废弃用法
client.resources().upload(new File("report.pdf"));
// 推荐用法（支持进度回调）
client.resources().upload(
UploadRequest.builder()
.file(new File("report.pdf"))
.title("产品白皮书2024")
.onProgress(pct -> System.out.println("上传进度: " + pct + "%"))
.build()
);
DEPRECATED
Webhook 事件字段：
data.object 层级将被展平
移除日期：2024-08-01
当前 Webhook payload 中业务数据嵌套在 data.object 下，未来将展平至 data 层级，减少解析嵌套。
// 当前结构（废弃）
{ "event": "lead.created", "data": { "object": { "id": "lead_xxx", ... }}}
// 新结构
{ "event": "lead.created", "data": { "id": "lead_xxx", ... }}
历史已移除内容
以下内容已在历史版本中完成移除，仅供参考：
- 2023-11-05（v3.0.0）：移除包名
com.kingfisher.api.*，已迁移至com.cuiniao.sdk.* - 2023-11-05（v3.0.0）：移除
ApiClient类，由CuiniaoClient替代 - 2023-08-01：移除 API v0 所有端点，最低版本要求提升至 v1