---
title: Wonderpet 中台串接手冊
description: For Magento
---

[toc]

---

# 表格介紹

端點資料皆為固定格式的物件陣列，單一筆資料以物件呈現，區分為表頭（body）與表身（lines）。
**表頭**通常紀錄 primitive type 資料，包含 `string`、`number`、`date`、`enum`、`boolean`，
**表身**以名稱作區別，每一個表身項目內的結構皆為物件陣列，每個物件代表一筆表身資料

interface TableRecord {
    body: { [fieldName:string]: number | string　| Date | boolean }
    lines: {
        [lineName: string]: Array<{ [fieldName:string]: number | string　| Date | boolean }>
    }
}

以一筆測試的會員資料舉例，資料定義如下：

表頭（單一欄位紀錄）
    會員名稱
    會員編號
    會員註冊時間
表身（多筆資料紀錄）
    標籤：
        標籤名稱
        備註
    飼養寵物：
        寵物名稱
        年齡
        性別

則資料結構如下：

interface PosMember {
    body: {
        memberName: string;
        memberNo: number;
        registeredAt: Date;
    },
    lines: {
        tags: {
            tagName: string;
            memo: string;
        },
        pets: {
            petName: string;
            age: number;
            gendor: string;
        }
    }
}

從 api 所取得的資料如下：

const records = [
    {
        body: {
            memberName: "測試會員",
            memberNo: 1,
            registeredAt: "Wed Nov 02 2022 15:19:38 GMT+0800 (台北標準時間)"
        },
        lines: {
            tags: [
                { tagName: "標籤一", memo: "這是標籤一" },
                { tagName: "標籤二", memo: "這是標籤二" },
                { tagName: "標籤三", memo: "這是標籤三" },
            ],
            pets: [
                { petName: "寵物一", age: 5, gendor: "MALE" },
                { petName: "寵物二", age: 1, gendor: "FEMALE" },
                { petName: "寵物三", age: 3, gendor: "FEMALE" },
            ],
        }
    }
]

# API 功能介紹

