---
title: API 列表
description: API 列表
---

[toc]

---

## 驗證相關

### 取得 JWT

#### 端點查詢

mutation signinByToken($accessKeyId: String!, $secretAccessKey: String!) {
    signinByToken(accessKeyId: $accessKeyId, secretAccessKey: $secretAccessKey)
}

#### 使用情境

在每一次的 GraphQL 的請求中，以 `Bearer {jwt}` 的方式放到 **Request Header** 中的 **authorization** 與 **Cookie**，以進行身份驗證

{
    authorization: `Bearer ${jwt}`
}

---

### 取得 X-App-User-Token

#### Header 要求：

- 請在 Header 加入 `X-App-User-Token`，內容為 Magento 的 token

{
    X-App-User-Token: `${MagentoToken}`
}

#### 端點查詢

mutation Call($table: String!, $name: String!, $argument: String!) {
  call(table: $table, name: $name, argument: $argument)
}

#### 參數

- table：posmember
- name："App登入"
- argument：
| 表頭欄位名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------- | -------- | -------- | ------ | ------ |
| memberName | 會員編號 | 字串 | Y | |
| mobile | 手機號碼 | 字串 | Y | |

#### 回應

成功回應

- 回傳類型：`String`
- 回傳值：從 call 物件內取出 `appUserToken` 的值，該字串需存放於 Header `X-App-User-Token`，供後續請求使用。

{
  "data": {
    "call": "{\"appUserToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
  }
}

#### 使用情境

在每一次的 GraphQL 的請求中，將回傳的字串替換先前 **Request Header** 中的 **X-App-User-Token**，以進行身份驗證

{
    X-App-User-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
}

## 會員相關

### 查詢會員

查詢會員資料請使用此端點

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 使用情境

1. 註冊會員時，根據手機號碼查詢中台的會員資料，如果回傳結果為多筆資料，網站需顯示 “手機號碼已被多筆會員註冊，請洽客服人員” 的錯誤訊息
2. 登入會員時，根據手機號碼查詢最新的會員資料

#### 端點名稱

findPosmember

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ----------------------- |
| name | 會員編號 | 字串 | |
| mobile | 手機號碼 | 字串 | 手機號碼前面去零加 +886 |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------------------- | ------------------------ | -------- | ---------------------------------------------- |
| name | 會員編號 | 字串 | |
| emLineId | LINE ID | 字串 | |
| displayName | 會員姓名 | 字串 | |
| email | E-Mail | 字串 | |
| birth | 生日 | 日期 | |
| gender | 性別 | 列舉 | MALE、FEMALE、OTHERS |
| city | 城市 | 字串 | |
| state | 區域 | 字串 | |
| newAddress | 地址（新） | 字串 | |
| mobile | 手機 | 字串 | |
| invoiceCarrier | 共通性載具 | 字串 | |
| eGUIUniNo | 統一編號 | 字串 | |
| recommendStore | 推薦門市 | 字串 | |
| recommendStoreEmployees | 門市推薦人員 | 字串 | 員工編號，以逗號分隔多值 |
| mgmRecommender | 推薦人員 | 字串 | 會員編號，以逗號分隔多值 |
| emMobileSMSOptIn | 同意收取簡訊優惠 | 布林 | |
| emOptIn | 同意收取電子報優惠 | 布林 | |
| appLoginTime | APP 登入時間 | 日期 | |
| joiningSource | 加入來源 | 列舉 | STORE、AD |
| petDogCnt | 寵物數量\_狗 | 整數 | |
| petCatCnt | 寵物數量\_貓 | 整數 | |
| petOtherCnt | 寵物數量\_其他 | 整數 | |
| pets01 | 寵物種類 01 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed01 | 寵物品種 01 | 字串 | |
| petName01 | 寵物姓名 01 | 字串 | |
| petBirth01 | 寵物生日 01 | 日期 | |
| petSex01 | 寵物性別 01 | 列舉 | MALE、FEMALE |
| petStatus01 | 寵物狀態 01 | 列舉 | ON、OFF |
| petHealth01 | 節育狀況 01 | 列舉 | CONTROLLED、UNCONTROLLED |
| pets02 | 寵物種類 02 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed02 | 寵物品種 02 | 字串 | |
| petName02 | 寵物姓名 02 | 字串 | |
| petBirth02 | 寵物生日 02 | 日期 | |
| petSex02 | 寵物性別 02 | 列舉 | MALE、FEMALE |
| petStatus02 | 寵物狀態 02 | 列舉 | ON、OFF |
| petHealth02 | 節育狀況 02 | 列舉 | CONTROLLED、UNCONTROLLED |
| pets03 | 寵物種類 03 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed03 | 寵物品種 03 | 字串 | |
| petName03 | 寵物姓名 03 | 字串 | |
| petBirth03 | 寵物生日 03 | 日期 | |
| petSex03 | 寵物性別 03 | 列舉 | MALE、FEMALE |
| petStatus03 | 寵物狀態 03 | 列舉 | ON、OFF |
| petHealth03 | 節育狀況 03 | 列舉 | CONTROLLED、UNCONTROLLED |
| memberClass | 會員等級 | 列舉 | CLASSIC、GOLD、BLACK |
| memberStartAt | 會籍期間\_起 | 日期 | |
| memberEndAt | 會籍期間\_迄 | 日期 | |
| consumerlifeTotal | 會籍期間消費總金額 | 整數 | |
| consumerlifeCount | 會籍期間消費次數 | 整數 | |
| goldLevelupSaleTotal | 一般會員距離升級金卡差額 | 整數 | |
| blackLevelupSaleTotal | 金卡距離升級黑卡差額 | 整數 | |
| goldHoldSaleTotal | 金卡維持金卡的差額 | 整數 | |
| blackHoldSaleTotal | 黑卡維持黑卡的差額 | 整數 | |

---

### 建立會員

於任何情境需要建立新會員，則使用此端點
端點只會回傳會員編號，若有需要建立後的完整資料，請使用查詢端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table：posmember
- name："建立會員"
- argument：
| 表頭欄位名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------- | -------- | -------- | ------ | ------ |
| registeredAt | 會員首次註冊日 | 日期 | Y | |
| mobile | 手機號碼 | 字串 | Y | |
| source | 來源 | 列舉 | Y | PETPARK_EC、PETPARK_APP |
| displayName | 會員姓名 | 字串 | | |
| invoiceCarrier | 共通性載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 |
| ------------ | -------- | -------- |
| name | 會員編號 | 字串 |

---

### 更新會員

於任何情境需要更新會員資料，則使用此端點
端點只會回傳會員編號，若有需要建立後的完整資料，請使用查詢端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

