Shopify Plus 台灣超商取貨物流整合教學：完整技術指南

1# 安裝 Shopify CLI
2npm install -g @shopify/cli @shopify/theme
3
4# 確認版本
5shopify version
6# 預期輸出: @shopify/cli/3.x.x

1curl -X POST \
2  https://your-store.myshopify.com/admin/api/2025-01/carrier_services.json \
3  -H "Content-Type: application/json" \
4  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
5  -d '{
6    "carrier_service": {
7      "name": "台灣超商取貨",
8      "callback_url": "https://your-server.com/api/shopify/carrier-rates",
9      "service_discovery": true
10    }
11  }'

1// routes/carrierRates.js
2const express = require('express');
3const router = express.Router();
4
5router.post('/api/shopify/carrier-rates', (req, res) => {
6  const { rate } = req.body;
7  const destination = rate.destination;
8  
9  // 僅對台灣地址回傳超商選項
10  if (destination.country !== 'TW') {
11    return res.json({ rates: [] });
12  }
13
14  // 計算包裹是否符合超商規格限制
15  // 超商取貨限制：單邊不超過 45cm，長+寬+高 ≤ 105cm，重量 ≤ 5kg
16  const totalWeight = rate.items.reduce((sum, item) => 
17    sum + (item.grams * item.quantity), 0
18  );
19  
20  if (totalWeight > 5000) {
21    return res.json({ rates: [] });
22  }
23
24  const rates = [
25    {
26      service_name: '7-ELEVEN 超商取貨',
27      service_code: 'CVS_711',
28      total_price: '6000', // 60 TWD，以「分」為單位
29      currency: 'TWD',
30      min_delivery_date: getDeliveryDate(2),
31      max_delivery_date: getDeliveryDate(4),
32    },
33    {
34      service_name: '全家超商取貨',
35      service_code: 'CVS_FAMI',
36      total_price: '6000',
37      currency: 'TWD',
38      min_delivery_date: getDeliveryDate(2),
39      max_delivery_date: getDeliveryDate(4),
40    },
41    {
42      service_name: '萊爾富超商取貨',
43      service_code: 'CVS_HILIFE',
44      total_price: '6000',
45      currency: 'TWD',
46      min_delivery_date: getDeliveryDate(2),
47      max_delivery_date: getDeliveryDate(4),
48    }
49  ];
50
51  res.json({ rates });
52});
53
54function getDeliveryDate(daysFromNow) {
55  const date = new Date();
56  date.setDate(date.getDate() + daysFromNow);
57  return date.toISOString();
58}
59
60module.exports = router;

1# 在你的 Shopify app 專案中
2shopify app generate extension --type checkout_ui
3# 選擇 "Checkout" 作為 extension 類型
4# 命名為 "cvs-store-picker"

1# extensions/cvs-store-picker/shopify.extension.toml
2api_version = "2025-01"
3
4[[extensions]]
5type = "ui_extension"
6name = "CVS Store Picker"
7handle = "cvs-store-picker"
8
9  [[extensions.targeting]]
10  module = "./src/Checkout.jsx"
11  target = "purchase.checkout.shipping-option-item.render-after"

