taiwan-logistics-skill 1.0.0

package/assets/taiwan-logistics/data/field-mappings.csv

@@ -0,0 +1,27 @@
+field_name,field_zh,ecpay_name,type,required,max_length,format,notes
+merchant_id,商店代號,MerchantID,string,true,10,,
+order_id,訂單編號,MerchantTradeNo,string,true,20,英數字,需唯一
+order_date,訂單日期,MerchantTradeDate,string,true,20,yyyy/MM/dd HH:mm:ss,
+logistics_type,物流類型,LogisticsType,string,true,20,CVS/Home,
+logistics_sub_type,物流子類型,LogisticsSubType,string,true,20,,見代碼表
+ecpay_logistics_id,綠界物流編號,AllPayLogisticsID,string,false,20,,ECPay回傳
+goods_amount,商品金額,GoodsAmount,integer,true,,,
+goods_name,商品名稱,GoodsName,string,true,50,,
+sender_name,寄件人姓名,SenderName,string,true,10,,
+sender_phone,寄件人電話,SenderPhone,string,true,20,,
+sender_cell_phone,寄件人手機,SenderCellPhone,string,false,20,,
+sender_zipcode,寄件人郵遞區號,SenderZipCode,string,false,6,,宅配必填
+sender_address,寄件人地址,SenderAddress,string,false,200,,宅配必填
+receiver_name,收件人姓名,ReceiverName,string,true,10,,
+receiver_phone,收件人電話,ReceiverPhone,string,true,20,,
+receiver_cell_phone,收件人手機,ReceiverCellPhone,string,false,20,,
+receiver_zipcode,收件人郵遞區號,ReceiverZipCode,string,false,6,,宅配必填
+receiver_address,收件人地址,ReceiverAddress,string,false,200,,宅配必填
+receiver_store_id,收件門市代號,ReceiverStoreID,string,false,6,,超商必填
+return_store_id,退貨門市代號,ReturnStoreID,string,false,6,,
+is_collection,是否代收,IsCollection,string,false,1,Y/N,超商適用
+collection_amount,代收金額,CollectionAmount,integer,false,,,
+temperature,溫層,Temperature,string,false,4,0001/0002/0003,宅配適用
+distance,距離,Distance,string,false,2,00/01,00同縣市 01外縣市
+specification,規格,Specification,string,false,4,,包裹尺寸
+server_reply_url,通知網址,ServerReplyURL,string,true,200,URL,

package/assets/taiwan-logistics/data/logistics-types.csv

@@ -0,0 +1,11 @@
+logistics_type,logistics_sub_type,name_zh,provider,type,collection_available,max_amount,size_limit,temperature,notes
+CVS,UNIMART,7-11 B2C,7-11,cvs_b2c,true,20000,45x30x30cm,常溫,大宗寄倉
+CVS,UNIMARTC2C,7-11 店到店,7-11,cvs_c2c,true,20000,45x30x30cm,常溫,C2C 交貨便
+CVS,FAMI,全家 B2C,全家,cvs_b2c,true,20000,45x30x30cm,常溫,大宗寄倉
+CVS,FAMIC2C,全家店到店,全家,cvs_c2c,true,20000,45x30x30cm,常溫,C2C 店到店
+CVS,HILIFE,萊爾富 B2C,萊爾富,cvs_b2c,true,20000,45x30x30cm,常溫,大宗寄倉
+CVS,HILIFEC2C,萊爾富店到店,萊爾富,cvs_c2c,true,20000,45x30x30cm,常溫,C2C 店到店
+CVS,OKMART,OK B2C,OK,cvs_b2c,true,20000,45x30x30cm,常溫,大宗寄倉
+CVS,OKMARTC2C,OK 店到店,OK,cvs_c2c,true,20000,45x30x30cm,常溫,C2C 店到店
+Home,TCAT,黑貓宅急便,黑貓,home,false,200000,150cm,常溫/冷藏/冷凍,宅配到府
+Home,ECAN,宅配通,宅配通,home,false,100000,120cm,常溫,常溫宅配

package/assets/taiwan-logistics/data/operations.csv