- table: "posmember"
- name: "更新會員"
- argument
| 表頭欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ------ | ------- | ------- | -- |
| name | 會員編號 | 字串 | key 值，必填 |
| emLineId | LINE ID | 字串 | 可否編輯待討論 |
| displayName | 會員姓名 | 字串 | |
| email | E-Mail | 字串 | |
| birth | 生日 | 日期 | |
| gender | 性別 | 列舉 | MALE、FEMALE、OTHERS |
| city | 城市 | 字串 | |
| state | 區域 | 字串 | |
| address | 地址（新） | 字串 | |
| mobile | 手機 | 字串 | |
| invoiceCarrier | 共通性載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |
| recommendStore | 推薦門市 | 字串 | |
| recommendStoreEmployees | 門市推薦人員 | 字串 | 員工編號，以逗號分隔多值 |
| mgmRecommender | 推薦會員 | 字串 | 會員編號，以逗號分隔多值 |
| emMobileSMSOptIn | 同意收取簡訊優惠 | 布林 | |
| emOptIn | 同意收取電子報優惠 | 布林 | |
| appLoginTime | APP 登入時間 | 日期 | |
| joiningSource | 加入來源 | 列舉 | STORE、AD |
| petDogCnt | 寵物數量*狗 | 整數 | |
| petCatCnt | 寵物數量*貓 | 整數 | |
| petOtherCnt | 寵物數量\_其他 | 整數 | |
| pets01 | 寵物種類 01 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed01 | 寵物品種 01 | 字串 | |
| petName01 | 寵物姓名 01 | 字串 | |
| petBirth01 | 寵物生日 01 | 日期 | |
| petSex01 | 寵物性別 01 | 列舉 | MALE、FEMALE |
| petStatus01 | 寵物狀態 01 | 列舉 | ON、OFF |
| petHealth01 | 節育狀況 01 | 列舉 | CONTROLLED、UNCONTROLLED |
| pets02 | 寵物種類 02 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed02 | 寵物品種 02 | 字串 | |
| petName02 | 寵物姓名 02 | 字串 | |
| petBirth02 | 寵物生日 02 | 日期 | |
| petSex02 | 寵物性別 02 | 列舉 | MALE、FEMALE |
| petStatus02 | 寵物狀態 02 | 列舉 | ON、OFF |
| petHealth02 | 節育狀況 02 | 列舉 | CONTROLLED、UNCONTROLLED |
| pets03 | 寵物種類 03 | 列舉 | CAT、DOG、MOUSE、RABBIT、FISH、REPTILE、OTHERS |
| petBreed03 | 寵物品種 03 | 字串 | |
| petName03 | 寵物姓名 03 | 字串 | |
| petBirth03 | 寵物生日 03 | 日期 | |
| petSex03 | 寵物性別 03 | 列舉 | MALE、FEMALE |
| petStatus03 | 寵物狀態 03 | 列舉 | ON、OFF |
| petHealth03 | 節育狀況 03 | 列舉 | CONTROLLED、UNCONTROLLED |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 |
| ------------ | -------- | -------- |
| name | 會員編號 | 字串 |

---

## 商品資料與庫存相關

### 查詢門市商品庫存數

查詢門市商品的庫存數，可一次查詢多個商品。**由於庫存商品眾多，建議一次查詢最多 100 筆的商品以達到最好的效能**

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 端點名稱

findBalance

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | -------------------- |
| location | 倉庫編號 | 字串 | 倉庫編號等同門市編號 |
| item | 料件編號 | 字串 | 料件編號等同商品編號 |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| -------------------- | ----------------- | -------- | ---------------------- |
| location | 倉庫編號 | 字串 | 倉庫編號等同門市編號 |
| location_displayName | 倉庫編號.倉庫名稱 | 字串 | 門市的顯示名稱 |
| item | 料件編號 | 字串 | 料件編號等同商品編號 |
| item_displayName | 料件編號.料件名稱 | 字串 | 商品的顯示名稱 |
| amount | 目前庫存數 | 整數 | 商品在此門市下的庫存數 |

---

### 查詢商品

查詢商品請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. 查詢商品資料使用

#### 參數

- table: "item"
- name: "maFindItem

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| --------- | -------- | -------- | ---- | --------------------------------------------------- |
| itemNames | 料件編號 | 陣列 | | 使用料件名稱查詢，該方式不可傳入 skip 及 limit 參數 |
| skip | 偏移量 | 整數 | | |
| limit | 回傳筆數 | 整數 | | |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------------------------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | 料件編號 | 字串 | 料件編號等同商品編號 |
| displayName | 料件名稱 | 字串 | 商品的顯示名稱 |
| brand | 品牌 | 列舉 | 希爾思、法國皇家、優卡、etc... |
| animalRev1 | 適用動物 | 列舉 | DOG、CAT、CAT_AND_DOG、ALL、SMALL_ANIMAL_AQUARIUM、SMALL_ANIMAL_BIRD、SMALL_ANIMAL_AQUARIUM_BEETLE、SMALL_ANIMAL_AQUARIUM_TURTLE、SMALL_ANIMAL_AQUARIUM_FISH、SMALL_ANIMAL_HEDGEHOG、SMALL_ANIMAL_HONEYBAG、SMALL_ANIMAL_CHINCHILLA、SMALL_ANIMAL_RABBIT、SMALL_ANIMAL_CAVIIDAE、SMALL_ANIMAL_MICE、SMALL_ANIMAL_OMNIVOROUS、SMALL_ANIMAL_HERBIVORE、SMALL_ANIMAL_UNIVERSAL |
| category | 主分類 | 列舉 | DRY_FOOD、WET_FOOD、SNACK、etc... |
| subcategory | 次分類 | 列舉 | 零食*肉乾、濕糧*其他、零食\_凍乾、etc... |
| smallCategory | 小分類 | 列舉 | 乾糧*幼齡*無、乾糧*成齡*無、乾糧*熟齡*無、etc... |
| labelPrice | 建議售價（定價） | 整數 | |
| price | 標準售價（會員價） | 整數 | |
| standardMargin | 會員價毛利率（建檔進價） | 浮點數 | |
| specialMargin | 會員價毛利率（短期進價） | 浮點數 | |
| age | 商品適用年齡 | 列舉 | YOUNG、ADULT、SENIOR、ALL 複選，以,分隔 |
| size | 商品包裝規格 | 列舉 | SAMPLE、SMALL、MEDIUM、LARGE、RETAIL |
| description | 商品描述 | 字串 | |
| dietaryPreference | 穀類 | 列舉 | NATURAL、WITH_GRAIN、GRAIN_FREE |
| flavor | 口味 | 列舉 | CHICKEN、LAMB、BEEF、PORK、FISH、DUCK、VENISON、KANGAROO、RABBIT、MULTI_PROTEIN、TURKEY、QUAIL、VEGAN、OSTRICH、OTHER |
| healthFeature | 功能 | 列舉 | NUTRITIONAL_SUPPLEMENTS、SPORTS_SUPPLEMENTS、DIGESTIVE_CARE、BONE_DEVELOPMENT、EYE_CARE、MENSTRUAL_CARE、PREGNANCY_AND_NURSING、URINARY_CARE、SKIN_AND_COAT、CARDIAC_CARE、TEAR_STAIN、CANCER_CARE、KIDNEY_CARE、HAIRBALL_CONTROL、DENTAL、ORAL_CARE、WEIGHT_CONTROL、PANCREAS_CARE、LIVER_CARE、HYPOALLERGENIC、DIABETIC_CARE、STERILISED |
| pelletSize | 顆粒大小 | 列舉 | LARGE、MEDIUM、SMALL、ROUND、SPECIAL_SHAPE、STAR_SHAPE、STRIP、CHUNK、THIN_CIRCLE_SHAPE、THIN、FLAKE、CROSS_SHAPE、BALL_SHAPE、POWDER、LIQUID |
| hardness | 軟硬度 | 列舉 | VERY_HARD、HARD、SLIGHTLY_HARD、MODERATE、SLIGHTLY_SOFT、SOFT、VERY_SOFT |
| countryOfOrigin | 產地 | 列舉 | 土耳其、不丹、台灣、etc... |
| taxedPurchasePrice | 最新核價單進價(含稅) | 浮點數 | |
| instruction | 注意事項 | 字串 | |
| warranty | 是否提供售後服務 | 布林值 | |
| daysOfWarranty | 保固天數 | 字串 | |
| warrantyDescription | 保固說明 | 字串 | |
| productCondition | 物流性質 | 列舉 | NORMAL、FRAGILE、LIQUID |
| inspectionReportImage1_url | 檢驗報告書(圖 1)網址 | 字串 | 回傳永久圖片網址 |
| inspectionReportImage2_url | 檢驗報告書(圖 2)網址 | 字串 | 回傳永久圖片網址 |
| shelfLife | 是否有保存期限 | 布林值 | |
| expirationDays | 保存期限天數 | 整數 | |
| productStorageStatus | 商品保存狀態 | 列舉 | 常溫、冷藏、冷凍 |
| uploadOnPetParkDistribution | 是否上架寵公電商 | 布林值 | |
| petParkDistributionLongtermDiscount | 寵公電商長促價 | 整數 | |
| supplierWeight | 廠商-重量(淨重) | 浮點數 | |
| supplierUnitOfWeight | 廠商-重量單位 | 列舉 | GRAM、KILOGRAM、OUNCE、POUND |
| weight | 倉庫-重量(淨重) | 浮點數 | |
| weightUnit | 倉庫-重量單位 | 列舉 | G、KG、OZ、LB |
| width | 倉庫-寬度(公分) | 浮點數 | |
| height | 倉庫-高度(公分) | 浮點數 | |
| depth | 倉庫-深度(公分) | 浮點數 | |
| spec | 規格 | 字串 | |
| \_updatedAt | 更新時間 | 日期 | 商品資料最後更新時 |
| barcode | 商品條碼 | 字串 | 給予表頭最新的條碼資料 |

