README

Laravel Ezship Api - 台湾便利配非官方套件

由hosomikai制作，倾注爱心hosomikai

laravel需求

安装

1. 需求包

创建新的Laravel应用程序和composer设置后，可以使用以下命令包含包

$ composer require hosomikai/laravel-ezship

2. 发布

php artisan vendor:publish --provider="Hosomikai\Ezship\EzshipServiceProvider"

3. 添加你的.env

EZSHIP_APP_ID={YOUR_EZSHIP_APP_ID}
EZSHIP_RETURN_URL=${APP_URL}/ezship
EZSHIP_MAP_REDIRECT_URL=${APP_URL}/ezship_map

如果你想加载demo示例 config/app.php

'providers' => [
    ...
    Hosomikai\Ezship\EzshipDemoServiceProvider::class,
]

设置完成后，浏览 https://:8000/ezship/order

用法

1. 设置返回网址

routes/web.php

    Route::get('ezship', 'EzshipController@handle');

注意：需要将你的ezship路由网址注册到VerifyCsrfToken中间件的$except中，以过滤post方法

EzshipController

    use Illuminate\Http\Request;
    use Hosomikai\Ezship\EzshipResponse;

    ...

    public function handle(Request $request)
    {
        $response = new EzshipResponse($request->all());

        //your handle or just default
        //you can redirect your handle page or 
        //if you use api to get this response
        //just return response object

        return $response;
    }

2. 宅配串接

    use Ezship
    ...

    $orderId = now()->format('YmdHis');                     //商店訂單編號                 
    $amount = 100;                                          //包裹價值金額或代收金額
    $needPay = true;                                        //是否需要代收款(取貨付款或單純取貨)
    $recipientName = 'hosomikai';                           //取貨人或收件人姓名(需與收件人證件姓名一致)
    $recipientEmail = 'service@hosomikai.com';              //取貨人或收件人信箱
    $recipientMobile = '0953539459';                        //取貨人或收件人電話
    $zipCode = '104';                                       //收貨人郵遞區號
    $recipientAddr = '12, No. 80號復興北路中山區台北市104';     //收貨人地址

    $order = Ezship::newOrder($amount, $needPay, $orderId)
                ->recipient($recipientName', $recipientMobile, $recipientEmail')
                ->homeDelivery($zipCode, $recipientAddr);

    
    //post by redirect form
    return $order->checkout();

3. 超商取货串接

生成电子地图链接

    use Hosomikai\Ezship\EzshipMapGenerator;

    //你想夾帶回來的參數
    $params = [
        //
    ];

    //運用此api產生的連結 選擇取貨超商
    $mapUrl = $mapGenerator
            ->withWebParams($params)
            ->mapUrl();

routes/web.php

Route::post('ezship_map', 'EzshipController@handleMap');

EzshipController

    use Illuminate\Http\Request;
    use Illuminate\Support\Arr;
    use Hosomikai\Ezship\EzshipMapResponse;
    ...

    public function handleMap(Request $request)
    {
        $mapResponse = new EzshipMapResponse($request->all());

        if ($mapResponse->fails()) {
            //handle fail
            return;
        }

        //成功選取的超商完整代碼
        $strCode = $mapResponse->getStoreCode()();
        
        //當時夾帶的 回來需要判別的使用的參數
        $yourparams = $mampResponse->getWebPara();

        //....
        // handle your flow
    }

新建超商取货订单

    use Ezship
    use Hosomikai\Ezship\EzshipResponse;
    ...

    $orderId = now()->format('YmdHis');                     //商店訂單編號                 
    $amount = 100;                                          //包裹價值金額或代收金額
    $needPay = true;                                        //是否需要代收款(取貨付款或單純取貨)
    $recipientName = 'hosomikai';                           //取貨人或收件人姓名(需與收件人證件姓名一致)
    $recipientEmail = 'service@hosomikai.com';              //取貨人或收件人信箱
    $recipientMobile = '0953539459';                        //取貨人或收件人電話
    $stCode = 'yourstcode';                                 //code you get from (EzshipMapResponse)->getStoreCode();

    $order = Ezship::newOrder($amount, $needPay, $orderId)
                ->recipient($recipientName', $recipientMobile, $recipientEmail')
                ->toStore($stCode);

    
    //post by redirect form
    return $order->checkout();
    ....

4. Hosomikai\Ezship\Contracts\EzshipOrder

可以在env中设置

EZSHIP_NEW_ORDER_STATUS_STORE=
EZSHIP_NEW_ORDER_STATUS_HOME_DELIVERY=

或者你可以发布配置并在config/ezship.php:中更改

    ...

    /**
     * 建立新訂單狀態類型.
     */
    'order_status' => [
        'store' => env('EZSHIP_NEW_ORDER_STATUS_STORE', EzshipOrderStatusConstant::STORE_NEW_TYPE2),                      //超取新訂單狀態類型
        'home_delivery' => env('EZSHIP_NEW_ORDER_STATUS_HOME_DELIVERY', EzshipOrderStatusConstant::HOME_DELIVERY_TYPE2),  //宅配新訂單狀態類型
    ],

5. 查询物流配送状态

    $snId = '3514114054';

    //this will return EzshipResponse object (by our config before)
    $order = Ezship::queryBySnId($snId);

    // return data

参考资料

台湾便利通/Ezship

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

待办事项

• 查询自动查询物流状态
• 触发事件
• 记录ezship配送log
• 内容完善校正
• 测试
• web params exception
• 优化返回response model