Skip to navigation

更新客戶

View as Markdown

依 id 更新客戶。路徑上的 id 永遠優先於 body 帶的 id,即使 body 另外指定了別的 id 也一律以路徑為準,避免呼叫端不小心把更新導向另一筆客戶。更新是部分合併,只送有異動的欄位;省略的欄位維持原值,不會被清空。id 不存在或屬於其他租戶時回傳 404。

結帳條件(settlementType)與可用付款方式(paymentMethodMode、paymentMethods)也可以在這裡修改:省略就保留現有值,paymentMethodMode 與 paymentMethods 須成對送出。只送 settlementType 不會動到付款方式,只送 paymentMethodMode: "Inherit" 會清空付款方式清單、不動結帳條件。驗證失敗時回傳 400 加上對應的錯誤字串,整筆不寫入,包含同一個請求裡的其他欄位。

負責業務可以用 internalUserId 或 internalUserOuterSysCode(業務的外部系統代碼)指定,兩者都省略就保留現有值。代碼對不到業務時回傳 400,整筆不寫入,不會改成預設業務,規則見請求內容的欄位說明。

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 排查步驟,請參閱「驗證與簽章」。

Path parameters

idlongRequired

要更新的客戶序號。這個值永遠優先於 body 裡的 id,兩者不一致時一律以路徑為準。不存在或屬於其他租戶時,回傳 404;error 是該資源的簡短說明,而非 not_found。

Request

This endpoint expects an object.
idlong or nullOptional

客戶序號。帶 id 時一律視為更新該筆客戶,不會再比對 outerSysCode;省略時改依 outerSysCode 判斷新增或更新。PUT /v1/companies/{id} 會忽略這裡的值,一律以路徑上的 id 為準。

outerSysCodestring or nullOptional

ERP 端的客戶代碼,用來與既有客戶比對、去重。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 outer_sys_code_too_long。

namestring or nullOptional

企業名稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 name_too_long。

shortNamestring or nullOptional

企業簡稱。新增時省略視為空字串;更新時省略保留現有值。長度上限 20 字元,超過回傳 400 short_name_too_long。

cellPhonestring or nullOptional

公司電話。新增時省略視為空字串;更新時省略保留現有值。長度上限 20 字元,超過回傳 400 cell_phone_too_long。

shippingAddressstring or nullOptional

收貨地址。新增時省略視為空字串;更新時省略保留現有值。長度上限 50 字元,超過回傳 400 shipping_address_too_long。

internalUserIdlong or nullOptional

負責業務(內部使用者)的序號,選填。省略時可改送 internalUserOuterSysCode 以業務的外部系統代碼指定;兩者都省略時,新增會套用貴租戶設定的預設業務(若租戶未設定預設業務,新增會失敗),更新則保留現有值。兩者都有值時以本欄位為準。

internalUserOuterSysCodestring or nullOptional

負責業務(內部使用者)的外部系統代碼,選填,讓 ERP 不必先知道內部使用者的序號。只有在 internalUserId 省略時才會使用;兩者都有值時以 internalUserId 為準,這個代碼完全不會被比對,所以填錯也不會造成失敗。

代碼會與貴租戶底下未刪除的內部使用者精準比對,前後空白會被忽略、大小寫敏感,與 GET /v1/internal-users 回傳的 outerSysCode 相同;null 或只有空白視同省略。不檢查該使用者是否啟用中,與直接送 internalUserId 一致。

  • 對不到任何人:400 internal_user_not_found
  • 對到兩位以上(outerSysCode 不保證唯一):400 internal_user_code_ambiguous,請改送 internalUserId

兩種失敗都不會退回預設業務,也不會寫入任何欄位,包含同一個請求裡的其他欄位。

settlementTypestring or nullOptional

結帳條件,只接受 Cash(現結)或 Monthly(月結),大小寫敏感、須完全相符,與 GET 回傳的值相同。新增時省略為 Monthly;更新時省略保留現有值。前後空白會被忽略,只有空白視同省略。其他值回傳 400 invalid_settlement_type。

結帳條件只決定結帳頁有沒有「月結」(掛帳)這個選項,與付款方式是各自獨立的兩個設定,改其中一個不會動到另一個,也不會清購物車或影響既有訂單。

paymentMethodModestring or nullOptional

這個客戶可用付款方式的決定方式,只接受 Inherit(沿用租戶已啟用的全部付款方式)或 Specify(只用 paymentMethods 列出的那幾種),大小寫敏感、須完全相符。前後空白會被忽略,只有空白視同省略。

本欄與 paymentMethods 必須成對寫入,依序判斷:

  • 兩者都省略:新增時為 Inherit 加空清單;更新時兩者都不動
  • 只送 paymentMethods(包含空陣列)沒送本欄:400 payment_method_mode_required
  • 本欄不是 Inherit 或 Specify:400 invalid_payment_method_mode
  • Inherit:paymentMethods 省略或空陣列即可,會清空清單;帶非空清單回傳 400 payment_methods_not_allowed
  • Specify:必須在同一個請求帶非空的 paymentMethods,否則回傳 400 payment_methods_required

驗證失敗時整筆拒絕,不會寫入任何欄位,包含同一個請求裡的 name 等其他欄位。

paymentMethodslist of strings or nullOptional

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

OK
idlongOptional

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

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error