---

### 查詢商品會員價

查詢商品的會員價，可一次查詢多個商品。

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 端點名稱

findItem

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ---- |
| name | 料件編號 | 字串 | |

#### 回傳欄位

| 表頭欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ------------ | -------- | -------- | -------------- |
| name | 料件編號 | 字串 | |
| displayName | 料件名稱 | 字串 | 料件的顯示名稱 |
| price | 會員價 | 整數 | 料件的會員價 |

---

### 查詢主分類

查詢主分類資料請使用此端點。

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 端點名稱

findItemcategory

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | ---------- | -------- | ---------------- |
| name | 主分類編號 | 字串 | |
| displayName | 主分類名稱 | 字串 | 主分類的顯示名稱 |

#### 回傳欄位

_表頭_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | ---------- | -------- | ---------------- |
| name | 主分類編號 | 字串 | |
| displayName | 主分類名稱 | 字串 | 主分類的顯示名稱 |

---

### 查詢商品 EC 主檔

查詢商品資料請使用此端點。

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 端點名稱

findItemec

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | -------- | -------- | ---------------------- |
| itemName | 料件編號 | 字串 | 對應商品主檔的料件編號 |
| displayName | 料件名稱 | 字串 | 商品的顯示名稱 |
| \_updatedAt | 更新時間 | 日期 | 商品資料最後更新時間 |

#### 回傳欄位

_表頭_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| -------------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| itemName | 料件檔編號\* | 字串 | 對應商品主檔的料件編號 |
| itemType | 種類 | 列舉 | COMPLETE_DIETS、COMPLEMENTARY_DIETS、VETERINARY_DIETS |
| briefDescription | 商品描述(短) | 字串 | |
| volume | 容量(ML) | 列舉 | LESS_FIFTY、FIFTY_TO_ONE_FIFTY、ONE_FIFTY_TO_THREE_HUNDRED、GREATER_THREE_HUNDRED、LTE_10L、GTE_11L_LTE_20L、GTE_21L_LTE_30L、GTE_31L |
| isConvenienceStorePickup | 是否可超取 | 布林 | |
| breedSize | 適用體型 | 列舉 | MINIATURE、SMALL、MEDIUM、LARGE、EXTRA_LARGE、ALL 複選，以,分隔 |
| ecTitle | EC 商品標題 | 字串 | |
| ecSpecifications | EC 規格說明 | 字串 | |
| ecStatus | EC 狀態別 | 列舉 | SELLING、CREATED、OFF_SELLING、TEMP_OFF_SELLING、OFF_SELLING_IF_SOLD_OUT |
| memo | 備註 | 字串 | |
| petparkMainImage_url | 商品首圖-寵公電商.網址 | 字串 | |
| scenarioImage1_url | 商品情境圖 1.網址 | 字串 | |
| scenarioImage1Ordering | 商品情境圖 1-順序 | 整數 | |
| scenarioImage2_url | 商品情境圖 2.網址 | 字串 | |
| scenarioImage2Ordering | 商品情境圖 2-順序 | 整數 | |
| scenarioImage3_url | 商品情境圖 3.網址 | 字串 | |
| scenarioImage3Ordering | 商品情境圖 3-順序 | 整數 | |
| scenarioImage4_url | 商品情境圖 4.網址 | 字串 | |
| scenarioImage4Ordering | 商品情境圖 4-順序 | 整數 | |
| scenarioImage5_url | 商品情境圖 5.網址 | 字串 | |
| scenarioImage5Ordering | 商品情境圖 5-順序 | 整數 | |
| scenarioImage6_url | 商品情境圖 6.網址 | 字串 | |
| scenarioImage6Ordering | 商品情境圖 6-順序 | 整數 | |
| scenarioImage7_url | 商品情境圖 7.網址 | 字串 | |
| scenarioImage7Ordering | 商品情境圖 7-順序 | 整數 | |
| scenarioImage8_url | 商品情境圖 8.網址 | 字串 | |
| scenarioImage8Ordering | 商品情境圖 8-順序 | 整數 | |
| commercialImage_url | 商品廣告圖.網址 | 字串 | |
| descriptionImage1_url | EC 介紹頁 1.網址 | 字串 | |
| descriptionImage1Ordering | EC 介紹頁 1-順序 | 整數 | |
| descriptionImage2_url | EC 介紹頁 2.網址 | 字串 | |
| descriptionImage2Ordering | EC 介紹頁 2-順序 | 整數 | |
| descriptionImage3_url | EC 介紹頁 3.網址 | 字串 | |
| descriptionImage3Ordering | EC 介紹頁 3-順序 | 整數 | |
| descriptionImage4_url | EC 介紹頁 4.網址 | 字串 | |
| descriptionImage4Ordering | EC 介紹頁 4-順序 | 整數 | |
| descriptionImage5_url | EC 介紹頁 5.網址 | 字串 | |
| descriptionImage5Ordering | EC 介紹頁 5-順序 | 整數 | |
| descriptionImage6_url | EC 介紹頁 6.網址 | 字串 | |
| descriptionImage6Ordering | EC 介紹頁 6-順序 | 整數 | |
| descriptionImage7_url | EC 介紹頁 7.網址 | 字串 | |
| descriptionImage7Ordering | EC 介紹頁 7-順序 | 整數 | |
| descriptionImage8_url | EC 介紹頁 8.網址 | 字串 | |
| descriptionImage8Ordering | EC 介紹頁 8-順序 | 整數 | |
| descriptionImage9_url | EC 介紹頁 9.網址 | 字串 | |
| descriptionImage9Ordering | EC 介紹頁 9-順序 | 整數 | |
| descriptionImage10_url | EC 介紹頁 10.網址 | 字串 | |
| descriptionImage10Ordering | EC 介紹頁 10-順序 | 整數 | |

