概述

接口地址

环境	基础地址
开发环境	http://dev-api.ailian.com
测试环境	http://test-api.ailian.com
生产环境	https://api.ailian.com

所有开放接口路径前缀为 /api/open/v1/。

通信协议

• 协议：HTTP / HTTPS
• 方法：GET / POST / PUT
• 数据格式：JSON
• 字符编码：UTF-8

接入流程

1. 联系平台管理员，申请接入 → 获取 app_key + app_secret
2. 根据本文档完成签名逻辑开发
3. 在测试环境联调
4. 联调通过后，申请生产环境密钥

接口版本策略

• URL 路径中的 /v1/ 已预留版本空间，后续不兼容变更时升版（如 /v2/）
• 新增字段不升版本，旧版本至少保留 6 个月过渡期
• 删除或变更已有字段时才升版本，并通过响应头 X-API-Deprecated: true + X-API-Sunset: <date> 提前通知
• 建议调用方在解析响应时忽略未知字段，保持向前兼容

不兼容变更（Breaking Changes）

嘉宾收入字段金额化（2026-08）

本次变更将嘉宾收入相关字段从「档位字符串」升级为「金额（元）」权威模型，涉及以下不兼容点：

变更项	旧行为	新行为
income_level 枚举	4 档：10万以下 / 10-20万 / 20-50万 / 50万以上	6 档：10万以下 / 10-20万 / 20-30万 / 30-50万 / 50-100万 / 100万以上
新增 income_amount	无	本人年收入金额（元），权威字段；income_level 由它反推，二者恒一致
新增 family_income_amount	无	家庭年收入金额（元），为空时等于 income_amount
新增 family_income_level	无	家庭年收入等级（6 档枚举），为空时等于 income_level
新增 req_income_amount	无	择偶收入要求下界（元），权威字段
新增 req_income_text	无	择偶收入要求原文
删除 req_income	字符串收入要求	已删除，改用 req_income_amount + req_income_text

旧值兼容映射（存量调用方仍传入旧 4 档值时自动就近归入新档）：

旧 income_level 值	新档
20-50万	20-30万
50万以上	50-100万

迁移建议：

1. 写入侧优先传 income_amount（元），income_level 可省略；
2. 若仍传 income_level，请改用 6 档枚举；旧 4 档值虽仍被兼容，但建议尽快切换；
3. 择偶收入要求改用 req_income_amount（元），或传 req_income_text 由平台自动解析回填金额。

---

请求体大小限制

接口类型	请求体上限
普通接口	1 MB
批量接口	5 MB

超限返回 HTTP 413 {"code": 41301, "message": "请求体过大"}。