单点登录(SSO)子账户接口
接口介绍
使用该接口，可以通过单点登录（SSO）的方式创建子账户，创建成功之后可以通过此接口登录子账户。
使用此接口创建的用户，属于主账户下属的子账户，权益同主账户同步。除创建和登录方式不同外，其他权益、设置同手动创建的子账户完全一致。
接入前准备
1. 使用主账户登录 SurveyMars，在 「我的账户」 页面查看 appId（账户 ID）。
2. 联系客服为您开通并下发 Secret Key（密钥）。该密钥仅用于在服务端计算签名 sign，切勿拼入 URL 明文传输或暴露在前端代码中。
3. 确认您的系统能在服务端生成符合规范的 SHA256 签名字符串，并能在用户浏览器或可信任环境中发起 GET 请求打开登录链接。
接口参数说明
请求方式：GET
| 参数名 | 参数说明 | 是否必须 |
| appId | 公司 ID。主账号登录后在 「我的账户」 页面查看，页面中的账户 ID 即为接入所需的 appId。Query 中参数名须为 appId（大小写与文档保持一致）。 | 是 |
| Secret Key | 开发密钥，需联系客服生成，生成后可在 「我的账户」 页面查看；仅用于在服务端计算 sign。 | 否 |
| ts | 时间戳，从 1970-01-01 00:00:00（UTC）起至当前的 秒数。有效期为 60 秒。 | 是 |
| sign | 加密签名。sign 为对拼接后的明文字符串做 SHA256 得到的十六进制小写字符串，作为查询参数 sign。请求中带 roleId 时，明文为 appId + email + userName + roleId + ts + Secret Key；未传 roleId（非必填省略）时，明文须不含 roleId 段，为 appId + email + userName + ts + Secret Key。拼接顺序与类型须严格一致；Secret Key 只参与服务端拼接，不出现在浏览器地址栏。详见下文「签名计算规则」。 补充：查询参数 isOnlyLogin 与 language、returnUrl 相同，不参与上述签名字符串拼接。当 isOnlyLogin=true 且请求中不传 userName 时，计算 sign 时 userName 段按空字符串参与拼接（顺序不变：仍为 appId + email +（此处 userName 为空）+ roleId（若传）+ ts + Secret Key）。 如需在线计算 SHA256 以核对拼接是否正确，可将得到的明文字符串粘贴到第三方工具（例如 LZL 在线 SHA256 哈希）中生成。正式环境仍建议在服务端代码中生成 sign，勿将 Secret Key 暴露给浏览器。 |
是 |
| 创建子账户绑定的邮箱，请使用 绝对唯一 的字段；不可为空。 | 是 | |
| userName | 创建子账户的用户名（显示名），长度不超过 150 个字符；不可为空。若含空格、中文或特殊字符，须对参数值做 URL 编码（如空格使用 %20）。 补充：当 isOnlyLogin=true 时，userName 为非必填（仅登录、不创建子账号，详见 isOnlyLogin）。当 isOnlyLogin=false 或未传 isOnlyLogin（默认按 false 处理）时，userName 必填。 |
条件必填 |
| isOnlyLogin | 是否仅登录已有子账号、不创建子账号。取值 true / false（建议小写）；不传时默认 false。该参数不参与 sign 的 SHA256 拼接。 true：仅校验并登录该 email 下已存在的子账号，不会创建新子账号；userName 非必填。若子账号不存在，系统将提示用户不存在（具体文案随界面语言变化）。 false 或未传：userName 必填；若该邮箱对应子账号已存在则直接登录，不存在则创建子账号并登录（创建时仍适用 roleId 等既有规则）。 |
否 |
| roleId | 创建子账户的角色，可选；不传或留空时默认为「问卷管理员」。子账户角色：1-系统管理员，2-问卷管理员，3-统计结果查看员，4-完整结果查看员，6-问卷编辑协作员。请勿传入未列出的数字，否则返回错误信息。 | 否 |
| returnUrl | 指定登录成功后的跳转地址（建议使用相对路径，如 /usercenter、/survey/list）。不传时默认跳转到「我的问卷」页面；建议对路径做 URL 编码，移动端等场景亦应能正确落地。 | 否 |
| language | 界面语言，传入整数。可选；不传时使用系统默认语言。该参数不参与上文 sign 的 SHA256 拼接计算。 取值对照： 1—简体中文（zh） 2—英语（en） 3—繁体中文（tw） 4—日语（ja） 5—韩语（ko） 6—阿拉伯语（ar） 7—法语（fr） 8—德语（de） 9—西班牙语（es） 10—葡萄牙语（pt） 11—意大利语（it） 12—俄语（ru） 13—泰语（th） 14—土耳其语（tr） 15—印尼语（id） 16—越南语（vi） 17—波兰语（pl） 18—荷兰语（nl） 22—希伯来语（he） 23—瑞典语（sv） 27—丹麦语（da） 28—芬兰语（fi） 30—马来语（ms） 31—挪威语（nb） 50—冰岛语（is） |
否 |
签名计算规则
1. 将参与签名的字段按固定顺序直接首尾拼接为一条字符串（中间无分隔符）。当请求中传递了非必填参数 roleId 时，顺序为：appId + email + userName + roleId + ts + Secret Key。当 roleId 未传（留空或不带该参数）时，签名字符串中须完全省略 roleId 这一段，顺序为：appId + email + userName + ts + Secret Key，不可用占位数字或空字符串代替 roleId。补充：当 isOnlyLogin=true 且 URL 中不传 userName 时，上述 userName 位置按空字符串拼接后再计算 sign；isOnlyLogin 本身不参与拼接。
2. 对该字符串做 SHA256，取十六进制小写字符串作为参数 sign 的值。
3. 查询参数中的 language、returnUrl、isOnlyLogin 等若存在，均不参与上述签名字符串拼接；仅按第 1 步所列字段顺序计算。
首次创建与再次登录
email、roleId、userName 仅在子账户 首次创建 时写入系统。若该 email 对应子账户已存在，后续登录请求 不会 校验本次传入的 roleId、userName 是否与历史一致，也 不会 用新传入值修改已有资料；若签名或必填参数有误，仍可能返回验签失败或参数错误。
补充（isOnlyLogin 与登录 / 创建）：当 isOnlyLogin=false 或未传时：若 email 已有子账号则登录，若无则创建子账号并登录（userName 等在首次创建时写入）。当 isOnlyLogin=true 时：仅允许登录已有子账号，不创建；子账号不存在时提示用户不存在。
常见问题
问：为什么提示验签失败或参数错误？
答：请核对 Secret Key 是否正确：若请求中带了 roleId，拼接顺序须为 appId、email、userName、roleId（整数）、ts、Secret Key；若未传 roleId，签名字符串中须省略 roleId 段，顺序为 appId、email、userName、ts、Secret Key。isOnlyLogin=true 且未传 userName 时，签名字符串中 userName 按空串拼接。同时确认 ts 仍在有效期内，且 URL 编码未改变用于拼接的原始值。缺少 appId 或邮箱为空会触发参数类错误；isOnlyLogin=false（或未传）时用户名为空也会触发参数类错误。
问：子账户已是问卷管理员，为何传入错误的 roleId 仍能登录？
答：当该 email 对应子账户已存在时，系统不会用本次请求的 roleId、userName 去校验或更新已有资料；这些字段主要影响首次创建。首次创建时仍须传入合法 roleId 或留空以使用默认角色。
问：ts 为何很快就过期？
答：生产环境要求时间戳与服务器时间相差在 60 秒 内，请在用户即将跳转前实时生成 ts 与 sign。
问：userName 含空格或中文时接口异常怎么办？
答：请对查询参数做标准 URL 编码（空格编码为 %20 等）。未编码时部分 HTTP 客户端会截断或解析错误，表现为请求失败，并非服务端拒绝正常字符。
问：isOnlyLogin=true 与 false 有什么区别？提示用户不存在是什么原因？
答：isOnlyLogin=true 表示只登录、不创建子账号，userName 可不传；若该 email 在贵司主账号下尚无子账号，系统会提示用户不存在。isOnlyLogin=false 或未传时，userName 必填；邮箱已有子账号则登录，没有则创建。
问：如何在 SurveyMars 侧删除 SSO 创建的子账户？
答：需主账户登录后，在 「子账号」 页面手动删除。贵司业务系统中删除员工不会自动删除 SurveyMars 子账户，请自行保持两边数据策略一致。