_表身.EC 管理分類_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| -------------------------- | --------------- | -------- | ---- |
| ecCategoryName | EC 管理分類編號 | 字串 | |
| ecCategoryName_displayName | EC 管理分類名稱 | 字串 | |

---

## 點數相關

### 查詢會員點數紀錄

查詢會員點數紀錄請使用此端點

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 使用情境

1. 查詢該會員目前剩餘的點數，可使用此端點查詢最新一筆該會員的點數帳本資料的剩餘點數欄位
2. 查詢該會員快到期的點數紀錄，可使用此端點查詢該會員到期時間大於目前時間的點數帳本資料，再根據到期時間由小至大排序，即可取得該會員快到期的點數紀錄

#### 端點名稱

findPointaccount

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | -------- | -------- | ---- |
| memberName | 會員編號 | 字串 | |
| \_createdAt | 建立時間 | 日期 | |

#### 回傳欄位

_表頭_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------- |
| name | 點數帳本編號 | 字串 | |
| memberName | 會員編號 | 字串 | |
| changeAmount | 異動點數 | 整數 | |
| localBalance | 剩餘點數 | 整數 | 此筆點數剩餘可使用的點數 |
| balance | 會員剩餘點數 | 整數 | 當下此會員剩餘的點數 |
| expiredAt | 到期時間 | 日期 | |
| memo | 備註 | 字串 | 增加點數或使用點數的原因，用來顯示於點數歷程的原因欄位 |
| type | 點數使用類型 | 列舉 | FROM_CONSUMPTION、FROM_EVENT、POINT_REDEMPTION、POINT_DISCOUNT、EXPIRED、REFUND、RECOVERY |
| maOrderId | Magento 訂單編號 | 字串 | |

---

### 核銷點數

核銷點數請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. Magento 訂單成立時，核銷使用的點數

#### 參數

- table: "pointaccount"
- name: "核銷點數"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------- | ---------------- | -------- | ---- | -------------------------------------------- |
| memberName | 會員編號 | 字串 | Y | |
| type | 類型 | 字串 | Y | POINT_REDEMPTION、POINT_DISCOUNT |
| usedPoints | 異動點數 | 整數 | Y |
| magentoOrderId | Magento 訂單編號 | 字串 | Y | |
| memo | 備註 | 字串 | | 使用點數的原因，用來顯示於點數歷程的原因欄位 |

#### 回傳值

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ---------- | -------- | -------- | -------------- |
| memberName | 會員編號 | 字串 | |
| usedPoints | 異動點數 | 整數 | 進行核銷的點數 |

---

### 返還點數

返還點數請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. Magento 訂單成立但還沒拋單給倉庫的時候，會員按下了取消，要退還使用的點數
2. Magento 訂單成立但付款失敗時，退還使用的點數

#### 參數

- table: "pointaccount"
- name: "返還點數"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------- | ---------------- | -------- | ---- | -------------------------------------------- |
| memberName | 會員編號 | 字串 | Y | |
| magentoOrderId | Magento 訂單編號 | 字串 | Y | |
| memo | 備註 | 字串 | | 使用點數的原因，用來顯示於點數歷程的原因欄位 |

#### 回傳值

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------------- | ---------------- | -------- | ---- |
| memberName | 會員編號 | 字串 |
| magentoOrderId | Magento 訂單編號 | 字串 |

---

### 點數歸戶

FeverSocial 點數歸戶請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. FeverSocial 獎勵發點時使用

#### 參數

- table: "feversocialpoints"
- name: "點數歸戶"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------------------------- | ------------------ | -------- | ---- | -------------- |
| memberName | 會員編號 | 字串 | Y | user_id |
| points | 贈送點數 | 整數 | Y | quantity |
| expiredAt | 點數到期日期 | 日期 | Y | expired_at |
| memo | 備註 | 字串 | Y | custom_code |
| transactionId | 交易編號 | 字串 | | id |
| transactionType | 交易類型 | 字串 | | type |
| transactionPromotionName | 活動名稱 | 字串 | | promotion_name |
| transactionPromotionId | 活動編號 | 字串 | | promotion_id |
| transactionPromotionUniqueId | 活動系統編號 | 字串 | | promotion_uuid |
| transactionMemberUniqueId | 使用者內部識別編號 | 字串 | | member_uuid |
| transactionCreatedAt | 建立時間 | 日期 | | created_at |

#### 回傳值

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ------------- | -------- | -------- | ---------- |
| memberName | 會員編號 | 字串 | |
| depositPoints | 發送點數 | 整數 | 發送的點數 |

---

### 查詢點加金活動

查詢點加金活動請使用此端點

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 使用情境

1. 查詢指定時間範圍內活動中的所有點加金活動

#### 端點名稱

findPointpromotion

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ------------ | -------- | ---- |
| startAt | 活動起始時間 | 日期 | |
| endAt | 活動結束時間 | 日期 | |

#### 回傳欄位

_表頭_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | -------------- | -------- | ------------ |
| name | 點加金活動編號 | 字串 | |
| displayName | 活動名稱 | 字串 | |
| startAt | 開始日期 | 日期 | |
| endAt | 結束日期 | 日期 | |
| desc | 活動說明 | 字串 | 多行文本類型 |
| img_url | 圖片網址 | 字串 | |

_表身_

兌換品項 redeemItems

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| -------------------- | -------------- | -------- | ---- |
| itemName | 料件編號 | 字串 | |
| itemName_displayName | 料件名稱 | 字串 | |
| itemName_labelPrice | 建議售價(定價) | 整數 | |
| itemImg_url | 料件圖片網址 | 字串 | |
| redeemableAmount | 可兌換數量 | 整數 | |
| amount | 單組數量 | 整數 | |
| redeemedAmount | 已兌換數量 | 整數 | |
| requiredPoints | 兌換所需點數 | 整數 | |
| requiredMoney | 兌換所需金額 | 整數 | |
| storeLimitSet | 門市限購組數 | 整數 | |
| barcode | APP 點加金條碼 | 字串 |
| description | 兌換說明 | 字串 |

