API 參考客戶

批次寫入客戶

View as Markdown
一次寫入多筆客戶，逐筆各自新增、更新或去重，互不影響。送出空陣列或沒有 body 會在受理前被拒絕，回傳 400 empty_batch；已受理的請求一律回傳 HTTP 200，逐筆的處理結果放在回應 body 的 items 裡（見 BatchUpsertResult / BatchItemResult），單筆失敗不會讓其他筆一起失敗。每一筆的新增/更新/去重規則與單筆端點相同：帶 id 就更新該筆；不帶 id 但 outerSysCode 命中既有客戶就改為更新（冪等去重）；兩者都沒有則新增。更新一律是部分合併，只會覆蓋你送出的欄位。

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/customers/{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

負責業務（內部使用者）的序號，選填。新增時省略會套用貴租戶設定的預設業務；若租戶未設定預設業務，新增會失敗。更新時省略保留現有值。

Response

OK
itemslist of objects or nullOptional

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

Errors

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