1// extensions/cvs-store-picker/src/Checkout.jsx
2import {
3  reactExtension,
4  useShippingOptionTarget,
5  useApplyAttributeChange,
6  Button,
7  Text,
8  BlockStack,
9  InlineStack,
10  Modal,
11} from '@shopify/ui-extensions-react/checkout';
12import { useState } from 'react';
13
14export default reactExtension(
15  'purchase.checkout.shipping-option-item.render-after',
16  () => <CvsStorePicker />
17);
18
19function CvsStorePicker() {
20  const shippingOption = useShippingOptionTarget();
21  const applyAttributeChange = useApplyAttributeChange();
22  const [selectedStore, setSelectedStore] = useState(null);
23
24  // 僅在超商取貨運送方式下顯示
25  const cvsServices = ['CVS_711', 'CVS_FAMI', 'CVS_HILIFE'];
26  if (!cvsServices.includes(shippingOption?.shippingOption?.code)) {
27    return null;
28  }
29
30  const handleStoreSelect = async (store) => {
31    setSelectedStore(store);
32    
33    // 將門市資訊寫入 order attributes
34    await applyAttributeChange({
35      type: 'updateAttribute',
36      key: 'cvs_store_id',
37      value: store.storeId,
38    });
39    await applyAttributeChange({
40      type: 'updateAttribute',
41      key: 'cvs_store_name',
42      value: store.storeName,
43    });
44    await applyAttributeChange({
45      type: 'updateAttribute',
46      key: 'cvs_store_address',
47      value: store.storeAddress,
48    });
49  };
50
51  return (
52    <BlockStack spacing="tight">
53      {selectedStore ? (
54        <InlineStack spacing="base" blockAlignment="center">
55          <Text>取貨門市：{selectedStore.storeName}</Text>
56          <Button
57            kind="plain"
58            onPress={() => openStoreMap(shippingOption.shippingOption.code)}
59          >
60            重新選擇
61          </Button>
62        </InlineStack>
63      ) : (
64        <Button
65          onPress={() => openStoreMap(shippingOption.shippingOption.code)}
66        >
67          選擇取貨門市
68        </Button>
69      )}
70    </BlockStack>
71  );
72}

1npm install ecpay-logistics-sdk
2# 或使用官方提供的 Node.js 範例自行封裝

1// services/ecpayLogistics.js
2const crypto = require('crypto');
3const axios = require('axios');
4
5class ECPayLogistics {
6  constructor() {
7    // 正式環境 URL
8    this.apiUrl = 'https://logistics.ecpay.com.tw/Express/Create';
9    // 測試環境 URL
10    this.testApiUrl = 'https://logistics-stage.ecpay.com.tw/Express/Create';
11    this.merchantId = process.env.ECPAY_MERCHANT_ID;
12    this.hashKey = process.env.ECPAY_HASH_KEY;
13    this.hashIV = process.env.ECPAY_HASH_IV;
14  }
15
16  async createShipment(order) {
17    const cvsType = this.getCvsType(order.attributes);
18    const storeId = this.getAttribute(order.attributes, 'cvs_store_id');
19    
20    const params = {
21      MerchantID: this.merchantId,
22      MerchantTradeNo: `B8${order.order_number}`,
23      MerchantTradeDate: this.formatDate(new Date()),
24      LogisticsType: 'CVS',
25      LogisticsSubType: cvsType, // UNIMART, FAMI, HILIFE
26      GoodsAmount: Math.round(order.total_price),
27      GoodsName: `訂單 #${order.order_number}`,
28      SenderName: '品牌名稱',
29      SenderPhone: '0200000000',
30      ReceiverName: order.shipping_address.name,
31      ReceiverPhone: order.shipping_address.phone,
32      ReceiverStoreID: storeId,
33      ServerReplyURL: 'https://your-server.com/api/ecpay/webhook',
34      IsCollection: order.gateway === 'cod' ? 'Y' : 'N', // 是否代收貨款
35    };
36
37    // 產生檢查碼
38    params.CheckMacValue = this.generateCheckMac(params);
39
40    const response = await axios.post(
41      process.env.NODE_ENV === 'production' ? this.apiUrl : this.testApiUrl,
42      new URLSearchParams(params).toString(),
43      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
44    );
45
46    return this.parseResponse(response.data);
47  }
48
49  generateCheckMac(params) {
50    // 依照綠界規範排序並加密
51    const sorted = Object.keys(params).sort().reduce((acc, key) => {
52      acc[key] = params[key];
53      return acc;
54    }, {});
55
56    let raw = `HashKey=${this.hashKey}`;
57    for (const [key, value] of Object.entries(sorted)) {
58      raw += `&${key}=${value}`;
59    }
60    raw += `&HashIV=${this.hashIV}`;
61
62    const encoded = encodeURIComponent(raw).toLowerCase();
63    return crypto.createHash('md5').update(encoded).digest('hex').toUpperCase();
64  }
65
66  getCvsType(attributes) {
67    const serviceCode = this.getAttribute(attributes, 'shipping_code');
68    const map = {
69      'CVS_711': 'UNIMART',
70      'CVS_FAMI': 'FAMI',
71      'CVS_HILIFE': 'HILIFE',
72    };
73    return map[serviceCode] || 'UNIMART';
74  }
75
76  getAttribute(attributes, key) {
77    const attr = attributes.find(a => a.name === key);
78    return attr ? attr.value : null;
79  }
80
81  formatDate(date) {
82    return date.toISOString().slice(0, 19).replace('T', ' ');
83  }
84}
85
86module.exports = ECPayLogistics;