---

## 優惠券相關

### 查詢會員優惠券紀錄

查詢會員優惠券紀錄請使用此端點

> 請參考[查詢表格紀錄](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E6%9F%A5%E8%A9%A2%E8%A1%A8%E6%A0%BC%E7%B4%80%E9%8C%84)

#### 端點名稱

findPetparkcoupon

#### 篩選條件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ------------ | ---------------------- | -------- | ---------------- |
| memberName | 會員編號 | 字串 | |
| code | 優惠券券號 | 字串 | |
| startAt | 優惠券可用起日 | 日期 | |
| endAt | 優惠券可用迄日 | 日期 | |
| usedAt | 優惠券使用時間 | 日期 | |
| usedSaleName | 使用優惠券的銷售單編號 | 字串 | Magento 訂單編號 |

#### 回傳欄位

_表頭_

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| --------------------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| memberName | 會員編號 | 字串 | |
| displayName | 優惠券名稱 | 字串 | |
| couponEventName | 優惠券活動編號 | 字串 | |
| couponEventName_displayName | 優惠券活動名稱 | 字串 | |
| couponEventName_type | 優惠券類型 | 列舉 | FREEBIE_CHANGE、PRICE_DISCOUNT、PERCENT_DISCOUNT、FREE_SHIPPING_FEE |
| couponEventName_useChannel | 優惠券適用渠道 | 列舉 | MA_SHOP、MA_FAST_BUY、STORE、SALON |
| couponEventName_discount | 優惠券折抵金額 | 整數 | |
| couponEventName_percent | 優惠券折數 | 整數 | 範圍 30 ~ 99，80 代表打八折 |
| couponEventName_applyTotal | 優惠券單筆消費金額使用門檻 | 整數 | |
| couponEventName_magentoId | Magento 促銷編號 | 字串 | |
| couponEventName_description | 優惠券使用說明 | 字串 | 多行文本類型 |
| couponEventName_linkParams | App 連結參數 | 字串 | |
| couponEventName_image | 優惠券圖片 | 字串 | 請自行組成圖片網址 <br>測試環境: https://cdn-staging.wonderpet.asia/優惠券_圖片/{優惠券圖片} <br>正式環境: https://cdn.wonderpet.asia/優惠券_圖片/{優惠券圖片} |
| code | 優惠券券號 | 字串 | |
| startAt | 優惠券可用起日 | 日期 | |
| endAt | 優惠券可用迄日 | 日期 | |
| usedAt | 優惠券使用時間 | 日期 | |
| usedSaleName | 使用優惠券的銷售單編號 | 字串 | |
| discount | 折價金額 | 整數 | |

---

### 發放優惠券

發放優惠券請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. 會員首次 APP 登入時，發送優惠券給會員
2. 會員首次註冊時，發送優惠券給會員

#### 參數

- table: "petparkcoupon"
- name: "發放優惠券"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------------------------- | ------------------ | -------- | ---- | ------------------------------------------- |
| timing | 發放時機 | 字串 | Y | FIRST_SIGNIN_APP、APPNEW_MEMBER、EVENT_CODE |
| memberName | 會員編號 | 字串 | Y | |
| couponEventCode | 優惠券活動代碼 | 字串 | | 有填入時發放時機必須為 EVENT_CODE |
| transactionId | 交易編號 | 字串 | | id |
| transactionType | 交易類型 | 字串 | | type |
| transactionPromotionName | 活動名稱 | 字串 | | promotion_name |
| transactionPromotionId | 活動編號 | 字串 | | promotion_id |
| transactionPromotionUniqueId | 活動系統編號 | 字串 | | promotion_uuid |
| transactionMemberUniqueId | 使用者內部識別編號 | 字串 | | member_uuid |
| transactionCreatedAt | 建立時間 | 日期 | | created_at |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| ---------- | ---------- | -------- | -------------------------------------------- |
| codes | 優惠券號 | 字串 | 多筆券號用,分隔 |
| amount | 優惠券張數 | 數字 | 發放幾張優惠券 |
| memberName | 會員編號 | 字串 | |
| message | 訊息 | 字串 | 票券歸戶成功後，會回傳 `票券歸戶成功！` 訊息 |

---

### 核銷優惠券

核銷優惠券請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. Magento 訂單建立後，若有使用優惠券，則進行優惠券核銷

#### 參數

- table: "petparkcoupon"
- name: "核銷優惠券"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------ | ---------------------- | -------- | ---- | ---------------- |
| code | 優惠券券號 | 字串 | Y | |
| usedAt | 優惠券使用時間 | 日期 | Y | |
| usedSaleName | 使用優惠券的銷售單編號 | 字串 | Y | Magento 訂單編號 |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---------------- |
| code | 優惠券券號 | 字串 | 核銷的優惠券券號 |

---

### 返還優惠券

取消已使用過的優惠券請使用此端點

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 使用情境

1. Magento 訂單成立但還沒拋單給倉庫的時候，會員按下了取消，要退還使用的優惠券
2. Magento 訂單成立但付款失敗時，退還使用的優惠券

#### 參數

- table: "petparkcoupon"
- name: "返還優惠券"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------ | ---------------------- | -------- | ---- | ---------------- |
| memberName | 會員編號 | 字串 | Y | |
| code | 優惠券券號 | 字串 | Y | |
| usedSaleName | 使用優惠券的銷售單編號 | 字串 | Y | Magento 訂單編號 |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---------------- |
| code | 優惠券券號 | 字串 | 返還的優惠券券號 |

---

## 訂單相關

### 建立線上購訂單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

> [!IMPORTANT]
> 批次新增時，若其中一筆訂單新增失敗，則所有訂單都會新增失敗，並擲出錯誤訊息顯示失敗的訂單編號與失敗原因。
>
> 錯誤訊息格式：`訂單新增失敗 - {訂單編號1}: {錯誤原因1}; {訂單編號2}: {錯誤原因2}`

#### 參數