請參考 [API 功能介紹頁面](https://hackmd.io/XyfGJWRPQVW9Cq5cNUGNAA)

# API 列表

請參考 [API 列表頁面](https://hackmd.io/Adg0rZvBS4aQjxDXUV36bg)

# 常見問題

<details>
<summary>於 Server 端發出請求時，總是收到 401</summary>

在進行 SignIn 後會取得 JWT 並且 Response Headers 會帶有 SetCookie 更新 Client 端的 Cookie，而後所有的請求系統都會同時檢查 Cookie 與 Header 是否均帶有 JWT 並且內容一致，而在 Server 端發出請求時並不會帶有 Cookie，需要實作方自行實作 Cookie 機制

</details>
<details>
<summary>於 Server 端發出請求時，收到 "jwt expired" 的錯誤訊息</summary>

這是由於 JWT 已經過期，必須重新進行 SignIn 並且取得新的 JWT，並且帶入 Cookie

</details>
<details>
<summary>
於 Playground 發出請求時，收到 "invalid signature" 的錯誤訊息
</summary>

[GraphQL Playground](https://data-api-staging.wonderpet.asia/__playground)[^playground] 設定要加上 `"request.credentials": "include"`
&nbsp;
[^playground]: [Introducing GraphQL Playground](https://www.prisma.io/blog/introducing-graphql-playground-f1e0a018f05d)

</details>
<details>
<summary> 當發生錯誤，回傳範例：</summary>

GraphQL 錯誤回應的 JSON 結構，完整的程式碼:

{
  "errors": [
    {
      "message": "Error: 必須輸入會員編號",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ]
    }
  ]
}

</details>

# Changelog

| 日期 | 修改內容 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026/01/06 | `建立寵速配訂單`、`建立線上購訂單`、`建立線上購退款單`、`建立寵速配退款單` 新增 LINEPAY 付款/退款方式 |
| 2025/12/31 | `建立寵速配訂單`、`建立線上購訂單` 支援單筆與多筆查詢，調整回傳欄位 |
| 2025/12/26 | `建立會員`、`查詢會員`、`更新會員` API 新增 `invoiceCarrier`、`eGUIUniNo` 欄位 |
| 2025/12/24 | `建立寵速配訂單`、`更新寵速配訂單` API 新增 `donationCode`、`eGUICarrier`、`eGUIUniNo` 發票欄位 |
| 2025/12/05 | 常見問題新增錯誤範例 |
| 2025/09/22 | 1. 新增 `點數歸戶` API <br> 2. `發放優惠券` API 新增 FeverSocial Transaction 參數 |
| 2025/09/22 | `查詢會員` API 新增 `consumerlifeCount` 回傳欄位 |
| 2025/06/04 | 擴充 `查詢商品` 可以傳入 `料件編號` 查詢 |
| 2025/03/13 | `查詢商品資料使用` 新增回傳商品條碼（barcode） |
| 2025/03/03 | `App登入` API增加 header 說明 |
| 2025/02/24 | 新增 `App查詢會員線下銷售單` API |
| 2025/02/20 | 新增 `App登入` API |
| 2024/12/19 | `查詢會員優惠券紀錄` API 新增 `discount` 回傳欄 |
| 2024/11/29 | `發放優惠券` API 新增 `message` 回傳欄位 |
| 2024/11/06 | `發放優惠券` API 新增 `couponEventCode` 欄位，發放時機新增 `EVENT_CODE` |
| 2024/04/08 | `查詢商品 EC 主檔` API 新增 `ecStatus`、`memo` 欄位 |
| 2024/01/25 | 1. `建立寵速配訂單` API 新增 `recommendStore` `recommendEmployee` 參數<br>2. `建立線上購訂單` API 新增 `recommendStore` `recommendEmployee` 參數 |
| 2024/01/18 | 1. `查詢會員點數紀錄` API 新增 `_createdAt` 參數<br>2. `查詢會員優惠券紀錄` API 新增 `usedAt` 參數 |
| 2023/12/28 | 更新 `建立寵速配訂單`、`更新寵速配訂單` API |
| 2023/07/20 | 調整文件架構 |
| 2023/06/07 | 1. 新增 `查詢商品會員價` API<br>2. `更新線上購訂單` API 調整欄位說明 |
| 2023/05/23 | 1. `查詢會員`、`更新會員` API 新增欄位<br>2. `查詢會員優惠券紀錄` 新增 **_優惠券名稱_**、**_優惠券活動圖片_** 回傳欄位 |
| 2023/04/25 | `查詢點加金活動`調整回傳欄位中文名稱 兌換品項 -> APP 點加金條碼 |
| 2023/04/21 | `更新寵速配訂單`、`更新線上購訂單` API 新增欄位 |
| 2023/04/11 | `查詢會員優惠券紀錄` API 新增欄位 `App 連結參數` |
| 2023/03/20 | 新增 `查詢會員線下銷售單` API |
| 2023/03/16 | 修改 `查詢點加金活動`、`查詢會員優惠券紀錄` API 回傳欄位說明 |
| 2023/03/15 | 1. 新增 `更新線上購退款單` API<br>2. `maFindItem` API 回傳永久圖片網址 |
| 2023/03/01 | 1. 修改 `建立線上購訂單`、`更新線上購訂單`、`建立線上購退貨單`、`更新線上購退貨單`、`建立寵速配訂單`、`更新寵速配訂單`、`建立寵速配退貨單`、`更新寵速配退貨單` 的狀態欄位參數說明<br>2. `建立寵速配訂單`、`更新寵速配訂單` 移除 **_門店配貨完成時間_** 欄位<br>3. `更新寵速配退貨單` 移除 **_調整加項_** 與 **_調整減項_** 欄位 |
| 2023/02/14 | `maFindItem` API 參數新增 skip 與 limit |
| 2023/02/13 | 新增 `建立寵速配退貨單`、`更新寵速配退貨單` API |
| 2023/02/10 | 新增 `建立線上購訂單`、`更新線上購訂單` API |
| 2023/02/09 | 新增 `建立線上購退款單`、`建立寵速配訂單`、`更新寵速配訂單` API |
| 2023/02/07 | 新增 `建立線上購退貨單`、`更新線上購退貨單` API |
| 2023/01/17 | 1. 查詢會員 API 回傳 recommandStore 欄位命名改為 recommendStore<br>2. 建立會員 API 新增 displayName 參數 |
| 2023/01/13 | 新增 `查詢商品 EC 主檔` API |
| 2023/01/12 | 新增 `查詢主分類` API |
| 2022/12/15 | 新增 `查詢點加金活動` API |
| 2022/12/13 | 新增 `返還點數` API |
| 2022/12/12 | 新增 `查詢會員點數紀錄`、`核銷點數` API |
| 2022/12/09 | 1. 查詢會員 API 回傳新增 `一般會員距離升級金卡差額`、`金卡距離升級黑卡差額`、`金卡維持金卡的差額`、`黑卡維持黑卡的差額` 欄位<br>2. 新增 `查詢會員優惠券紀錄`、`核銷優惠券`、`返還優惠券` API |
| 2022/12/06 | 新增發券 API |
| 2022/12/01 | 文件初版 |