carllee1983/newebpay-logistics

NewebPay Logistics Integration PHP SDK

v2.1.0 2025-11-29 13:27 UTC

Requires

• php: ^8.3
• ext-json: *
• ext-openssl: *
• guzzlehttp/guzzle: ^7.0
• psr/log: ^1.1

Requires (Dev)

• mockery/mockery: ^1.4
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.7

MIT

• Carl Lee

• shipping
• logistics
• cvs
• Taiwan
• newebpay
• convenience-store

README

繁體中文

A PHP SDK for integrating with NewebPay Logistics API (藍新金流物流 API).

Installation

Install via Composer:

composer require carllee1983/newebpay-logistics

Configuration

Initialize the library with your Merchant ID, Hash Key, and Hash IV:

use CarlLee\NewebPayLogistics\NewebPayLogistics;

$merchantId = 'YOUR_MERCHANT_ID';
$hashKey = 'YOUR_HASH_KEY';
$hashIV = 'YOUR_HASH_IV';

$logistics = NewebPayLogistics::create($merchantId, $hashKey, $hashIV);

Laravel Integration

Installation

1. Publish the configuration file:

php artisan vendor:publish --tag=newebpay-logistics-config

1. Add the following variables to your .env file:

NEWEBPAY_LOGISTICS_MERCHANT_ID=your_merchant_id
NEWEBPAY_LOGISTICS_HASH_KEY=your_hash_key
NEWEBPAY_LOGISTICS_HASH_IV=your_hash_iv
# Optional: Override server URL (default is testing environment)
# NEWEBPAY_LOGISTICS_SERVER_URL=https://core.newebpay.com/API/Logistic

Usage

You can use the NewebPayLogistics facade:

use NewebPayLogistics;

public function map()
{
    $map = NewebPayLogistics::map();
    // ...
}

Usage

1. Map Interface (電子地圖)

Generate the HTML form to redirect the user to the logistics provider's map interface for store selection.

use CarlLee\NewebPayLogistics\FormBuilder;

use CarlLee\NewebPayLogistics\Parameter\LgsType;
use CarlLee\NewebPayLogistics\Parameter\ShipType;

$map = $logistics->map();
$map->setMerchantTradeNo('TRADE' . time());
$map->setLgsType(LgsType::B2C);
$map->setShipType(ShipType::SEVEN_ELEVEN);
$map->setIsCollection('N'); // N: No collection, Y: Collection
$map->setServerReplyURL('https://example.com/reply');

$formBuilder = new FormBuilder();
$html = $formBuilder->build($map);

echo $html;

1-1. Frontend Integration (Vue/React)

If you are using a decoupled frontend/backend architecture (like Vue, React), you can return the form data via API and let the frontend submit the form.

$data = $formBuilder->getFormData($map);

// Return JSON to frontend
echo json_encode($data);

// Output example:
// {
//     "url": "https://ccore.newebpay.com/API/Logistic/map",
//     "method": "post",
//     "params": {
//         "MerchantID_": "...",
//         "PostData_": "...",
//         "TradeSha": "..."
//     }
// }

1-2. Server-side Redirect

Since NewebPay Logistics API (like Map Interface) requires POST data transmission, standard server-side HTTP 302 redirects (header("Location: ...")) cannot be used as they don't carry POST data.

If you want to control the redirect from the server side, use one of the following methods:

1. Auto Submit Form: Use $formBuilder->autoSubmit($map) to generate HTML containing JavaScript that automatically submits the form upon loading.

   // Directly generate auto-submit form HTML
   echo $logistics->generateForm($map);

   Or via FormBuilder (if you need to customize Form ID, etc.):

   $formBuilder = $logistics->getFormBuilder();
   echo $formBuilder->autoSubmit($map);

2. Frontend Submit: As shown in the previous section, return the data to the frontend and let the frontend create and submit the form via JavaScript.

2. Create Order (建立物流訂單)

Create a logistics order (B2C/C2C).

use CarlLee\NewebPayLogistics\Parameter\LgsType;
use CarlLee\NewebPayLogistics\Parameter\ShipType;
use CarlLee\NewebPayLogistics\Parameter\TradeType;

$create = $logistics->createOrder();
$create->setMerchantTradeNo('TRADE' . time());
$create->setLgsType(LgsType::B2C);
$create->setShipType(ShipType::SEVEN_ELEVEN);
$create->setTradeType(TradeType::PAYMENT);
$create->setReceiverName('Test Receiver');
$create->setReceiverPhone('0912345678');
$create->setReceiverCellPhone('0912345678');
// ... set other parameters

// $response = $logistics->send($create);

3. Query Order (查詢物流訂單)

Query the status of a logistics order.

$query = $logistics->query();
$query->setLogisticsID('LOGISTICS_ID');
$query->setMerchantTradeNo('TRADE_NO');

// $response = $logistics->send($query);

4. Print Order (列印託運單)

Generate the interface for printing the shipping label.

$print = $logistics->printOrder();
$print->setLogisticsID('LOGISTICS_ID');
$print->setMerchantTradeNo('TRADE_NO');

// $response = $logistics->send($print);

Examples

Check the examples/ directory for complete example scripts:

• Map Operation
• Create Order
• Query Order
• Print Order

Testing

To run the unit tests:

vendor/bin/phpunit

Development with Docker

This project supports development using Docker, which provides a consistent PHP 8.3 environment.

Prerequisites

• Docker
• Docker Compose

Usage

1. Build the Docker image:

   docker-compose build

2. Run Composer commands:

   docker-compose run --rm php composer install

3. Run tests:

   docker-compose run --rm php vendor/bin/phpunit

4. Enter the container shell:

   docker-compose run --rm php bash

License

MIT