建立客戶
建立單一客戶。未帶 id 且 outerSysCode 未對應到既有客戶時新增;outerSysCode 已存在時改為更新該筆(冪等去重),重送同一份資料不會產生重複客戶。負責業務可以用 internalUserId 或 internalUserOuterSysCode(業務的外部系統代碼)指定,兩者都省略時套用貴公司設定的預設業務;代碼對不到業務時回傳 400,不會退回預設業務,規則見請求內容的欄位說明。
也可以一併設定結帳條件(settlementType)與可用付款方式(paymentMethodMode、paymentMethods),省略時新增的客戶為 Monthly、Inherit、空清單;各欄位的規則見請求內容的欄位說明,合法的付款方式 key 見 GET /v1/payment-methods。這三個欄位的驗證失敗會回傳 400 加上對應的錯誤字串,整筆不寫入。
Authentication
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
客戶序號。帶 id 時一律視為更新該筆客戶,不會再比對 outerSysCode;省略時改依 outerSysCode 判斷新增或更新。PUT /v1/companies/{id} 會忽略這裡的值,一律以路徑上的 id 為準。
ERP 端的客戶代碼,用來與既有客戶比對、去重。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。
企業名稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 name_too_long。
企業簡稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 20 字元,超過回傳 400 short_name_too_long。
公司電話。新增時省略視為空字串;更新時省略保留現有值。長度上限 20 字元,超過回傳 400 cell_phone_too_long。
收貨地址。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 shipping_address_too_long。
負責業務(內部使用者)的序號,選填。省略時可改送 internalUserOuterSysCode 以業務的外部系統代碼指定;兩者都省略時,新增會套用貴租戶設定的預設業務(若租戶未設定預設業務,新增會失敗),更新則保留現有值。兩者都有值時以本欄位為準。
負責業務(內部使用者)的外部系統代碼,選填,讓 ERP 不必先知道內部使用者的序號。只有在 internalUserId 省略時才會使用;兩者都有值時以 internalUserId 為準,這個代碼完全不會被比對,所以填錯也不會造成失敗。
代碼會與貴租戶底下未刪除的內部使用者精準比對,前後空白會被忽略、大小寫敏感,與 GET /v1/internal-users 回傳的 outerSysCode 相同;null 或只有空白視同省略。不檢查該使用者是否啟用中,與直接送 internalUserId 一致。
- 對不到任何人:400 internal_user_not_found
- 對到兩位以上(
outerSysCode不保證唯一):400 internal_user_code_ambiguous,請改送internalUserId
兩種失敗都不會退回預設業務,也不會寫入任何欄位,包含同一個請求裡的其他欄位。
結帳條件,只接受 Cash(現結)或 Monthly(月結),大小寫敏感、須完全相符,與 GET 回傳的值相同。新增時省略為 Monthly;更新時省略保留現有值。前後空白會被忽略,只有空白視同省略。其他值回傳 400 invalid_settlement_type。
結帳條件只決定結帳頁有沒有「月結」(掛帳)這個選項,與付款方式是各自獨立的兩個設定,改其中一個不會動到另一個,也不會清購物車或影響既有訂單。
這個客戶可用付款方式的決定方式,只接受 Inherit(沿用租戶已啟用的全部付款方式)或 Specify(只用 paymentMethods 列出的那幾種),大小寫敏感、須完全相符。前後空白會被忽略,只有空白視同省略。
本欄與 paymentMethods 必須成對寫入,依序判斷:
- 兩者都省略:新增時為
Inherit加空清單;更新時兩者都不動 - 只送
paymentMethods(包含空陣列)沒送本欄:400 payment_method_mode_required - 本欄不是
Inherit或Specify:400 invalid_payment_method_mode Inherit:paymentMethods省略或空陣列即可,會清空清單;帶非空清單回傳 400 payment_methods_not_allowedSpecify:必須在同一個請求帶非空的paymentMethods,否則回傳 400 payment_methods_required
驗證失敗時整筆拒絕,不會寫入任何欄位,包含同一個請求裡的 name 等其他欄位。
paymentMethodMode 為 Specify 時,這個客戶可用的付款方式 key 清單,須與 paymentMethodMode 一起送出(規則見該欄位)。合法的 key 可由 GET /v1/payment-methods 取得:內建的 BankTransfer、ECPayAtm、ECPayCreditOneTime,或貴租戶自訂的 Custom_ 開頭 key。
每個元素會先去除前後空白,空白的元素會被略過,重複的值會去重並保留第一次出現的順序。大小寫敏感、須完全相符,不接受數字或以逗號串起來的字串。
- 含
MonthlySettlement:400 monthly_settlement_not_allowed,月結請用settlementType - 其他不合法的值(
None、其他租戶或已刪除的自訂 key、格式不符的字串等):400 invalid_payment_method
清單裡的內建付款方式即使租戶從未設定過也算合法;但 Specify 實際生效的是「清單」與「租戶目前已啟用的付款方式」兩者的交集,尚未啟用的付款方式要等租戶啟用後,採購方才看得到。
Response
新增或更新成功後,該筆資料的 id。