FAQ

Q: 如何申请接入？ A: 联系平台管理员，提供系统名称、用途说明、预计调用量，管理员会分配 app_key 和 app_secret。

Q: 签名一直失败怎么排查？ A: 参见「9.1 签名调试」。最常见原因是：body_md5 计算不一致、app_secret 错误、sorted_query 未参与签名。

Q: 可以批量创建嘉宾吗？ A: 可以，使用 POST /api/open/v1/guests/batch 批量接口，每次最多 50 条。

Q: 如何通过嘉宾卡片图片创建嘉宾？ A: 有两种方式：

1. 同步解析：调用 POST /api/open/v1/guests/parse-card 获取解析结果，确认后再调用 POST /api/open/v1/guests 创建嘉宾
2. 异步创建：调用 POST /api/open/v1/guests/create-from-card 直接异步创建，通过 Webhook 或 GET /api/open/v1/guests/card-task/{task_id} 查询结果

解析失败（无法识别姓名/性别）时不会创建嘉宾记录。

Q: 择偶要求字段如何使用？ A: 择偶要求支持两种格式：

1. 文本描述：requirement 字段，自由文本，最长 500 字
2. 结构化标签：requirement_tags 字段，JSON 对象，包含 age_min、age_max、height_min、education_min、locations 等 16 个字段

传入 requirement_tags 后，系统会自动同步到对应的预计算列（如 req_age_min），用于匹配引擎的 SQL 硬过滤。

Q: 返回的数据是脱敏的吗？ A: 开放接口默认返回完整数据（不脱敏）。如果你的客户端被单独配置了脱敏，敏感字段会显示为 ***。

Q: 密钥泄露了怎么办？ A: 立即联系管理员禁用当前 app_key。管理员可以重置密钥，支持不中断服务的平滑轮换（新旧密钥并行过渡 7 天）。

Q: 接口会变更吗？ A: 新增字段不升版本，删除或变更字段时才升版本（如 /v2/）。旧版本至少保留 6 个月过渡期。建议解析响应时忽略未知字段。

Q: 如何实时接收数据变更通知？ A: 联系管理员开通 Webhook 推送，配置回调地址和订阅事件类型。详见第六章。