@@ -0,0 +1,8 @@
+operation,operation_zh,ecpay_endpoint,method,required_fields,optional_fields,notes
+create_cvs,建立超商取貨訂單,/Express/Create,POST,"MerchantID,MerchantTradeNo,LogisticsType,LogisticsSubType,GoodsAmount,GoodsName,SenderName,SenderPhone,ReceiverName,ReceiverPhone,ReceiverStoreID,ServerReplyURL","IsCollection,CollectionAmount,ReturnStoreID",LogisticsType=CVS
+create_home,建立宅配訂單,/Express/Create,POST,"MerchantID,MerchantTradeNo,LogisticsType,LogisticsSubType,GoodsAmount,GoodsName,SenderName,SenderPhone,SenderAddress,ReceiverName,ReceiverPhone,ReceiverAddress,ServerReplyURL","Temperature,Distance,Specification,ScheduledDeliveryTime",LogisticsType=Home
+map,超商電子地圖,/Express/map,POST,"MerchantID,LogisticsType,LogisticsSubType,ServerReplyURL","IsCollection,ExtraData",開啟門市選擇頁面
+query,查詢物流訂單,/Helper/QueryLogisticsTradeInfo/V2,POST,"MerchantID,TimeStamp","AllPayLogisticsID,MerchantTradeNo",二擇一
+print,列印託運單,/helper/printTradeDocument,POST,"MerchantID,AllPayLogisticsID","LogisticsType,LogisticsSubType",需先建立訂單
+return,逆物流訂單,/Express/ReturnHome,POST,"MerchantID,AllPayLogisticsID,ServerReplyURL","GoodsAmount,SenderName",退貨/換貨
+update_store,更新門市,/Express/UpdateStoreInfo,POST,"MerchantID,AllPayLogisticsID,ReceiverStoreID","CVSPaymentNo,CVSValidationNo",僅限超商取貨

package/assets/taiwan-logistics/data/providers.csv

@@ -0,0 +1,9 @@
+provider,name_zh,name_en,type,api_available,test_merchant_id,test_hash_key,test_hash_iv,test_url,prod_url,features,coverage
+ecpay,綠界物流,ECPay Logistics,aggregator,true,2000132,5294y06JbISpM5x9,v77hoKGq4kWxNNIS,https://logistics-stage.ecpay.com.tw,https://logistics.ecpay.com.tw,"7-11,全家,萊爾富,OK,黑貓,宅配通",全台
+unimart,7-11 交貨便,7-11 ibon,cvs,true,,,,,https://emap.pcsc.com.tw,店到店,全台 5000+ 門市
+fami,全家店到店,FamilyMart,cvs,true,,,,,https://www.famiport.com.tw,店到店,全台 3500+ 門市
+hilife,萊爾富,Hi-Life,cvs,true,,,,,https://www.hilife.com.tw,店到店,全台 1500+ 門市
+okmart,OK 便利商店,OK Mart,cvs,true,,,,,,店到店,全台 900+ 門市
+tcat,黑貓宅急便,t-cat,home,true,,,,https://www.t-cat.com.tw,https://www.t-cat.com.tw,"常溫,冷藏,冷凍",全台
+hct,新竹物流,HCT,home,true,,,,https://www.hct.com.tw,https://www.hct.com.tw,常溫,全台
+pelican,宅配通,Pelican Express,home,true,,,,https://www.pelican.com.tw,https://www.pelican.com.tw,常溫,全台

package/assets/taiwan-logistics/data/status-codes.csv

@@ -0,0 +1,14 @@
+code,status_zh,status_en,category,description,next_action
+300,訂單建立成功,Order Created,success,物流訂單已成功建立,等待出貨
+310,訂單取消,Order Cancelled,cancelled,訂單已取消,
+2030,已交寄,Package Shipped,in_transit,商品已交給物流商,等待配送
+2063,配達完成,Delivered,delivered,宅配已送達收件人,
+2067,消費者取貨完成,Pickup Completed,completed,消費者已至超商取貨,
+2073,退貨中,Return in Progress,returning,退貨流程進行中,
+2074,退貨完成,Return Completed,returned,退貨流程已完成,
+2030,包裹已到店,Arrived at Store,at_store,包裹已送達指定門市,通知取貨
+2031,包裹已取件,Picked Up by Carrier,picked_up,物流商已取件,
+2032,轉運中,In Transit,in_transit,包裹配送中,
+2061,配達失敗,Delivery Failed,failed,配送失敗,聯繫收件人
+2070,包裹已退回,Package Returned,returned,包裹已退回寄件人,
+3001,系統錯誤,System Error,error,系統發生錯誤,聯繫客服

package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py