- table: "mashoporder"
- name: "建立線上購訂單"
- argument (單筆新增時參數為單筆物件，批次新增時參數為物件陣列)

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------------------- | ---------------- | ------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| name | Magento 訂單編號 | 字串 | Y | KEY 值，紀錄於 Magento 的訂單編號 |
| total | 消費總金額 | 整數 | Y | 實際付款金額 |
| orderCreatedAt | 訂單建立時間 | 日期 | Y | |
| paidAt | 訂單付款時間 | 日期 | | 完成付款的時間 |
| memberName | 會員編號 | 字串 | Y | 於 Magento 進行結帳的會員 |
| invoiceDate | 發票日期 | 日期 | | |
| invoiceNumber | 發票號碼 | 字串 | | |
| paymentId | 金流編號 | 字串 | | 金流端提供的唯一金流編碼 |
| pointDiscountUsedPoint | 點數折現使用點數 | 整數 | Y | 此訂單使用點數折現的折抵點數 |
| pointDiscount | 點數折現金額 | 整數 | Y | 此訂單使用點數折現的折抵金額 |
| eGUICarrier | 載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |
| payment | 付款方式 | 列舉 | Y | CREDIT_CARD、COD、LINEPAY |
| shipment | 配送方式 | 列舉 | Y | HOME_DELIVERY、SEVEN_ELEVEN |
| creditNo | 信用卡號 | 字串 | | |
| creditBankName | 銀行別 | 字串 | | |
| transTime | 交易時間 | 日期 | | |
| referenceNo | 銀行交易序號 | 字串 | | |
| cardType | 卡別 | 字串 | | |
| pickUpTime | 訂單取貨完成時間 | 日期 | | 貨到付款、配送完成時間 |
| status | 訂單狀態 | 列舉 | Y | PROCESSING、PACKING、PENDING、SHIPPED_PAID、SHIPPED_UNPAID、CAN_PICK_UP_PAID、CAN_PICK_UP_UNPAID、COMPLETE、CLOSED、CANCELED |
| shippingFee | 訂單運費 | 整數 | Y | 消費者付的運費 |
| items | 料件細項 | 陣列<料件細項> | | |
| orderDiscounts | 整單折扣細項 | 陣列<整單折扣細項> | | |

| 料件細項 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------------- | ------------------ | -------- | ---- | ---------------------------------------------------- |
| itemName | 料件編號 | 字串 | Y | 商品編號 |
| maItemDisplayName | Magento 料件名稱 | 字串 | Y | 商品名稱 |
| specialPrice | 促銷價 | 整數 | Y | 可能是寵物公園電商長促價或 Ma 指定價格 |
| price | 定價 | 整數 | Y | 商品定價 |
| quantity | 數量 | 整數 | Y | 購買數量 |
| subtotal | 小計 | 整數 | Y | 促銷價 \* 數量 |
| afterDiscountedValue | 整單折扣攤提後價值 | 浮點數 | Y | 將整單折扣的折抵金額攤提後的價值，不包含點數折抵金額 |

| 整單折扣細項 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------ | ------------ | -------- | ---- | --------------------------- |
| name | 整單折扣編號 | 字串 | Y | 紀錄於 Magento 該促銷的編號 |
| displayName | 整單折扣名稱 | 字串 | Y | 紀錄於 Magento 該促銷的名稱 |
| amount | 折抵金額 | 整數 | Y | 此訂單的整單折扣折抵金額 |

#### 回傳欄位

- 單筆新增時回傳單筆物件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ---- |
| name | 訂單編號 | 字串 | |

- 批次新增時回傳物件陣列

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ------------ | -------- | ---- |
| names | 訂單編號陣列 | 字串陣列 | |

### 更新線上購訂單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mashoporder"
- name: "更新線上購訂單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------- | ---------------- | ------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| name | Magento 訂單編號 | 字串 | Y | KEY 值，紀錄於 Magento 的訂單編號 |
| paidAt | 訂單付款時間 | 日期 | | |
| invoiceDate | 發票日期 | 日期 | | |
| invoiceNumber | 發票號碼 | 字串 | | |
| paymentId | 金流編號 | 字串 | | |
| eGUICarrier | 載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |
| creditNo | 信用卡號 | 字串 | | |
| creditBankName | 銀行別 | 字串 | | |
| transTime | 交易時間 | 日期 | | |
| referenceNo | 銀行交易序號 | 字串 | | |
| cardType | 卡別 | 字串 | | |
| pickUpTime | 訂單取貨完成時間 | 日期 | | 貨到付款、配送完成時間 |
| status | 訂單狀態 | 列舉 | | PROCESSING、PACKING、PENDING、SHIPPED_PAID、SHIPPED_UNPAID、CAN_PICK_UP_PAID、CAN_PICK_UP_UNPAID、COMPLETE、CLOSED、CANCELED |
| logisticVendor | 物流供應商 | 字串 | | |
| logisticType | 物流廠商代碼 | 字串 | | |
| shipments | 出貨單 | 陣列<出貨單> | | |
| inStoreAt | 到店時間 | 日期 | | |

| 出貨單 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------- | ------------ | -------- | ---- | ---------------------------------------------------------- |
| shipmentId | 出貨單編號 | 字串 | Y | Magento 更新出貨單時的索引 |
| logisticNo | 物流單號 | 字串 | | |
| logisticStatus | 物流配送狀態 | 字串 | | 310, 320, 330, 337, 341, 342, 343, 344, 345, 346, 336, 347 |
| rejectedAt | 拒收時間 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ---- |
| name | 訂單編號 | 字串 | |

### 建立線上購退貨單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mashopreturn"
- name: "建立線上購退貨單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| --------------- | ---------------- | -------------- | ---- | -------------------------------------------------------------- |
| name | 退貨單編號 | 字串 | Y | |
| maShopOrderName | Magento 訂單編號 | 字串 | Y | |
| status | 狀態 | 列舉 | Y | PENDING、AUTHORIZED、RETURN_RECEIVED、PROCESSED_CLOSED、CLOSED |
| processedAt | 完成退貨時間 | 日期 | | |
| items | 退貨項目 | 陣列<退貨項目> | | |

| 退貨項目 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------------- | ---------------- | -------- | ---- | ---- |
| itemName | 料件編號 | 字串 | Y | |
| maItemDisplayName | Magento 料件名稱 | 字串 | | |
| quantity | 數量 | 整數 | Y | |
| reason | 原因 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退貨單編號 | 字串 | |

### 更新線上購退貨單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mashopreturn"
- name: "更新線上購退貨單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------- | ------------ | -------- | ---- | -------------------------------------------------------------- |
| name | 退貨單編號 | 字串 | Y | |
| status | 狀態 | 列舉 | | PENDING、AUTHORIZED、RETURN_RECEIVED、PROCESSED_CLOSED、CLOSED |
| processedAt | 完成退貨時間 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退貨單編號 | 字串 | |

### 建立線上購退款單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mashoprefund"
- name: "建立線上購退款單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------------- | ---------------- | -------------- | ---- | ----------------------------- |
| name | 退款單編號 | 字串 | Y | |
| maShopOrderName | Magento 訂單編號 | 字串 | Y | |
| orderPaymentId | 原交易金流編號 | 字串 | | |
| paymentId | 退款金流編號 | 字串 | | |
| finishedAt | 退款完成時間 | 日期 | Y | |
| orderEGUINo | 原發票號碼 | 字串 | | |
| type | 退款方式 | 列舉 | Y | CREDIT_CARD、MANUAL_TRANSFER、LINEPAY |
| total | 退款金額 | 整數 | Y | |
| pointBalanced | 點數調整項 | 整數 | Y | |
| shippingFee | 退運費金額 | 整數 | Y | |
| adjustmentRefund | 調整加項 | 整數 | Y | |
| adjustmentFee | 調整減項 | 整數 | Y | |
| creditNoteNo | 折讓單編號 | 字串 | | |
| creditNoteCreatedAt | 折讓單建立時間 | 日期 | |
| creditNo | 信用卡號 | 字串 | | 退款方式為 CREDIT_CARD 時必填 |
| creditBankName | 銀行別 | 字串 | | |
| referenceNo | 銀行交易序號 | 字串 | | |
| transTime | 交易時間 | 日期 | | 退款方式為 CREDIT_CARD 時必填 |
| cardType | 卡別 | 字串 | | 退款方式為 CREDIT_CARD 時必填 |
| items | 退款項目 | 陣列<退款項目> | Y | |

