carllee1983/ecpay-fulllogistics

綠界科技全方位物流服務 PHP SDK

v1.0.0 2025-11-27 14:18 UTC

Requires

• php: ^8.3
• ext-json: *
• ext-openssl: *
• carllee1983/ecpay-core: ^1.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Carl Lee

• post
• shipping
• logistics
• cvs
• Taiwan
• B2C
• ecpay
• c2c
• convenience-store
• 7-eleven
• family-mart
• hilife
• tcat

README

綠界科技全方位物流服務 PHP SDK

安裝

composer require carllee1983/ecpay-fulllogistics

環境需求

• PHP 8.3+
• OpenSSL 擴展
• JSON 擴展
• TLS 1.2 支援（綠界僅支援 TLS 1.2 以上加密通訊協定）

重要注意事項

安全性警告

• 請勿將 HashKey/HashIV 存放或顯示於前端網頁（如 JavaScript、HTML、CSS），避免金鑰被盜取造成損失及資料外洩
• 務必透過環境變數或設定檔管理金鑰，確保不納入版本控制

API 特點

• 資料傳遞格式採用 JSON 及 AES-128-CBC 加密機制
• 導入暫存訂單機制，適合結帳後仍有修改部分出貨資訊需求的廠商
• 採用 RWD 整合物流選擇頁面，廠商無需自行製作頁面

支援的功能

物流訂單建立

類別	別名	說明
OpenLogisticsSelection	selection	開啟物流選擇頁
UpdateTempTrade	temp	更新暫存物流訂單
CreateLogisticsOrder	create	建立正式物流訂單
GenerateB2CTestData	test_data	B2C 一段標測試資料產生

列印

類別	別名	說明
PrintTradeDocument	print	列印託運單

逆物流

類別	別名	說明
ReturnUnimart	return_unimart	7-ELEVEN 逆物流 (B2C)
ReturnFami	return_fami	全家逆物流 (B2C)
ReturnHilife	return_hilife	萊爾富逆物流 (B2C)
ReturnHome	return_home	宅配逆物流

查詢

類別	別名	說明
QueryLogisticsOrder	query	查詢物流訂單

異動與取消

類別	別名	說明
UpdateB2COrder	update_b2c	異動訂單 (B2C)
UpdateC2COrder	update_c2c	異動訂單 (C2C)
CancelC2COrder	cancel	取消訂單 (C2C)

通知處理

類別	說明
LogisticsNotify	物流狀態通知
ReverseLogisticsNotify	逆物流狀態通知

設定

環境變數

ECPAY_FULLLOGISTICS_SERVER=https://logistics-stage.ecpay.com.tw
ECPAY_FULLLOGISTICS_MERCHANT_ID=your_merchant_id
ECPAY_FULLLOGISTICS_HASH_KEY=your_hash_key
ECPAY_FULLLOGISTICS_HASH_IV=your_hash_iv

Laravel 整合

發布設定檔：

php artisan vendor:publish --provider="CarlLee\EcPayFullLogistics\Laravel\EcPayFullLogisticsServiceProvider"

基本用法

開啟物流選擇頁

use CarlLee\EcPayFullLogistics\Factories\OperationFactory;
use CarlLee\EcPayFullLogistics\Parameter\LogisticsType;

$factory = new OperationFactory([
    'merchant_id' => 'your_merchant_id',
    'hash_key' => 'your_hash_key',
    'hash_iv' => 'your_hash_iv',
]);

$selection = $factory->make('selection')
    ->setMerchantTradeNo('ORDER_' . time())
    ->setLogisticsType(LogisticsType::CVS)
    ->setGoodsAmount(1000)
    ->setGoodsName('測試商品')
    ->setSenderName('寄件人')
    ->setSenderCellPhone('0912345678')
    ->setServerReplyURL('https://your-domain.com/logistics/callback');

$response = $selection->send();

if ($response->isSuccess()) {
    $tempLogisticsId = $response->getTempLogisticsID();
    // 處理成功邏輯
}

建立正式物流訂單

use CarlLee\EcPayFullLogistics\Parameter\LogisticsSubType;

$order = $factory->make('create')
    ->setMerchantTradeNo('ORDER_' . time())
    ->setLogisticsSubType(LogisticsSubType::UNIMART_C2C)  // 7-ELEVEN C2C
    ->setGoodsAmount(1000)
    ->setGoodsName('測試商品')
    ->setSenderName('寄件人')
    ->setSenderCellPhone('0912345678')
    ->setReceiverName('收件人')
    ->setReceiverCellPhone('0987654321')
    ->setReceiverStoreID('991182')
    ->setServerReplyURL('https://your-domain.com/logistics/callback');

$response = $order->send();

if ($response->isSuccess()) {
    $logisticsId = $response->getAllPayLogisticsID();
    $validationNo = $response->getCVSValidationNo();
}

從暫存訂單建立正式訂單

$order = $factory->make('create')
    ->fromTempTrade($tempLogisticsId);

$response = $order->send();

處理物流狀態通知

use CarlLee\EcPayFullLogistics\Notifications\LogisticsNotify;

$notify = new LogisticsNotify($hashKey, $hashIV);
$notify->handle($_POST);

if ($notify->isSuccess()) {
    $logisticsId = $notify->getAllPayLogisticsID();
    $status = $notify->getLogisticsStatus();

    // 更新訂單狀態

    echo $notify->getSuccessResponse(); // 1|OK
}

查詢物流訂單

$query = $factory->make('query')
    ->setAllPayLogisticsID('1234567890');

$response = $query->send();

if ($response->isSuccess()) {
    $status = $response->getLogisticsStatus();
    $statusName = $response->getLogisticsStatusName();
}

列印託運單

// 單筆列印
$print = $factory->make('print')
    ->setAllPayLogisticsID('1234567890');

// 批次列印
$print = $factory->make('print')
    ->batch(['1234567890', '1234567891']);

$response = $print->send();
$printUrl = $response->getPrintUrl();

Laravel 使用方式

use CarlLee\EcPayFullLogistics\Laravel\Facades\EcPayFullLogistics;

// 使用 Facade
$selection = EcPayFullLogistics::make('selection')
    ->setMerchantTradeNo('ORDER_' . time())
    ->setLogisticsType(LogisticsType::CVS)
    // ...

$response = $selection->send();

測試環境資訊

類型	特店編號	HashKey	HashIV
C2C	2000132	5294y06JbISpM5x9	v77hoKGq4kWxNNIS
B2C	2000933	XBERn1YOvpM9nfZc	h1ONHk4P4yqbl5LK

測試環境網址：https://logistics-stage.ecpay.com.tw 正式環境網址：https://logistics.ecpay.com.tw

相關資源

• 全方位物流服務API技術文件
• 綠界特店管理後台（測試）

授權

MIT License