開發者資源

Shopzpin API 文件

這是一份 API 規格文件，為開發者、合作夥伴及商戶提供 Shopzpin 平台的介接參考指南。

1. 概述

本文檔為 Shopzpin 的 API 規格，旨在用於前後端對接、合作夥伴導入或提案用途。 Shopzpin 是一個專注於商戶的 O2O 商業和 CRM 平台，支援：

商家帳號管理
門市/分店管理
會員計畫
獎勵與忠誠度點數
優惠券與促銷
智能點餐
訂單與付款
顧客數據與分析
遊戲化活動互動

2. 基本網址

測試環境 (Sandbox)

text

https://api-sandbox.shopzpin.com/v1

生產環境 (Production)

text

https://api.shopzpin.com/v1

3. 身份驗證

此 API 使用 Bearer Token 進行身份驗證。

請求標頭 (Header)

http

Authorization: Bearer <access_token>
Content-Type: application/json

登入端點

POST/auth/login

請求範例

json

{
  "email": "merchant@brand.com",
  "password": "YourPassword123"
}

成功回應

json

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "merchant_id": "mrc_10001",
    "user": {
      "id": "usr_90001",
      "name": "Shop Manager",
      "role": "admin"
    }
  }
}

4. 標準回應格式

成功回應

json

{
  "success": true,
  "message": "Request completed successfully",
  "data": {}
}

錯誤回應

json

{
  "success": false,
  "message": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "errors": {
    "email": ["The email field is required."]
  }
}

5. 核心資源

商家 (Merchants)員工 (Staff)門市 (Outlets)顧客 (Customers)會員 (Memberships)點數 (Points)優惠券 (Coupons)產品/菜單 (Products)訂單 (Orders)付款 (Payments)活動 (Campaigns)獎勵 (Rewards)分析 (Analytics)

6. 商家端點

6.1 獲取商家資料

GET/merchant/profile

回應範例 (Response)

json

{
  "success": true,
  "data": {
    "merchant_id": "mrc_10001",
    "brand_name": "Demo Cafe",
    "business_type": "F&B",
    "email": "merchant@brand.com",
    "phone": "+60-12-3456789",
    "status": "active",
    "created_at": "2026-04-14T10:00:00Z"
  }
}

6.2 更新商家資料

PUT/merchant/profile

請求範例 (Request)

json

{
  "brand_name": "Demo Cafe Group",
  "phone": "+60-12-8888888",
  "business_type": "Retail & F&B"
}

7. 員工 / 用戶管理

7.1 列出所有員工

GET/staff

查詢參數 (Query Parameters)

pagelimitrole

7.2 新增員工

POST/staff

請求範例 (Request)

json

{
  "name": "Alice Wong",
  "email": "alice@brand.com",
  "role": "cashier",
  "outlet_id": "out_101"
}

8. 門市管理

8.1 列出所有門市

GET/outlets

8.2 新增門市

POST/outlets

請求範例 (Request)

json

{
  "name": "Demo Cafe - Puchong",
  "code": "PCH001",
  "address": "72-1A Jalan Puteri 2/4, Bandar Puteri, Puchong",
  "phone": "+60-16-9642896",
  "status": "active"
}

8.3 獲取門市詳情

GET/outlets/{outlet_id}

8.4 更新門市資料

PUT/outlets/{outlet_id}

8.5 刪除門市

DELETE/outlets/{outlet_id}

9. 顧客管理

9.1 列出所有顧客

GET/customers

查詢參數 (Query Parameters)

pagelimitkeywordmembership_tieroutlet_id

9.2 新增顧客

POST/customers

請求範例 (Request)

json

{
  "name": "Carter Yip",
  "phone": "+852-90000000",
  "email": "carter@example.com",
  "birth_date": "1990-01-01",
  "source": "qr_signup"
}

9.3 獲取顧客詳情

GET/customers/{customer_id}

回應範例 (Response)

json

{
  "success": true,
  "data": {
    "id": "cus_20001",
    "name": "Carter Yip",
    "phone": "+852-90000000",
    "email": "carter@example.com",
    "membership_tier": "Gold",
    "points_balance": 580,
    "total_spent": 2450.00,
    "last_visit_at": "2026-04-13T14:22:10Z"
  }
}

10. 會員與忠誠度

10.1 列出會員等級

GET/memberships/tiers

回應範例 (Response)

json

{
  "success": true,
  "data": [
    {
      "id": "tier_bronze",
      "name": "Bronze",
      "min_spend": 0,
      "benefits": ["Welcome reward"]
    },
    {
      "id": "tier_silver",
      "name": "Silver",
      "min_spend": 1000,
      "benefits": ["Birthday voucher", "Priority promo"]
    },
    {
      "id": "tier_gold",
      "name": "Gold",
      "min_spend": 2000,
      "benefits": ["Extra points", "Exclusive offers"]
    }
  ]
}

