iT邦幫忙

2018 iT 邦幫忙鐵人賽
DAY 17
1

物流串接

前面介紹了許多金流串接的方法,今天就來試試和歐付寶同集團 - 綠界科技提供的物流串接吧。

綠界提供的技術支援和歐付寶有87%像,但除了一般的 API,綠界這邊還多了 Apple Pay、Android Pay 和物流整合 讓開發者可以串接到自己站上。

技術支援

和歐付寶一樣,綠界也提供官方物流整合API及SDK介接規格,合作特店會員可以用來建立物流訂單、電子地圖串接、逆物流訂單等介接。超商取貨付款服務包含「全家便利超商」、「統一超商」、「萊爾富」;宅配服務則有「黑貓宅急便」、「宅配通」。

物流整合串接 SDK 程式(PHP版)
( 文件另有 Ruby, Node.js, Java 版本)

物流整合API技術文件

物流貨態代碼檔

  • 產生訂單介接流程
    物流流程

電子地圖串接(超商取貨時選擇取貨分店)

測試環境:https://logistics-stage.ecpay.com.tw/Express/map

參數 參數名稱 型態 說明 範例
*MerchantID 廠商編號 String(10) 測試編號 2000132
*LogisticsType 物流類型 String(20) CVS:超商取貨 CVS
*LogisticsSubType 物流子類型 String(20) B2C(FAMI:全家,UNIMART:統一超商,HILIFE:萊爾富);C2C(FAMIC2C:全家店到店,UNIMARTC2C:統一超商交貨便,HILIFEC2C:萊爾富店到店) UNIMART
*IsCollection 是否代收貨款 String(1) N:不代收貨款,Y:代收貨款。 N
*ServerReplyURL Server 端回覆網址 String(200) 取得超商店鋪代號等資訊後,會回傳到此網址。 http://test.com.tw/return.php

首先要 include 官方提供的 SDK 文件

include('../SDK/ECPay.Logistics.Integration.php');

產生物流 SDK 物件

$AL = new ECPayLogistics();
$AL->Send = array(
    'MerchantID' => '2000132',
    'MerchantTradeNo' => 'no' . date('YmdHis'),
    'LogisticsSubType' => LogisticsSubType::UNIMART,
    'IsCollection' => IsCollection::NO,
    'ServerReplyURL' => 'http://testec.com.tw/ServerReplyURL.php',
    'ExtraData' => '測試額外資訊',
    'Device' => Device::PC
);

呼叫 CvsMap('submitButtonText') 會回傳一個包裝好的 html form,裡面會有剛剛使用ECPayLogistics::Send()設定好的參數資訊。

$html = $AL->CvsMap('選擇取貨門市');
echo $html;

可以直接 echo 出來

<div style="text-align:center;">
  <form id="ECPayForm" method="POST" action="https://logistics-stage.ecpay.com.tw/Express/map" target="_self">
    <input type="hidden" name="MerchantID" value="2000132" />
    <input type="hidden" name="MerchantTradeNo" value="no20171226140813" />
    <input type="hidden" name="LogisticsSubType" value="UNIMART" />
    <input type="hidden" name="IsCollection" value="N" />
    <input type="hidden" name="ServerReplyURL" value="http://www.sample.com.tw/logistics_dev/ServerReplyURL.php" />
    <input type="hidden" name="ExtraData" value="測試額外資訊" />
    <input type="hidden" name="Device" value="0" />
    <input type="hidden" name="LogisticsType" value="CVS" />
    <input type="submit" id="__paymentButton" value="選擇取件門市" />
  </form>
</div>

submit 之後會來到選取門市的電子地圖,但測試環境會直接指定好預設門市。
select_store

確定門市後會導到 'ServerReplyURL' 的網址,POST 的資料內容會有使用者選取的門市資訊。

array(8) {
  ["MerchantID"] => "2000132"
  ["MerchantTradeNo"] => "ECPay"
  ["LogisticsSubType"] => "UNIMART"
  ["CVSStoreID"] => "991182"
  ["CVSStoreName"] => "馥樺門市"
  ["CVSAddress"] => "台北市南港區三重路23號1樓"
  ["CVSTelephone"] => ""
  ["ExtraData"] => "測試額外資訊"
}

物流訂單產生

測試環境:https://logistics-stage.ecpay.com.tw/Express/Create

