批次寫入客戶
一次寫入多筆客戶,逐筆各自新增、更新或去重,互不影響。
送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。
每一筆的新增/更新/去重規則與單筆端點相同:帶 id 就更新該筆;不帶 id 但 outerSysCode 命中既有客戶就改為更新(冪等去重);兩者都沒有則新增。更新一律是部分合併,只會覆蓋你送出的欄位。
每一筆都可以帶 settlementType、paymentMethodMode、paymentMethods,規則與單筆端點相同;某一筆的這三個欄位不合法時,那一筆回報 failed,errors 帶與單筆端點相同的錯誤字串,其他筆照常處理。
每一筆也可以用 internalUserOuterSysCode 指定負責業務(同時帶 internalUserId 時以 internalUserId 為準),規則與單筆端點相同。某一筆的代碼對不到業務時,那一筆回報 failed,errors 帶 internal_user_not_found 或 internal_user_code_ambiguous,其他筆照常處理。
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
逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。