10.2 新增忠誠度點數

POST/customers/{customer_id}/points/add

請求範例 (Request)

json

{
  "points": 100,
  "reason": "Purchase reward",
  "reference_no": "ord_50001"
}

10.3 兌換點數

POST/customers/{customer_id}/points/redeem

請求範例 (Request)

json

{
  "points": 200,
  "reward_id": "rw_001"
}

10.4 檢視點數紀錄

GET/customers/{customer_id}/points/ledger

11. 優惠券與促銷

11.1 列出所有優惠券

GET/coupons

11.2 建立優惠券

POST/coupons

請求範例 (Request)

json

{
  "title": "10% OFF Lunch Promo",
  "code": "LUNCH10",
  "discount_type": "percentage",
  "discount_value": 10,
  "valid_from": "2026-04-15T00:00:00Z",
  "valid_to": "2026-05-15T23:59:59Z",
  "usage_limit": 500,
  "applicable_outlet_ids": ["out_101", "out_102"]
}

11.3 驗證優惠券

POST/coupons/validate

請求範例 (Request)

json

{
  "code": "LUNCH10",
  "customer_id": "cus_20001",
  "cart_total": 120.00
}

11.4 停用優惠券

PATCH/coupons/{coupon_id}/disable

12. 產品 / 菜單管理

12.1 列出所有產品

GET/products

12.2 新增產品

POST/products

請求範例 (Request)

json

{
  "name": "Iced Latte",
  "sku": "DRINK-001",
  "category": "Beverage",
  "price": 14.90,
  "status": "active",
  "outlet_ids": ["out_101"]
}

12.3 更新產品

PUT/products/{product_id}

12.4 刪除產品

DELETE/products/{product_id}

13. 智能點餐 / 訂單

13.1 建立訂單

POST/orders

請求範例 (Request)

json

{
  "customer_id": "cus_20001",
  "outlet_id": "out_101",
  "order_type": "pickup",
  "items": [
    {
      "product_id": "prd_101",
      "name": "Iced Latte",
      "qty": 2,
      "unit_price": 14.90
    }
  ],
  "coupon_code": "LUNCH10",
  "notes": "Less sugar"
}

回應範例 (Response)

json

{
  "success": true,
  "data": {
    "order_id": "ord_50001",
    "status": "pending_payment",
    "subtotal": 29.80,
    "discount": 2.98,
    "total": 26.82,
    "currency": "MYR"
  }
}

13.2 獲取訂單詳情

GET/orders/{order_id}

13.3 列出所有訂單

GET/orders

查詢參數 (Query Parameters)

statusoutlet_idcustomer_iddate_fromdate_to

13.4 更新訂單狀態

PATCH/orders/{order_id}/status

請求範例 (Request)

json

{
  "status": "completed"
}

14. 付款

14.1 建立付款意圖

POST/payments/intents

請求範例 (Request)

json

{
  "order_id": "ord_50001",
  "method": "fpx",
  "amount": 26.82,
  "currency": "MYR"
}

回應範例 (Response)

json

{
  "success": true,
  "data": {
    "payment_intent_id": "pay_30001",
    "status": "requires_action",
    "payment_url": "https://pay.shopzpin.com/checkout/pay_30001"
  }
}

14.2 驗證付款

POST/payments/verify

請求範例 (Request)

json

{
  "payment_intent_id": "pay_30001",
  "gateway_reference": "GX99887766"
}

14.3 付款紀錄

GET/payments

15. 遊戲化活動 API

15.1 列出所有活動

GET/campaigns

15.2 建立活動

POST/campaigns

請求範例 (Request)

json

{
  "title": "Spin & Win April",
  "campaign_type": "game_reward",
  "game_type": "spin_wheel",
  "start_at": "2026-04-15T00:00:00Z",
  "end_at": "2026-04-30T23:59:59Z",
  "outlet_ids": ["out_101"],
  "rules": {
    "daily_play_limit": 1,
    "min_purchase": 20
  }
}

15.3 開始遊戲會話

POST/campaigns/{campaign_id}/play

請求範例 (Request)

json

{
  "customer_id": "cus_20001",
  "source": "qr_code"
}

15.4 領取獎勵

POST/campaigns/{campaign_id}/claim

請求範例 (Request)

json

{
  "customer_id": "cus_20001",
  "reward_code": "RWAPRIL88"
}

16. 數據分析

16.1 銷售摘要

GET/analytics/sales-summary

查詢參數 (Query Parameters)

date_fromdate_tooutlet_id

回應範例 (Response)

json

{
  "success": true,
  "data": {
    "gross_sales": 18500.00,
    "net_sales": 17220.00,
    "total_orders": 632,
    "average_order_value": 27.25,
    "new_customers": 87,
    "repeat_customers": 214
  }
}

16.2 顧客洞察

GET/analytics/customers

16.3 活動表現

GET/analytics/campaigns/{campaign_id}

