Skip to main content

會員API

會員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 '{
    "token": "company-auth-token-xxxxx",
    "memName": "王小明",
    "memMobile": "0912345678",
    "memEmail": "[email protected]"
  }'

成功時回應：

{ "status": "success" }

認證

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

新增 / 更新 判斷邏輯

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

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

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

請求格式

請求 body 是一個 JSON 物件。除了必填的 token，其餘每個 key 可以是「系統預設欄位」或「自訂欄位」。

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

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

系統預設欄位

使用 camelCase 名稱，value 為字串。

欄位 說明 必填
token公司授權 token（用於識別公司）✅
memMobile 手機號碼（新增/更新的比對鍵） 建議
memName 客戶姓名
memFirstName名字
memLastName姓氏
memNickName暱稱
memSex性別
memBirthday生日（西元，yyyy-MM-dd）
memTel 電話
memEmail Email
memSex性別
memNickName暱稱
memBirthday生日（西元）
memCountry 客戶國別
memAddressmemServiceUnit 地址服務單位
memCare貼心服務
memRemark 備註
introducerNamememEdm 介紹人姓名是否訂閱 EDM
introducerMobilememSms 介紹人電話是否接收簡訊
introducerTypeisBlacklist 介紹人身份是否為黑名單
noMarketing行銷勿用
thirdPartyCustomerId 第三方客戶編號
memLineLINE
memFbFacebook
memIgInstagram
memWhatsappWhatsApp
memWechat微信
memSkypeSkype
memQqQQ

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

欄位說明
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 城市 城市 pk（數名稱（字串） 100"臺北市"
6 區域 區域 pk（數名稱（字串） 1001"中正區"
7 道路 道路 pk（數名稱（字串） 5001"忠孝東路"
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

{
  "token": "company-auth-token-xxxxx",
  "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": 100"臺北市",
  "custom_zone_field": "中正區",
  "custom_road_field": "忠孝東路",
  "custom_address_field": "忠孝東路一段1號",
  "custom_zipcode_field": "100",
  "custom_address_group": {
    "city": "臺北市",
    "zone": "中正區",
    "road": "忠孝東路",
    "addressDt": "忠孝東路一段1號",
    "zip": "100"
  }
}

注意事項

  • ⚠️ 西元日期、農曆必須傳「物件」，不可傳純字串，否則會解析失敗並回錯誤。
  • ⚠️ 城市 / 區域 / 道路請一律傳的是「名稱」（如 pk（數字"臺北市"），不是名稱。
    • 註：iftek 主平台會自動推播給貴公司的 outbound webhook 輸出的是「名稱」字串，與此匯入 API 所需的 pk 格式不同，串接時請勿直接把收到的名稱回傳。
  • 未被識別的 key 會原樣帶入後端，由後端驗證決定是否接受對應。
  • 必填⚠️ 更新為全量覆蓋：更新時未帶到的欄位的檢核由後端負責；不合法會回錯誤被清空，請帶上完整會員資料。
  • 至少需提供一項聯絡方式（手機 / 電話 / Email / LINE / Facebook / IG / WhatsApp / QQ / Skype / 微信 / 第三方客戶編號 擇一）。
  • 特殊標籤（mscType 10）目前暫不支援匯入，傳了會被忽略。
  • 必填欄位由平台檢核，不合法會回錯誤。
Back to top