建立客戶總部
⚠️ 新增群組後,總部客戶的 Boss 角色使用者就看得到所有成員(子客戶)的資料。 請確認成員清單無誤再送出。
建立一個客戶總部,成功回傳 201 與新群組的 id。總部客戶本身也會成為這個群組的成員。
name 必填,去掉前後空白後 1 至 50 字元。總部以 parentCompanyId 或 parentCompanyCode(客戶的 outerSysCode)指定,至少要給一個,兩者都給時以 parentCompanyId 為準。子客戶以 subCompanyIds 和/或 subCompanyCodes 指定,兩者取聯集;重複的值、小於等於 0 的 id、與總部相同的 id 與空白的代碼會被略過。
代碼是大小寫敏感的完全比對,範圍限呼叫端所屬租戶的有效客戶:對不到任何客戶回傳 400 company_not_found,對到兩家以上回傳 400 company_code_ambiguous,OrderUp 絕不會替你挑一家。為避免被用來探測其他租戶的客戶序號,錯誤不會指出是哪一個 id 或代碼有問題。
任何一項規則不符就整筆拒絕、不寫入任何資料。依序檢查:名稱必填(name_required)且不超過 50 字元(name_too_long);總部必須指定(parent_company_required);總部與子客戶必須是有效客戶(company_not_found、company_code_ambiguous);總部不可已是另一個群組的總部(parent_already_headquarters);總部與子客戶都不可已屬於另一個群組(company_already_in_group);子客戶不可是另一個群組的總部(sub_company_is_headquarters)。
同一租戶的群組寫入請一次送一筆。資料庫只保證「同一個總部只能有一個群組」,兩個同時送出的請求可能把同一家子客戶分別加進兩個群組。也不要與該租戶的客戶寫入(POST/PUT /v1/companies、批次)同時進行。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
群組名稱,必填。去掉前後空白後必須有內容,上限 50 字元;空白回傳 400 name_required,超過回傳 400 name_too_long。
總部客戶的序號。與 parentCompanyCode 都給時以這個為準。兩者都沒給回傳 400 parent_company_required。
總部客戶的 ERP 端代碼(outerSysCode),大小寫敏感的完全比對。parentCompanyId 有值時忽略這個欄位。對不到客戶回傳 400 company_not_found;對到兩家以上回傳 400 company_code_ambiguous,不會替你挑一家。
子客戶的序號清單,選填。與 subCompanyCodes 取聯集;重複的值、小於等於 0 的值與總部自己的序號會被略過。每個 id 都必須是呼叫端所屬租戶的有效客戶,否則回傳 400 company_not_found。
子客戶的 ERP 端代碼清單,選填。與 subCompanyIds 取聯集;空白的代碼會被略過,其餘做大小寫敏感的完全比對。對不到客戶回傳 400 company_not_found;對到兩家以上回傳 400 company_code_ambiguous。
Response
新增或更新成功後,該筆資料的 id。