Skip to navigation

批次寫入客戶

View as Markdown

一次寫入多筆客戶,逐筆各自新增、更新或去重,互不影響。

送出空陣列或沒有 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

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 a list of objects.
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
itemslist of objects or nullOptional

逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。

Errors

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