Skip to main content

會員API

將會員資料推送進 iftek 平台。平台會依「手機號碼」自動判斷要新增還是更新會員（upsert）。

目錄

總覽

項目 內容
用途 由貴公司系統將會員資料匯入 iftek 平台
方法 POST
端點 /api/v1/openApi/memberInfo
內容格式 application/json
行為 依手機號碼自動 新增或更新（upsert）

快速開始

curl -X POST https://<iftek-host>/api/v1/openApi/memberInfo \
  -H "Content-Type: application/json" \
  -H "Authorization: company-auth-token-xxxxx" \
  -d '{
    "memName": "王小明",
    "memMobile": "0912345678",
    "memEmail": "[email protected]"
  }'

成功時回應：

{ "status": "success" }

認證

  • 每個請求都必須在 HTTP header 帶上 Authorization，平台會用它識別對應的公司。
  • 此 token 由 iftek 提供，請妥善保管，勿外洩。
Header 必填 說明
Authorization ✅ 公司授權 token（用於識別公司）
Content-Type ✅ application/json
狀況 回應
token 有效 200，{ "status": "success" }
token 無效 / 未授權 403（error token）

新增 / 更新 判斷邏輯

平台以 公司（由 Authorization 推得）+ 手機號碼（memMobile） 來比對既有會員：

情況 結果
有帶 memMobile，且查到既有會員 更新該會員
有帶 memMobile，但查不到 新增會員
未帶 memMobile 一律視為新增（無法比對既有會員）

💡 若希望走「更新」流程，請務必帶上正確的 memMobile。

請求格式

請求 body 是一個 JSON 物件，每個 key 可以是「系統預設欄位」或「自訂欄位」。

⚠️ 更新為全量覆蓋：更新既有會員時，未帶到的欄位會被清空。即使只想修改單一欄位，也請把該會員的完整資料一起帶上。

💡 至少需提供一項聯絡方式（手機、電話、Email、LINE、Facebook、IG、WhatsApp、QQ、Skype、微信、第三方客戶編號 擇一）。

系統預設欄位

使用 camelCase 名稱，value 為字串。

欄位 說明 必填
memMobile 手機號碼（新增/更新的比對鍵） 建議
memName 客戶姓名
memFirstName 名字
memLastName 姓氏
memNickName 暱稱
memSex 性別
memBirthday 生日（西元，yyyy-MM-dd）
memTel 電話
memEmail Email
memCountry 客戶國別
memServiceUnit 服務單位
memCare 貼心服務
memRemark 備註
memEdm 是否訂閱 EDM
memSms 是否接收簡訊
isBlacklist 是否為黑名單
noMarketing 行銷勿用
thirdPartyCustomerId 第三方客戶編號
memLine LINE
memFb Facebook
memIg Instagram
memWhatsapp WhatsApp
memWechat 微信
memSkype Skype
memQq QQ

介紹人欄位（會員有介紹人時填寫）：

欄位 說明
introducerType 介紹人身份
introducerName 介紹人姓名
introducerMobile 介紹人電話
introducerMemNum 介紹會員流水號（數字；介紹人身份為「會員」時使用）
referralDate 介紹日期

地址欄位（請一律傳「名稱」，平台會自動對應）：

欄位 說明
memCity 城市名稱，例 "臺北市"
memZone 區域名稱，例 "中正區"
memRoad 道路名稱，例 "忠孝東路"
memAddress 詳細地址，例 "忠孝東路一段1號"

標籤 / 分店 / 照片（格式較特殊）：

欄位 格式 說明
memTagList 陣列 會員標籤清單；元素可為標籤名稱（字串）或標籤編號（數字），例 ["VIP", 101]
memStoreList 陣列 會員所屬分店清單；元素可為分店代號（字串）或分店編號（數字），例 ["STORE_A", 10]
memPhoto 陣列 / 字串 上傳新照片：[{ "name": "檔名", "base64": "圖片內容" }]（base64 可含 data:...;base64, 前綴）；若要沿用原本照片，把先前我們提供的照片路徑字串原樣帶回即可；不帶則不設定照片。

自訂欄位

key 使用貴公司在「會員設定頁」設定的 apiCode，平台會自動對應回內部欄位。 value 格式依該欄位類型（mscType）而定：