參數 參數名稱 型態 說明 範例
*MerchantID 廠商編號 String(10) 測試編號 2000132
*MerchantTradeDate 會員交易時間 String(20) 格式為:yyyy/MM/dd HH:mm:ss 2012/03/21 15:40:18
*LogisticsType 物流類型 String(20) CVS:超商取貨;Home:宅配 CVS
*LogisticsSubType 物流子類型 String(20) B2C(FAMI:全家,UNIMART:統一超商,HILIFE:萊爾富);C2C(FAMIC2C:全家店到店,UNIMARTC2C:統一超商交貨便,HILIFEC2C:萊爾富店到店);HOME(TCAT:黑貓,ECAN:宅配通) UNIMART
*GoodsAmount 商品金額 Int UNIMART/UNIMARTC2C(1~19,999);其餘子類型(1~20,000) 5000
*SenderName 寄件人姓名 String(10) 字元限制為 10 個字元 小露露
*ReceiverName 收件人姓名 String(10) 字元限制為 10 個字元 小露露
*ServerReplyURL Server 端回覆網址 String(200) 物流狀態都會透過此 URL 通知 http://test.com.tw/receive.php
*CheckMacValue 檢查碼 String 請參照 API 文件(若使用 SDK 則不需要)

一樣先建立物流 SDK 物件,但需要設定測試用 HashKey/HashIV。

$AL = new ECPayLogistics();
$AL->HashKey = '5294y06JbISpM5x9';
$AL->HashIV = 'v77hoKGq4kWxNNIS';

再來是依據 API 規範將資料填入。其中'MerchantTradeNo'若為空,server 會自動生成一組編號;'ServerReplyURL'則是所有物流狀態更新時,server 會 POST 通知的頁面。

$AL->Send = array(
    'MerchantID' => '2000132',
    'MerchantTradeNo' => 'no' . date('YmdHis'),
    'MerchantTradeDate' => date('Y/m/d H:i:s'),
    'LogisticsType' => LogisticsType::CVS,
    'LogisticsSubType' => LogisticsSubType::UNIMART,
    'GoodsAmount' => 1500,
    'CollectionAmount' => 10,
    'IsCollection' => IsCollection::YES,
    'GoodsName' => '測試商品',
    'SenderName' => '測試寄件者',
    'SenderPhone' => '0226550115',
    'SenderCellPhone' => '0911222333',
    'ReceiverName' => '測試收件者',
    'ReceiverPhone' => '0226550115',
    'ReceiverCellPhone' => '0933222111',
    'ReceiverEmail' => 'test_emjhdAJr@test.com.tw',
    'TradeDesc' => '測試交易敘述',
    'ServerReplyURL' => HOME_URL . '/ServerReplyURL.php',
    'LogisticsC2CReplyURL' => HOME_URL . '/LogisticsC2CReplyURL.php',
    'Remark' => '測試備註',
    'PlatformID' => '',
);
//當物流類型[LogsticsType]為 CVS 時
$AL->SendExtend = array(
 'ReceiverStoreID' => '991182', //*收件人門市代號
 'ReturnStoreID' => '991182'//退貨門市代號
);

//當物流類型[LogsticsType]為 宅配 時
$AL->SendExtend = array(
 'SenderZipCode' => '123', //*寄件人郵遞區號
 'SenderAddress' => '台北市南港區三重路19-2號6樓之2',//*寄件人地址
 'ReceiverZipCode' => '234', //*收件人郵遞區號
 'ReceiverAddress' => '新北市北港區四重路55-2號6樓之2', //*寄件人地址
 'Temperature' => '0001', //*溫層
 'Distance' => '01', //*距離
 'Specification' => '0001' //*規格
);

若訂單資料成功建立則會收到

Array
(
    [ResCode] => 1
    [AllPayLogisticsID] => 83990
    [BookingNote] => 
    [CheckMacValue] => 8C6A31B21CEDA6865306DDE58FE2A30F
    [CVSPaymentNo] => 
    [CVSValidationNo] => 
    [GoodsAmount] => 1500
    [LogisticsSubType] => UNIMART
    [LogisticsType] => CVS
    [MerchantID] => 2000132
    [MerchantTradeNo] => no20171227130645
    [ReceiverAddress] => 
    [ReceiverCellPhone] => 0933222111
    [ReceiverEmail] => test_emjhdAJr@test.com.tw
    [ReceiverName] => 測試收件者
    [ReceiverPhone] => 0226550115
    [RtnCode] => 300
    [RtnMsg] => 訂單處理中(已收到訂單資料)
    [UpdateStatusDate] => 2017/12/28 02:05:43
)

上一篇
Day 15 - 歐付寶 (4) 信用卡付款
下一篇
Day 17 - 歐付寶 (6) 物流串接-2
系列文
使用PHP串接金流相關API30

尚未有邦友留言

立即登入留言