Skip to navigation

建立客戶總部

View as Markdown

⚠️ 新增群組後,總部客戶的 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

X-Signaturestring

每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。

canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。

Request

This endpoint expects an object.
namestring or nullOptional

群組名稱,必填。去掉前後空白後必須有內容,上限 50 字元;空白回傳 400 name_required,超過回傳 400 name_too_long。

parentCompanyIdlong or nullOptional

總部客戶的序號。與 parentCompanyCode 都給時以這個為準。兩者都沒給回傳 400 parent_company_required。

parentCompanyCodestring or nullOptional

總部客戶的 ERP 端代碼(outerSysCode),大小寫敏感的完全比對。parentCompanyId 有值時忽略這個欄位。對不到客戶回傳 400 company_not_found;對到兩家以上回傳 400 company_code_ambiguous,不會替你挑一家。

subCompanyIdslist of longs or nullOptional

子客戶的序號清單,選填。與 subCompanyCodes 取聯集;重複的值、小於等於 0 的值與總部自己的序號會被略過。每個 id 都必須是呼叫端所屬租戶的有效客戶,否則回傳 400 company_not_found。

subCompanyCodeslist of strings or nullOptional

子客戶的 ERP 端代碼清單,選填。與 subCompanyIds 取聯集;空白的代碼會被略過,其餘做大小寫敏感的完全比對。對不到客戶回傳 400 company_not_found;對到兩家以上回傳 400 company_code_ambiguous。

Response

Created
idlongOptional

新增或更新成功後,該筆資料的 id。

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error