17. Webhooks

Shopzpin 可以將 webhook 事件發送到外部系統。

支援的事件：

order.created
order.completed
payment.success
payment.failed
customer.created
coupon.redeemed
campaign.reward_claimed

Webhook 數據範例：

json

{
  "event": "payment.success",
  "created_at": "2026-04-14T11:30:00Z",
  "data": {
    "payment_intent_id": "pay_30001",
    "order_id": "ord_50001",
    "amount": 26.82,
    "currency": "MYR",
    "status": "success"
  }
}

18. 狀態碼

代碼	含義
200	成功 (OK)
201	已建立 (Created)
400	錯誤請求 (Bad Request)
401	未授權 (Unauthorized)
403	禁止訪問 (Forbidden)
404	未找到 (Not Found)
422	驗證錯誤 (Validation Error)
429	請求過多 (Too Many Requests)
500	內部伺服器錯誤 (Internal Server Error)

19. 頻率限制

預設 API 頻率限制：

100 次請求 / 分鐘 / token

超出限制時的回應：

json

{
  "success": false,
  "message": "Too many requests",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

20. 端到端流程範例

場景：顧客掃描 QR Code、註冊、點餐並獲得獎勵

1
顧客註冊
POST/customers
2
商家 App 獲取顧客資料
GET/customers/{customer_id}
3
顧客下單
POST/orders
4
顧客付款
POST/payments/intents
POST/payments/verify
5
系統標記訂單為已完成
PATCH/orders/{order_id}/status
6
系統發放點數至顧客錢包
POST/customers/{customer_id}/points/add
7
顧客參加活動並領取獎勵
POST/campaigns/{campaign_id}/play
POST/campaigns/{campaign_id}/claim

21. 安全建議

僅使用 HTTPS 傳輸
定期輪換 API 金鑰
為商家員工實施基於角色的存取控制 (RBAC)
記錄所有管理員敏感操作日誌
驗證 Webhook 簽章
必要時為企業商家啟用 IP 白名單

22. 錯誤碼範例

錯誤碼	描述
AUTH_INVALID_CREDENTIALS	登入憑證無效
AUTH_TOKEN_EXPIRED	Token 已過期
VALIDATION_ERROR	請求驗證失敗
CUSTOMER_NOT_FOUND	找不到顧客紀錄
OUTLET_NOT_FOUND	找不到門市紀錄
COUPON_INVALID	優惠券無效
COUPON_EXPIRED	優惠券已過期
ORDER_NOT_FOUND	找不到訂單
PAYMENT_FAILED	付款失敗
CAMPAIGN_NOT_ACTIVE	活動尚未啟用
RATE_LIMIT_EXCEEDED	請求次數過多

23. 版本控制

API 透過網址進行版本控制：

text

/v1

未來的重大更新將發布於：

text

/v2

API 文件導覽

Shopzpin API 文件

1. 概述

2. 基本網址

測試環境 (Sandbox)

生產環境 (Production)

3. 身份驗證

請求標頭 (Header)

登入端點

請求範例

成功回應

4. 標準回應格式

成功回應

錯誤回應

5. 核心資源

6. 商家端點

6.1 獲取商家資料

回應範例 (Response)

6.2 更新商家資料

請求範例 (Request)

7. 員工 / 用戶管理

7.1 列出所有員工

查詢參數 (Query Parameters)

7.2 新增員工

請求範例 (Request)

8. 門市管理

8.1 列出所有門市

8.2 新增門市

請求範例 (Request)

8.3 獲取門市詳情

8.4 更新門市資料

8.5 刪除門市

9. 顧客管理

9.1 列出所有顧客

查詢參數 (Query Parameters)

9.2 新增顧客

請求範例 (Request)

9.3 獲取顧客詳情

回應範例 (Response)

10. 會員與忠誠度

10.1 列出會員等級

回應範例 (Response)

10.2 新增忠誠度點數

請求範例 (Request)

10.3 兌換點數

請求範例 (Request)

10.4 檢視點數紀錄

11. 優惠券與促銷

11.1 列出所有優惠券

11.2 建立優惠券

請求範例 (Request)

11.3 驗證優惠券

請求範例 (Request)

11.4 停用優惠券

12. 產品 / 菜單管理

12.1 列出所有產品

12.2 新增產品

請求範例 (Request)

12.3 更新產品

12.4 刪除產品

13. 智能點餐 / 訂單

13.1 建立訂單

請求範例 (Request)

回應範例 (Response)

13.2 獲取訂單詳情

13.3 列出所有訂單

查詢參數 (Query Parameters)

13.4 更新訂單狀態

請求範例 (Request)

14. 付款

14.1 建立付款意圖

請求範例 (Request)

回應範例 (Response)

14.2 驗證付款

請求範例 (Request)

14.3 付款紀錄

15. 遊戲化活動 API

15.1 列出所有活動

15.2 建立活動

請求範例 (Request)