| 退貨項目 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------------------- | ---------------- | -------- | ---- | ---- |
| itemName | 料件編號 | 字串 | Y | |
| maItemDisplayName | Magento 料件名稱 | 字串 | | |
| isReturnToStock | 是否收回 | 布林 | Y | |
| price | 退款單價 | 整數 | Y | |
| quantity | 退款數量 | 整數 | Y | |
| subtotal | 退款小計 | 整數 | Y | |
| discount | 折抵金額 | 整數 | Y | |
| afterDiscountedSubtotal | 折抵後退款小計 | 整數 | Y | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退款單編號 | 字串 | |

### 更新線上購退款單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mashoprefund"
- name: "更新線上購退款單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------------- | -------------- | -------- | ---- | ---- |
| name | 退款單編號 | 字串 | Y | |
| creditNoteNo | 折讓單編號 | 字串 | | |
| creditNoteCreatedAt | 折讓單建立時間 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退款單編號 | 字串 | |

### 建立寵速配訂單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

> [!IMPORTANT]
> 批次新增時，若其中一筆訂單新增失敗，則所有訂單都會新增失敗，並擲出錯誤訊息顯示失敗的訂單編號與失敗原因。
>
> 錯誤訊息格式：`訂單新增失敗 - {訂單編號1}: {錯誤原因1}; {訂單編號2}: {錯誤原因2}`

#### 參數

- table: "mafastbuyorder"
- name: "建立寵速配訂單"
- argument (單筆新增時參數為單筆物件，批次新增時參數為物件陣列)

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------------------- | ---------------- | ------------------ | ---- | --------------------------------------------------- |
| name | Magento 訂單編號 | 字串 | Y | KEY 值，紀錄於 Magento 的訂單編號 |
| storeName | 門市編號 | 字串 | Y | |
| memberName | 會員編號 | 字串 | Y | 於 Magento 進行結帳的會員 |
| paymentId | 金流編號 | 字串 | Y | 金流端提供的唯一金流編碼 |
| total | 消費總金額 | 整數 | Y | 實際付款金額 |
| pointDiscountUsedPoint | 點數折現使用點數 | 整數 | Y | 此訂單使用點數折現的折抵點數 |
| pointDiscount | 點數折現金額 | 整數 | Y | 此訂單使用點數折現的折抵金額 |
| recipientName | 收件人姓名 | 字串 | Y | |
| recipientMobile | 收件人手機 | 字串 | Y | |
| recipientAddress | 收件人地址 | 字串 | Y | |
| orderCreatedAt | 訂單建立時間 | 日期 | Y | |
| paidAt | 訂單付款時間 | 日期 | Y | 信用卡完成付款的時間 |
| status | 訂單狀態 | 列舉 | Y | PROCESSING、PACKING、SHIPPED_PAID、COMPLETE、CLOSED |
| orderType | 訂單類型 | 列舉 | | APPOINTMENT、INSTANT |
| deliverAt | 派車時間 | 日期 | | 發出派車請求時間 |
| acceptedAt | 司機接單時間 | 日期 | | 發出派車請求後，司機按下接單時間 |
| appointmentAt | 預約時間 | 日期 | | |
| pickUpAt | 司機取貨時間 | 日期 | | 司機按下接單時間後，到門市完成取件的時間 |
| payment | 付款方式 | 列舉 | Y | CREDIT_CARD、LINEPAY |
| shipment | 配送方式 | 列舉 | Y | STORE_DELIVERY、SELF |
| creditNo | 信用卡號 | 字串 | | |
| creditBankName | 銀行別 | 字串 | | |
| transTime | 交易日期 | 日期 | | |
| referenceNo | 銀行交易序號 | 字串 | | |
| cardType | 卡別 | 字串 | | |
| memo | 訂單備註 | 字串 | | 客人針對訂單有特殊需求 |
| receiptedAt | 門市接單時間 | 日期 | | |
| logisticVendor | 物流供應商 | 字串 | | 車隊物流商 |
| finishedAt | 訂單完成時間 | 日期 | | 訂單自取、配送完成時間 |
| shippingFee | 訂單運費 | 整數 | Y | 消費者付的運費 |
| donationCode | 捐贈碼 | 字串 | | |
| eGUICarrier | 載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |
| items | 料件細項 | 陣列<料件細項> | | |
| orderDiscounts | 整單折扣細項 | 陣列<整單折扣細項> | | |

| 料件細項 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------------------- | ------------------ | -------- | ---- | ---------------------------------------------------- |
| itemName | 料件編號 | 字串 | Y | 商品編號 |
| maItemDisplayName | Magento 料件名稱 | 字串 | Y | 商品名稱 |
| specialPrice | 促銷價 | 整數 | Y | 可能是寵物公園電商長促價或 Ma 指定價格 |
| price | 定價 | 整數 | Y | 商品定價 |
| quantity | 數量 | 整數 | Y | 購買數量 |
| subtotal | 小計 | 整數 | Y | 促銷價 \* 數量 |
| afterDiscountedValue | 整單折扣攤提後價值 | 整數 | Y | 將整單折扣的折抵金額攤提後的價值，不包含點數折抵金額 |

| 整單折扣細項 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------ | ------------ | -------- | ---- | --------------------------- |
| name | 整單折扣編號 | 字串 | Y | 紀錄於 Magento 該促銷的編號 |
| displayName | 整單折扣名稱 | 字串 | Y | 紀錄於 Magento 該促銷的名稱 |
| amount | 折抵金額 | 整數 | Y | 此訂單的整單折扣折抵金額 |

#### 回傳欄位

- 單筆新增時回傳單筆物件

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ---- |
| name | 訂單編號 | 字串 | |

- 批次新增時回傳物件陣列

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ------------ | -------- | ---- |
| names | 訂單編號陣列 | 字串陣列 | |

### 更新寵速配訂單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mafastbuyorder"
- name: "更新寵速配訂單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------------- | ---------------- | -------- | ---- | --------------------------------------------------- |
| name | Magento 訂單編號 | 字串 | Y | KEY 值，紀錄於 Magento 的訂單編號 |
| saleName | 銷售單編號 | 字串 | | POS 帶入此訂單並且建立銷售單後，回填銷售單編號 |
| status | 訂單狀態 | 列舉 | | PROCESSING、PACKING、SHIPPED_PAID、COMPLETE、CLOSED |
| orderType | 訂單類型 | 列舉 | | APPOINTMENT、INSTANT |
| deliverAt | 派車時間 | 日期 | | 發出派車請求時間 |
| acceptedAt | 司機接單時間 | 日期 | | 發出派車請求後，司機按下接單時間 |
| appointmentAt | 預約時間 | 日期 | | |
| pickUpAt | 司機取貨時間 | 日期 | | 司機按下接單時間後，到門市完成取件的時間 |
| receiptedAt | 門市接單時間 | 日期 | | |
| logisticVendor | 物流供應商 | 字串 | | 車隊物流商 |
| finishedAt | 訂單完成時間 | 日期 | | 訂單自取、配送完成時間 |
| stockFulfilledAt | 門店備貨完成時間 | 日期 | | |
| donationCode | 捐贈碼 | 字串 | | |
| eGUICarrier | 載具 | 字串 | | |
| eGUIUniNo | 統一編號 | 字串 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | -------- | -------- | ---- |
| name | 訂單編號 | 字串 | |

