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 整合物流選擇頁面，廠商無需自行製作頁面

支援的功能

物流訂單建立

列印

逆物流

查詢

異動與取消

通知處理

設定

環境變數

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();

測試環境資訊

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

相關資源

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

授權

MIT License