mscType 類型 value 格式 範例
1 西元日期 物件 { "gregorianDate": "yyyy-MM-dd" } {"gregorianDate":"2024-03-15"}
2 農曆 物件 { "yearCyclical", "monthCode", "lunarDay" } {"yearCyclical":"甲子","monthCode":"4X","lunarDay":15}
3 文字框 字串 "自由輸入"
4 文字區域 字串 "多行文字"
5 城市 城市名稱（字串） "臺北市"
6 區域 區域名稱（字串） "中正區"
7 道路 道路名稱（字串） "忠孝東路"
8 地址 字串 "忠孝東路一段1號"
9 郵遞區號 字串 "100"
10 特殊標籤 暫不支援匯入（傳了會被忽略） —

農曆 monthCode 規則： "4" = 4 月、"4X" = 閏 4 月；lunarDay 為數字。

地址群組自訂欄位： 若貴公司把城市／區域／道路設定為同一組「地址群組」，請用群組中城市欄位的 apiCode 當 key，value 傳一個名稱物件：

{
  "city": "臺北市",
  "zone": "中正區",
  "road": "忠孝東路",
  "addressDt": "忠孝東路一段1號",
  "zip": "100"
}

回應

HTTP 狀態 說明 Body
200 匯入成功 { "status": "success" }
403 token 無效 / 未授權 error token

完整範例

Headers

POST /api/v1/openApi/memberInfo
Authorization: company-auth-token-xxxxx
Content-Type: application/json

Body

{
  "memName": "王小明",
  "memFirstName": "小明",
  "memLastName": "王",
  "memNickName": "明哥",
  "memMobile": "0912345678",
  "memTel": "0223456789",
  "memEmail": "[email protected]",
  "memSex": "1",
  "memBirthday": "1990-01-01",
  "memCountry": "TW",
  "memServiceUnit": "台北門市",
  "memCare": "Y",
  "memRemark": "VIP 客戶，生日當月贈禮",
  "memEdm": "Y",
  "memSms": "Y",
  "isBlacklist": "N",
  "noMarketing": "N",
  "thirdPartyCustomerId": "CRM-100123",

  "memLine": "ming_line",
  "memFb": "ming.fb",
  "memIg": "ming.ig",
  "memWhatsapp": "0912345678",
  "memWechat": "ming_wechat",
  "memSkype": "ming.skype",
  "memQq": "123456789",

  "introducerType": "0",
  "introducerName": "李大華",
  "introducerMobile": "0922333444",
  "referralDate": "2024-01-10",

  "memCity": "臺北市",
  "memZone": "中正區",
  "memRoad": "忠孝東路",
  "memAddress": "忠孝東路一段1號",

  "memTagList": ["VIP", 101],
  "memStoreList": ["STORE_A", 10],
  "memPhoto": [
    { "name": "avatar.png", "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUh..." }
  ],

  "custom_text_field": "自由輸入內容",
  "custom_textarea_field": "第一行\n第二行",
  "custom_gregorian_field": { "gregorianDate": "2024-03-15" },
  "custom_lunar_field": {
    "yearCyclical": "甲子",
    "monthCode": "4X",
    "lunarDay": 15
  },
  "custom_city_field": "臺北市",
  "custom_zone_field": "中正區",
  "custom_road_field": "忠孝東路",
  "custom_address_field": "忠孝東路一段1號",
  "custom_zipcode_field": "100",
  "custom_address_group": {
    "city": "臺北市",
    "zone": "中正區",
    "road": "忠孝東路",
    "addressDt": "忠孝東路一段1號",
    "zip": "100"
  }
}

注意事項

  • ⚠️ 西元日期、農曆必須傳「物件」，不可傳純字串，否則會解析失敗並回錯誤。
  • 城市 / 區域 / 道路請一律傳「名稱」（如 "臺北市"），平台會自動對應。
  • ⚠️ 更新為全量覆蓋：更新時未帶到的欄位會被清空，請帶上完整會員資料。
  • 至少需提供一項聯絡方式（手機 / 電話 / Email / LINE / Facebook / IG / WhatsApp / QQ / Skype / 微信 / 第三方客戶編號 擇一）。
  • 特殊標籤（mscType 10）目前暫不支援匯入，傳了會被忽略。
  • 必填欄位由平台檢核，不合法會回錯誤。
Back to top