### 建立寵速配退貨單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mafastbuyreturn"
- name: "建立寵速配退貨單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------------ | ---------------- | -------------- | ---- | ---------------- |
| name | 退貨單編號 | 字串 | Y | |
| maFastBuyOrderName | Magento 訂單編號 | 字串 | Y | |
| status | 狀態 | 列舉 | Y | PROCESSED_CLOSED |
| processedAt | 完成退貨時間 | 日期 | | |
| items | 退貨項目 | 陣列<退貨項目> | | |

| 退貨項目 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------------- | ---------------- | -------- | ---- | ---- |
| itemName | 料件編號 | 字串 | Y | |
| maItemDisplayName | Magento 料件名稱 | 字串 | | |
| quantity | 數量 | 整數 | Y | |
| reason | 原因 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退貨單編號 | 字串 | |

### 更新寵速配退貨單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mafastbuyreturn"
- name: "更新寵速配退貨單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------- | ------------ | -------- | ---- | ---------------- |
| name | 退貨單編號 | 字串 | Y | |
| status | 狀態 | 列舉 | | PROCESSED_CLOSED |
| processedAt | 完成退貨時間 | 日期 | | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退貨單編號 | 字串 | |

### 建立寵速配退款單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

#### 參數

- table: "mafastbuyrefund"
- name: "建立寵速配退款單"
- argument

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ------------------ | ---------------- | -------------- | ---- | ----------------------------- |
| name | 退款單編號 | 字串 | Y | |
| maFastBuyOrderName | Magento 訂單編號 | 字串 | Y | |
| storeName | 門市編號 | 字串 | Y | |
| orderPaymentId | 原交易金流編號 | 字串 | Y | |
| paymentId | 退款金流編號 | 字串 | Y | |
| finishedAt | 退款完成時間 | 日期 | Y | |
| type | 退款方式 | 列舉 | Y | CREDIT_CARD、MANUAL_TRANSFER、LINEPAY |
| total | 退款金額 | 整數 | Y | |
| pointBalanced | 點數調整項 | 整數 | Y | |
| shippingFee | 退運費金額 | 整數 | Y | |
| creditNo | 信用卡號 | 字串 | | 退款方式為 CREDIT_CARD 時必填 |
| creditBankName | 銀行別 | 字串 | | |
| referenceNo | 銀行交易序號 | 字串 | | |
| transTime | 交易時間 | 日期 | | 退款方式為 CREDIT_CARD 時必填 |
| cardType | 卡別 | 字串 | | 退款方式為 CREDIT_CARD 時必填 |
| items | 退貨項目 | 陣列<退貨項目> | | |

| 退貨項目 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ----------------------- | ---------------- | -------- | ---- | ---------------------- |
| itemName | 料件編號 | 字串 | Y | |
| maItemDisplayName | Magento 料件名稱 | 字串 | | |
| isReturnToStock | 是否收回 | 布林 | Y | 退款商品是否收回至倉庫 |
| price | 退款單價 | 整數 | Y | |
| quantity | 退款數量 | 整數 | Y | |
| subtotal | 退款小計 | 整數 | Y | |
| discount | 折抵金額 | 整數 | Y | |
| afterDiscountedSubtotal | 折抵後退款小計 | 整數 | Y | |

#### 回傳欄位

| 參數名稱 | 中文名稱 | 數值類型 | 說明 |
| -------- | ---------- | -------- | ---- |
| name | 退款單編號 | 字串 | |

### 查詢會員線下銷售單

> 請參考[呼叫表格函數](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA#%E5%91%BC%E5%8F%AB%E8%A1%A8%E6%A0%BC%E5%87%BD%E6%95%B8)

此 API 同時支援 **後端串接** 與 **App 串接**，兩者大部分參數相同，唯有個別參數存在差異。

---

#### 共用參數

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| ---------- | ------------ | -------- | ---- | ------------------ |
| name | 交易序號 | 字串 | | 查詢指定銷售單使用 |
| memberName | 會員編號 | 字串 | Y | |
| skip | 略過筆數 | 整數 | | 預設 0 |
| limit | 回傳筆數 | 整數 | | 預設 15 |
| withDetail | 是否帶上細節 | 布林值 | | 預設 false |

---

#### 後端串接

- table: "possale"
- name: "查詢會員線下銷售單"

> 說明：後端串接不需要提供手機號碼參數。

---

#### App 串接

- table: "posmember"
- name: "App查詢會員線下銷售單"

> 額外參數：

| 參數名稱 | 中文名稱 | 數值類型 | 必填 | 說明 |
| -------- | -------- | -------- | ---- | ---- |
| mobile | 手機號碼 | 字串 | Y | |

---

#### 回傳欄位

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ---------------- | -------- | -------- | ------------------------------------------------------- |
| name | 交易序號 | 字串 | |
| saleType | 交易類型 | 列舉 | 門市銷售、美容服務 |
| storeDisplayName | 交易門市 | 字串 | |
| paidAt | 交易時間 | 日期 | |
| total | 交易金額 | 整數 | |
| detail | 交易細節 | 交易細節 | 當參數 `withDetail` 為 true 時會帶上資料，否則則為 null |

交易細節

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ---------------------- | -------- | -------------- | ------------------ |
| name | 交易序號 | 字串 | |
| paidAt | 成立時間 | 日期 | |
| storeDisplayName | 交易門市 | 字串 | |
| channel | 消費項目 | 列舉 | 門市銷售、美容服務 |
| configName | 交易機台 | 字串 | |
| payments | 付款方式 | 陣列<字串> | |
| invoiceNumber | 發票 | 字串 | |
| total | 消費金額 | 整數 | |
| subtotal | 商品小計 | 整數 | |
| promotionTotal | 商品促銷 | 整數 | |
| promotionDiscountTotal | 整單促銷 | 整數 | |
| promotionCouponTotal | 折扣碼 | 整數 | |
| pointDiscountTotal | 點數折現 | 整數 | |
| couponTotal | 優惠券 | 整數 | |
| items | 購買項目 | 陣列<購買項目> | |

購買項目

| 欄位名稱 | 中文名稱 | 數值類型 | 說明 |
| ----------- | -------- | -------- | ---- |
| name | 品號 | 字串 | |
| displayName | 名稱 | 字串 | |
| quantity | 數量 | 整數 | |
| subtotal | 小計 | 整數 | |