1// routes/ecpayWebhook.js
2router.post('/api/ecpay/webhook', async (req, res) => {
3  const { MerchantTradeNo, RtnCode, RtnMsg, AllPayLogisticsID } = req.body;
4  
5  // RtnCode 對照（部分常用代碼）
6  // 2067: 包裹已到店
7  // 2073: 消費者已取件
8  // 2074: 包裹已退回
9  
10  const orderNumber = MerchantTradeNo.replace('B8', '');
11  
12  if (RtnCode === '2067') {
13    // 包裹到店 → 可通知消費者
14    await notifyCustomer(orderNumber, '您的包裹已到達取貨門市');
15  }
16  
17  if (RtnCode === '2073') {
18    // 消費者已取件 → 更新 Shopify fulfillment
19    await updateShopifyFulfillment(orderNumber, 'delivered');
20  }
21  
22  // 綠界要求回傳 1|OK
23  res.send('1|OK');
24});
25
26async function updateShopifyFulfillment(orderNumber, status) {
27  const shopify = new Shopify({
28    shopName: process.env.SHOPIFY_STORE,
29    accessToken: process.env.SHOPIFY_ACCESS_TOKEN,
30  });
31  
32  // 透過 order number 查詢訂單
33  const orders = await shopify.order.list({ name: orderNumber });
34  if (orders.length === 0) return;
35  
36  const order = orders[0];
37  const fulfillment = order.fulfillments[0];
38  
39  if (fulfillment) {
40    await shopify.fulfillmentEvent.create(order.id, fulfillment.id, {
41      status: status,
42      message: status === 'delivered' ? '消費者已取件' : '包裹配送中',
43    });
44  }
45}

1// extensions/cvs-validation/src/Checkout.jsx
2import {
3  reactExtension,
4  useCartLines,
5  useShippingOptionTarget,
6} from '@shopify/ui-extensions-react/checkout';
7
8export default reactExtension(
9  'purchase.checkout.block.render',
10  () => <CvsValidation />
11);
12
13function CvsValidation() {
14  const cartLines = useCartLines();
15  const shippingOption = useShippingOptionTarget();
16  
17  const totalWeight = cartLines.reduce((sum, line) => {
18    return sum + (line.merchandise.weight || 0) * line.quantity;
19  }, 0);
20  
21  // 超過 5kg 顯示警告
22  if (totalWeight > 5000 && shippingOption?.shippingOption?.code?.startsWith('CVS')) {
23    return (
24      <Banner status="warning">
25        超商取貨限重 5 公斤，目前商品總重超過限制，請改選宅配。
26      </Banner>
27    );
28  }
29  
30  return null;
31}

1# 測試 Carrier Service 端點
2curl -X POST https://your-server.com/api/shopify/carrier-rates \
3  -H "Content-Type: application/json" \
4  -d '{"rate":{"destination":{"country":"TW","postal_code":"106","province":"Taipei","city":"Taipei","name":"Test"},"items":[{"name":"Test Item","quantity":1,"grams":500,"price":100000}]}}'
5
6# 預期輸出
7# {"rates":[{"service_name":"7-ELEVEN 超商取貨","service_code":"CVS_711",...}]}

1# Shopify Flow 觸發條件（概念描述）
2觸發：Order created
3條件：order.shippingLine.code 包含 "CVS"
4動作：呼叫外部 webhook → your-server.com/api/auto-shipment