@@ -0,0 +1,524 @@
+#!/usr/bin/env python3
+"""
+NewebPay 藍新物流 CVS 超商物流 Python 完整範例
+
+依照 taiwan-logistics-skill 最高規範撰寫
+支援: C2C 店到店 (7-11, 全家, 萊爾富, OK)、B2C 大宗寄倉
+
+API 文件: https://www.newebpay.com
+"""
+
+import json
+import hashlib
+import time
+import urllib.parse
+from datetime import datetime
+from typing import Dict, Literal, Optional
+from dataclasses import dataclass, field
+
+try:
+    from Crypto.Cipher import AES
+    from Crypto.Util.Padding import pad, unpad
+    import requests
+    HAS_DEPENDENCIES = True
+except ImportError:
+    HAS_DEPENDENCIES = False
+
+
+@dataclass
+class CVSShipmentData:
+    """CVS 超商物流訂單資料"""
+    merchant_order_no: str
+    lgs_type: Literal['B2C', 'C2C']
+    ship_type: Literal['1', '2', '3', '4']  # 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK
+    receiver_store_code: str
+    receiver_name: str
+    receiver_cell_phone: str
+    receiver_tel: Optional[str] = None
+    goods_amount: int = 0
+    goods_name: str = ''
+    sender_name: Optional[str] = None
+    sender_cell_phone: Optional[str] = None
+    is_collection: Literal['Y', 'N'] = 'N'
+    collection_amount: int = 0
+    note: Optional[str] = None
+
+
+@dataclass
+class CVSShipmentResponse:
+    """CVS 超商物流訂單回應"""
+    success: bool
+    status: str
+    message: str
+    merchant_order_no: str
+    logistics_no: Optional[str] = None
+    cvs_payment_no: Optional[str] = None
+    cvs_validation_no: Optional[str] = None
+    booking_note: Optional[str] = None
+    raw: Dict = field(default_factory=dict)
+
+
+@dataclass
+class StoreMapData:
+    """電子地圖門市查詢資料"""
+    merchant_order_no: str
+    lgs_type: Literal['B2C', 'C2C']
+    ship_type: Literal['1', '2', '3', '4']
+    return_url: str
+    extra_data: Optional[str] = None
+
+
+@dataclass
+class StoreMapCallback:
+    """電子地圖門市選擇回傳"""
+    lgs_type: str
+    ship_type: str
+    merchant_order_no: str
+    store_id: str
+    store_name: str
+    store_addr: str
+    store_tel: str
+    extra_data: str
+    raw: Dict = field(default_factory=dict)
+
+
+class NewebPayCVSLogistics:
+    """
+    NewebPay 藍新物流 CVS 超商物流服務
+
+    認證方式: AES-256-CBC + SHA256
+    加密方式: JSON + AES-256-CBC 加密 + SHA256 驗證
+
+    支援超商:
+    - 1: 7-ELEVEN 統一超商
+    - 2: FamilyMart 全家便利商店
+    - 3: Hi-Life 萊爾富便利商店
+    - 4: OK Mart OK 便利商店
+
+    物流類型:
+    - C2C: 店到店 (店取、店寄)
+    - B2C: 大宗寄倉 (僅 7-11)
+
+    測試環境:
+    - 需至藍新金流申請測試帳號
+    - API URL: https://ccore.newebpay.com/API/Logistic
+    """
+
+    # 測試環境
+    TEST_BASE_URL = 'https://ccore.newebpay.com/API/Logistic'
+
+    # 正式環境
+    PROD_BASE_URL = 'https://core.newebpay.com/API/Logistic'
+
+    def __init__(
+        self,
+        merchant_id: str,
+        hash_key: str,
+        hash_iv: str,
+        is_production: bool = False
+    ):
+        """
+        初始化 NewebPay CVS 物流服務
+
+        Args:
+            merchant_id: 商店代號
+            hash_key: HashKey (32 字元)
+            hash_iv: HashIV (16 字元)
+            is_production: 是否為正式環境 (預設 False)
+
+        Raises:
+            ImportError: 缺少必要套件
+        """
+        if not HAS_DEPENDENCIES:
+            raise ImportError(
+                '需要安裝必要套件:\n'
+                '  pip install pycryptodome requests'
+            )
+
+        self.merchant_id = merchant_id
+        self.hash_key = hash_key.encode('utf-8')
+        self.hash_iv = hash_iv.encode('utf-8')
+        self.base_url = self.PROD_BASE_URL if is_production else self.TEST_BASE_URL
+
+    def aes_encrypt(self, data: str) -> str:
+        """
+        AES-256-CBC 加密
+
+        Args:
+            data: 明文字串
+
+        Returns:
+            str: 加密後的 hex 字串
+        """
+        cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
+        padded_data = pad(data.encode('utf-8'), AES.block_size)
+        encrypted = cipher.encrypt(padded_data)
+        return encrypted.hex()
+
+    def aes_decrypt(self, encrypted_data: str) -> str:
+        """
+        AES-256-CBC 解密
+
+        Args:
+            encrypted_data: 加密的 hex 字串
+
+        Returns:
+            str: 解密後的明文
+
+        Raises:
+            ValueError: 解密失敗
+        """
+        try:
+            cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
+            decrypted = cipher.decrypt(bytes.fromhex(encrypted_data))
+            unpadded = unpad(decrypted, AES.block_size)
+            return unpadded.decode('utf-8')
+        except Exception as e:
+            raise ValueError(f'解密失敗: {str(e)}')
+
+    def generate_hash_data(self, encrypt_data: str) -> str:
+        """
+        產生 HashData (SHA256)
+
+        Args:
+            encrypt_data: 加密後的資料
+
+        Returns:
+            str: SHA256 雜湊值 (大寫)
+        """
+        raw = f"{self.hash_key.decode('utf-8')}{encrypt_data}{self.hash_iv.decode('utf-8')}"
+        return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
+
+    def verify_hash_data(self, encrypt_data: str, hash_data: str) -> bool:
+        """驗證 HashData"""
+        calculated_hash = self.generate_hash_data(encrypt_data)
+        return calculated_hash == hash_data.upper()
+
+    def query_store_map(
+        self,
+        data: StoreMapData,
+    ) -> str:
+        """
+        查詢電子地圖 (門市選擇)
+
+        Args:
+            data: 門市查詢資料 (StoreMapData)
+
+        Returns:
+            str: 重導向網址 (用戶選擇門市)
+
+        Example:
+            >>> store_data = StoreMapData(
+            ...     merchant_order_no='ORD123',
+            ...     lgs_type='C2C',
+            ...     ship_type='1',
+            ...     return_url='https://your-site.com/callback',
+            ... )
+            >>> redirect_url = service.query_store_map(store_data)
+        """
+        # 準備加密資料
+        encrypt_data_obj = {
+            'MerchantOrderNo': data.merchant_order_no,
+            'LgsType': data.lgs_type,
+            'ShipType': data.ship_type,
+            'ReturnURL': data.return_url,
+            'TimeStamp': str(int(time.time())),
+        }
+
+        if data.extra_data:
+            encrypt_data_obj['ExtraData'] = data.extra_data
+
+        # JSON 序列化並加密
+        json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
+        encrypt_data = self.aes_encrypt(json_str)
+        hash_data = self.generate_hash_data(encrypt_data)
+
+        # 準備 API 請求
+        api_data = {
+            'UID_': self.merchant_id,
+            'EncryptData_': encrypt_data,
+            'HashData_': hash_data,
+            'Version_': '1.0',
+            'RespondType_': 'JSON',
+        }
+
+        # 發送請求 (NewebPay 會重導向到門市選擇頁面)
+        response = requests.post(
+            f'{self.base_url}/storeMap',
+            data=api_data,
+            allow_redirects=False,
+            timeout=30,
+        )
+
+        # 回傳重導向網址
+        if response.status_code in [301, 302, 303]:
+            return response.headers.get('Location', '')
+
+        return response.url
+
+    def parse_store_map_callback(
+        self,
+        encrypt_data: str,
+        hash_data: str,
+    ) -> StoreMapCallback:
+        """
+        解析電子地圖回傳資料
+
+        Args:
+            encrypt_data: 加密資料
+            hash_data: 雜湊驗證值
+
+        Returns:
+            StoreMapCallback: 門市選擇結果
+
+        Raises:
+            ValueError: 驗證失敗
+
+        Example:
+            >>> callback = service.parse_store_map_callback(
+            ...     request.form['EncryptData_'],
+            ...     request.form['HashData_']
+            ... )
+            >>> print(f"選擇門市: {callback.store_name}")
+        """
+        # 驗證 HashData
+        if not self.verify_hash_data(encrypt_data, hash_data):
+            raise ValueError('HashData 驗證失敗')
+
+        # 解密資料
+        decrypted_json = self.aes_decrypt(encrypt_data)
+        decrypted = json.loads(decrypted_json)
+
+        return StoreMapCallback(
+            lgs_type=decrypted.get('LgsType', ''),
+            ship_type=decrypted.get('ShipType', ''),
+            merchant_order_no=decrypted.get('MerchantOrderNo', ''),
+            store_id=decrypted.get('StoreID', ''),
+            store_name=decrypted.get('StoreName', ''),
+            store_addr=decrypted.get('StoreAddr', ''),
+            store_tel=decrypted.get('StoreTel', ''),
+            extra_data=decrypted.get('ExtraData', ''),
+            raw=decrypted,
+        )
+
+    def create_shipment(
+        self,
+        data: CVSShipmentData,
+    ) -> CVSShipmentResponse:
+        """
+        建立 CVS 超商物流訂單
+
+        Args:
+            data: CVS 物流訂單資料 (CVSShipmentData)
+
+        Returns:
+            CVSShipmentResponse: 物流訂單回應
+
+        Raises:
+            ValueError: 參數驗證失敗
+            Exception: API 請求失敗
+
+        Example:
+            >>> shipment_data = CVSShipmentData(
+            ...     merchant_order_no='SHIP123',
+            ...     lgs_type='C2C',
+            ...     ship_type='1',
+            ...     receiver_store_code='123456',
+            ...     receiver_name='王小明',
+            ...     receiver_cell_phone='0912345678',
+            ...     goods_amount=500,
+            ...     goods_name='測試商品',
+            ...     is_collection='N',
+            ... )
+            >>> result = service.create_shipment(shipment_data)
+            >>> print(result.logistics_no)
+        """
+        # 參數驗證
+        if len(data.merchant_order_no) > 30:
+            raise ValueError('訂單編號不可超過 30 字元')
+
+        # 準備加密資料
+        encrypt_data_obj = {
+            'MerchantOrderNo': data.merchant_order_no,
+            'LgsType': data.lgs_type,
+            'ShipType': data.ship_type,
+            'ReceiverStoreCode': data.receiver_store_code,
+            'ReceiverName': data.receiver_name,
+            'ReceiverCellPhone': data.receiver_cell_phone,
+            'TimeStamp': str(int(time.time())),
+        }
+
+        # 可選參數
+        if data.receiver_tel:
+            encrypt_data_obj['ReceiverTel'] = data.receiver_tel
+        if data.goods_amount:
+            encrypt_data_obj['GoodsAmount'] = data.goods_amount
+        if data.goods_name:
+            encrypt_data_obj['GoodsName'] = data.goods_name
+        if data.sender_name:
+            encrypt_data_obj['SenderName'] = data.sender_name
+        if data.sender_cell_phone:
+            encrypt_data_obj['SenderCellPhone'] = data.sender_cell_phone
+        if data.is_collection == 'Y':
+            encrypt_data_obj['IsCollection'] = 'Y'
+            encrypt_data_obj['CollectionAmount'] = data.collection_amount
+        if data.note:
+            encrypt_data_obj['Note'] = data.note
+
+        # JSON 序列化並加密
+        json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
+        encrypt_data = self.aes_encrypt(json_str)
+        hash_data = self.generate_hash_data(encrypt_data)
+
+        # 準備 API 請求
+        api_data = {
+            'UID_': self.merchant_id,
+            'EncryptData_': encrypt_data,
+            'HashData_': hash_data,
+            'Version_': '1.0',
+            'RespondType_': 'JSON',
+        }
+
+        # 發送 API 請求
+        try:
+            response = requests.post(
+                f'{self.base_url}/createShipment',
+                data=api_data,
+                timeout=30,
+            )
+            response.raise_for_status()
+            result = response.json()
+        except Exception as e:
+            raise Exception(f'API 請求失敗: {str(e)}')
+
+        # 解析回應
+        if result.get('Status') != 'SUCCESS':
+            return CVSShipmentResponse(
+                success=False,
+                status=result.get('Status', 'ERROR'),
+                message=result.get('Message', '未知錯誤'),
+                merchant_order_no=data.merchant_order_no,
+                raw=result,
+            )
+
+        # 解密回應資料
+        response_encrypt_data = result.get('EncryptData_', '')
+        response_hash_data = result.get('HashData_', '')
+
+        if response_encrypt_data and response_hash_data:
+            try:
+                if not self.verify_hash_data(response_encrypt_data, response_hash_data):
+                    raise ValueError('回應 HashData 驗證失敗')
+
+                decrypted_json = self.aes_decrypt(response_encrypt_data)
+                decrypted = json.loads(decrypted_json)
+            except Exception as e:
+                return CVSShipmentResponse(
+                    success=False,
+                    status='ERROR',
+                    message=f'解密失敗: {str(e)}',
+                    merchant_order_no=data.merchant_order_no,
+                    raw=result,
+                )
+        else:
+            decrypted = {}
+
+        return CVSShipmentResponse(
+            success=True,
+            status=result.get('Status', ''),
+            message=result.get('Message', ''),
+            merchant_order_no=data.merchant_order_no,
+            logistics_no=decrypted.get('LogisticsNo'),
+            cvs_payment_no=decrypted.get('CVSPaymentNo'),
+            cvs_validation_no=decrypted.get('CVSValidationNo'),
+            booking_note=decrypted.get('BookingNote'),
+            raw=result,
+        )
+
+
+# Usage Example
+if __name__ == '__main__':
+    print('=' * 60)
+    print('NewebPay 藍新物流 CVS - Python 範例')
+    print('=' * 60)
+    print()
+
+    # 檢查依賴套件
+    if not HAS_DEPENDENCIES:
+        print('✗ 錯誤: 需要安裝必要套件')
+        print('  請執行: pip install pycryptodome requests')
+        exit(1)
+
+    print('[注意] 請先至藍新金流申請測試帳號')
+    print('並將以下參數替換為您的測試環境資訊')
+    print()
+
+    # 初始化服務 (使用測試環境)
+    service = NewebPayCVSLogistics(
+        merchant_id='YOUR_MERCHANT_ID',
+        hash_key='YOUR_HASH_KEY',  # 32 字元
+        hash_iv='YOUR_HASH_IV',  # 16 字元
+        is_production=False,
+    )
+
+    # 範例 1: 查詢電子地圖 (門市選擇)
+    print('[範例 1] 查詢電子地圖 (門市選擇)')
+    print('-' * 60)
+
+    store_data = StoreMapData(
+        merchant_order_no=f'MAP{int(time.time())}',
+        lgs_type='C2C',
+        ship_type='1',  # 7-ELEVEN
+        return_url='https://your-site.com/callback/store-map',
+        extra_data='order_id=123',
+    )
+
+    try:
+        redirect_url = service.query_store_map(store_data)
+        print(f'✓ 電子地圖網址: {redirect_url}')
+        print('請將使用者導向此網址選擇門市')
+    except Exception as e:
+        print(f'✗ 發生例外: {str(e)}')
+
+    print()
+    print('-' * 60)
+
+    # 範例 2: 建立 C2C 物流訂單
+    print('[範例 2] 建立 C2C 物流訂單')
+    print('-' * 60)
+
+    shipment_data = CVSShipmentData(
+        merchant_order_no=f'SHIP{int(time.time())}',
+        lgs_type='C2C',
+        ship_type='1',  # 7-ELEVEN
+        receiver_store_code='123456',  # 收件門市代號 (從電子地圖取得)
+        receiver_name='王小明',
+        receiver_cell_phone='0912345678',
+        goods_amount=500,
+        goods_name='測試商品',
+        sender_name='賣家',
+        sender_cell_phone='0987654321',
+        is_collection='N',  # 不代收貨款
+    )
+
+    try:
+        result = service.create_shipment(shipment_data)
+
+        if result.success:
+            print(f'✓ 物流訂單建立成功')
+            print(f'  訂單編號: {result.merchant_order_no}')
+            print(f'  物流編號: {result.logistics_no}')
+            print(f'  寄貨編號: {result.cvs_payment_no}')
+            print(f'  驗證碼: {result.cvs_validation_no}')
+            print(f'  托運單號: {result.booking_note}')
+        else:
+            print(f'✗ 物流訂單建立失敗')
+            print(f'  狀態: {result.status}')
+            print(f'  訊息: {result.message}')
+    except Exception as e:
+        print(f'✗ 發生例外: {str(e)}')
+
+    print()
+    print('=' * 60)
+    print('範例執行完成')
+    print('=' * 60)