單點登入 (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 子帳號，請自行維持兩邊資料策略一致。
