tringuyenduc2903/goshipvietnam-laravel

GoShip SDK for Laravel framework (Only Vietnam Support)

v1.0.2 2025-08-29 04:03 UTC

Requires

• php: ^8.3
• ext-curl: *
• ext-readline: *
• bensampo/laravel-enum: ^6.12
• guzzlehttp/guzzle: ^7.9
• illuminate/contracts: ^10.0||^11.0||^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^2.0||^3.0
• pestphp/pest-plugin-arch: ^2.5||^3.0
• pestphp/pest-plugin-laravel: ^2.0||^3.0
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0
• spatie/laravel-ray: ^1.35

MIT

• Tri Nguyen Duc (Bee Tech - PHP)

• laravel
• Beetech Asia
• goshipvietnam-laravel

README

Installation

You can install the package via composer:

composer require tringuyenduc2903/goshipvietnam-laravel

You can publish the config file with:

php artisan vendor:publish --tag="goshipvietnam-config"

This is the contents of the published config file:

return [
    'url' => env('GOSHIP_API_URL', 'https://api.goship.io'),
    'jwt' => env('GOSHIP_JWT', ''),
    'username' => env('GOSHIP_USERNAME', ''),
    'password' => env('GOSHIP_PASSWORD', ''),
    'client_id' => env('GOSHIP_CLIENT_ID', ''),
    'client_secret' => env('GOSHIP_CLIENT_SECRET', ''),
];

Giải thích

• url: Môi trường phát triển tích hợp (Sandbox: https://sandbox.goship.io, Production: https://api.goship.io)
• jwt: Access Token (Sử dụng cho Phương thức Lấy Access Token trực tiếp)
• username: Email (Sử dụng cho Phương thức Sử dụng tài khoản developer)
• password: Mật khẩu (Sử dụng cho Phương thức Sử dụng tài khoản developer)
• client_id: Client ID (Sử dụng cho Phương thức Sử dụng tài khoản developer)
• client_secret: Client secret (Sử dụng cho Xác thực webhook và Phương thức Sử dụng tài khoản developer)

File .env:

• Đối với Lấy Access Token trực tiếp:

GOSHIP_API_URL=https://api.goship.io/api/v2
GOSHIP_JWT=
GOSHIP_CLIENT_SECRET=

• Đối với Sử dụng tài khoản developer:

GOSHIP_API_URL=https://api.goship.io/api/v2
GOSHIP_USERNAME=
GOSHIP_PASSWORD=
GOSHIP_CLIENT_ID=
GOSHIP_CLIENT_SECRET=

Usage

Đăng nhập

use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'username' => config('goshipvietnam.username'),
    'password' => config('goshipvietnam.password'),
    'client_id' => config('goshipvietnam.client_id'),
    'client_secret' => config('goshipvietnam.client_secret'),
];
GoShip::login($data);

Lấy tất cả tỉnh/thành phố

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getCities();

Lấy danh sách quận/huyện theo mã tỉnh/thành phố

use BeetechAsia\GoShip\Facades\GoShip;

$cityId = 100000;
GoShip::getDistrictsByCityId($cityId);

Lấy danh sách quận/huyện

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getDistricts();

Lấy tất cả phường/xã theo mã quận/huyện

use BeetechAsia\GoShip\Facades\GoShip;

$districtId = 100100;
GoShip::getWardsByDistrictId($districtId);

Lấy danh sách khách hàng

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getCustomers();

Tìm kiếm một khách hàng

use BeetechAsia\GoShip\Facades\GoShip;

$q = '[e-mail]'; // q có thể nhận giá trị của các trường id, name, email hoặc phone.
GoShip::searchCustomer($q);

Tạo mới một khách hàng

use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'name' => 'Trần Văn C',
    'email' => '[e-mail]', // Không bắt buộc
    'phone' => '0902001002',
    'address' => [
        'street' => '1102 Hàng Khay',
        'district' => '100100',
        'city' => '100000',
    ],
];
GoShip::createCustomer($data);

Cập nhật thông tin khách hàng

use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'name' => 'Trần Văn C',
    'email' => '[e-mail]', // Không bắt buộc
    'phone' => '0902001002',
];
GoShip::updateCustomer($data);

Xóa thông tin khách hàng

use BeetechAsia\GoShip\Facades\GoShip;

$customerId = 'elpomgr8';
GoShip::deleteCustomer('elpomgr8');

Lấy biểu phí vận chuyển

use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'shipment' => [
        'address_from' => [
            'district' => '100100',
            'city' => '100000',
        ],
        'address_to' => [
            'district' => '100100',
            'city' => '100000',
        ],
        'parcel' => [
            'cod' => 500000, // Không bắt buộc
            'amount' => 500000, // Không bắt buộc
            'width' => 10,
            'height' => 10,
            'length' => 10,
            'weight' => 750,
        ],
    ],
];
GoShip::getRates($data);

Danh sách Vận đơn

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getShipments();

Tìm kiếm Vận đơn

use BeetechAsia\GoShip\Facades\GoShip;

// Tìm kiếm theo id, order_id hoặc carrier_code
$q = 'GS8KOV152L';
GoShip::searchShipment($q);

// Tìm kiếm theo thời gian bắt đầu và thời gian kết thúc
$start_date = '2025-08-08';
$end_date = '2025-08-15';
GoShip::searchShipment(start_date: $start_date, end_date: $end_date);

Tạo mới Vận đơn

use BeetechAsia\GoShip\Enums\Payer;
use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'shipment' => [
        'rate' => 'MTRfMTFfMTAwMg==',
        'payer' => Payer::CUSTOMER,
        'order_id' => '02846e55e191c5706a5021191563c2a6',
        'address_from' => [
            'name' => 'Nguyễn Văn A',
            'phone' => '0913131313',
            'street' => '195 Đ. Thạch Bàn',
            'ward' => '64',
            'district' => '100100',
            'city' => '100000',
        ],
        'address_to' => [
            'name' => 'Trần Văn B',
            'phone' => '0912121212',
            'street' => '51 Lê Đại Hành',
            'ward' => '63',
            'district' => '100100',
            'city' => '100000',
        ],
        'parcel' => [
            'cod' => 500000, // Không bắt buộc
            'amount' => 500000, // Không bắt buộc
            'width' => 10,
            'height' => 10,
            'length' => 10,
            'weight' => 750,
            'metadata' => 'Hàng dễ vỡ, vui lòng nhẹ tay.', // Không bắt buộc
        ],
    ],
];
GoShip::createShipment($data);

Xóa Vận đơn

use BeetechAsia\GoShip\Facades\GoShip;

$shipmentId = 'GS6AYEDVZ6';
GoShip::deleteShipment($shipmentId);

Danh sách các phiên đối soát COD

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getInvoices();

Tìm kiếm phiên đối soát COD

use BeetechAsia\GoShip\Facades\GoShip;

// Tìm kiếm theo mã phiên đối soát COD
$code = 'FA13HEUD';
GoShip::searchInvoice($code);

// Tìm kiếm theo thời gian bắt đầu và thời gian kết thúc
$from = '2025-08-08';
$to = '2025-08-15';
GoShip::searchInvoice(from: $from, to: $to);

Tìm kiếm danh sách Vận đơn theo mã phiên đối soát COD

use BeetechAsia\GoShip\Facades\GoShip;

$invoiceId = 'HDF9D9SS';
GoShip::getShipmentByInvoiceId($invoiceId);

Lấy tất cả thông tin giao dịch

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getTransactions();

Tìm kiếm giao dịch

use BeetechAsia\GoShip\Facades\GoShip;

// Tìm kiếm theo mã giao dịch
$code = 'GSox6or6q5';
GoShip::searchTransaction($code)

// Tìm kiếm theo thời gian bắt đầu và thời gian kết thúc
$from = '2025-08-08';
$to = '2025-08-15';
GoShip::searchTransaction(from: $from, to: $to);

Xác thực webhook

Giới thiệu: Hàm trả về giá trị boolean (true/false)

true: Giá trị băm hợp lệ

false: Giá trị băm không hợp lệ

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::verifyWebhook();

Lấy biểu phí vận chuyển Đơn giao hoả tốc

use BeetechAsia\GoShip\Enums\Kind;
use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'paths' => [
        [
            'lat' => 20.9842552,
            'lng' => 105.8609381,
            'kind' => Kind::PICKUP,
        ],
        [
            'lat' => 20.9895958,
            'lng' => 105.8445432,
            'kind' => Kind::DELIVERY,
            'parcel' => [
                'cod_amount' => 500000, // Không bắt buộc
                'amount' => 500000, // Không bắt buộc
                'name' => 'Tủ gỗ',
                'quantity' => 20,
                'width' => 20,
                'weight' => 200,
            ],
        ],
    ],
];
GoShip::getOnDemandRates($data);

Danh sách Vận đơn Đơn giao hoả tốc

use BeetechAsia\GoShip\Facades\GoShip;

GoShip::getOnDemandShipments();

Tìm kiếm Vận đơn Đơn giao hoả tốc

use BeetechAsia\GoShip\Facades\GoShip;

// Tìm kiếm theo id, order_id
$q = '56GDG8F';
GoShip::searchOnDemandShipment($q);

// Tìm kiếm theo thời gian bắt đầu và thời gian kết thúc
$start_date = '2025-08-08';
$end_date = '2025-08-15';
GoShip::searchOnDemandShipment(start_date: $start_date, end_date: $end_date);

Tạo mới Vận đơn Đơn giao hoả tốc

use BeetechAsia\GoShip\Enums\Kind;
use BeetechAsia\GoShip\Enums\OnDemandCarrier;
use BeetechAsia\GoShip\Enums\Tier;
use BeetechAsia\GoShip\Facades\GoShip;

$data = [
    'order_id' => '02846e55e191c5706a5021191563c2a6',
    'paths' => [
        [
            'address' => 'Ngõ 371 Phố Vũ Tông Phan, Phường Khương Đình, Quận Thanh Xuân, Hà Nội, Việt Nam',
            'name' => 'Nguyễn Văn A',
            'phone' => '0913131313',
            'lat' => 20.9842552,
            'lng' => 105.8609381,
            'kind' => Kind::PICKUP,
        ],
        [
            'address' => '300 Đ. Giải Phóng, Phương Liệt, Hai Bà Trưng, Hà Nội, Việt Nam',
            'name' => 'Trần Văn B',
            'phone' => '0912121212',
            'lat' => 20.9895958,
            'lng' => 105.8445432,
            'kind' => Kind::DELIVERY,
            'parcel' => [
                'name' => 'Tủ gỗ',
                'quantity' => 1,
                'quantity' => 20,
                'width' => 20,
                'weight' => 200,
            ],
        ],
    ],
    'carrier' => OnDemandCarrier::AHAMOVE,
    'vehicle' => 'BIKE',
    'service' => 'HAN-BIKE', // Ahamove: HAN-BIKE, Grab: GrabExpress
    'note' => 'Để vào tủ đồ ở sảnh chung cư (Đến nơi liên hệ KH để lấy mã)' // Nếu không có ghi chú, đặt giá trị là chuỗi rỗng (empty string)
    'metadata' => ['Hàng dễ vỡ, vui lòng nhẹ tay.'], // Không bắt buộc
    /*
     * Áp dụng cho Ahamove
     * HAN-BIKE-ROUND-TRIP: Tài xế sẽ quay lại điểm lấy hàng với số phí bằng 80% phí khoảng cách. Lưu ý: Phí khoảng cách là số phí dựa theo số km vận chuyển, ko bao gồm phí điểm dừng và các loại phí khác.
     * HAN-BIKE-BULKY: Giao hàng cồng kềnh
     *             | Kích thước    | Cân nặng    | Mức phí
     *      TIER_2:| 60x50x60 (cm) | 40kg        | 10.000 VND
     *      TIER_3:| 70x60x70 (cm) | 60kg        | 20.000 VND
     *      TIER_4:| 90x70x90 (cm) | 80kg        | 40.000 VND
     */
    'requests' => [[
        '_id' => 'HAN-BIKE-BULKY',
        'tier_code' => Tier::TIER_2,
    ]],
];
GoShip::createOnDemandShipment($data);

Sửa thông tin Vận đơn Đơn giao hoả tốc

use BeetechAsia\GoShip\Enums\Kind;
use BeetechAsia\GoShip\Enums\OnDemandCarrier;
use BeetechAsia\GoShip\Enums\Tier;
use BeetechAsia\GoShip\Facades\GoShip;

$shipmentId = '56GDG8F';
$data = [
    'order_id' => '02846e55e191c5706a5021191563c2a6',
    'paths' => [
        [
            'address' => 'Ngõ 371 Phố Vũ Tông Phan, Phường Khương Đình, Quận Thanh Xuân, Hà Nội, Việt Nam',
            'name' => 'Nguyễn Văn A',
            'phone' => '0913131313',
            'lat' => 20.9842552,
            'lng' => 105.8609381,
            'kind' => Kind::PICKUP,
        ],
        [
            'address' => '300 Đ. Giải Phóng, Phương Liệt, Hai Bà Trưng, Hà Nội, Việt Nam',
            'name' => 'Trần Văn B',
            'phone' => '0912121212',
            'lat' => 20.9895958,
            'lng' => 105.8445432,
            'kind' => Kind::DELIVERY,
            'parcel' => [
                'name' => 'Tủ gỗ',
                'quantity' => 1,
                'quantity' => 20,
                'width' => 20,
                'weight' => 200,
            ],
        ],
    ],
    'carrier' => OnDemandCarrier::AHAMOVE,
    'vehicle' => 'BIKE',
    'service' => 'HAN-BIKE', // Ahamove: HAN-BIKE, Grab: GrabExpress
    'note' => 'Để vào tủ đồ ở sảnh chung cư (Đến nơi liên hệ KH để lấy mã)' // Nếu không có ghi chú, đặt giá trị là chuỗi rỗng (empty string)
    'metadata' => ['Hàng dễ vỡ, vui lòng nhẹ tay.'], // Không bắt buộc
    /*
     * Áp dụng cho Ahamove
     * HAN-BIKE-ROUND-TRIP: Tài xế sẽ quay lại điểm lấy hàng với số phí bằng 80% phí khoảng cách. Lưu ý: Phí khoảng cách là số phí dựa theo số km vận chuyển, ko bao gồm phí điểm dừng và các loại phí khác.
     * HAN-BIKE-BULKY: Giao hàng cồng kềnh
     *             | Kích thước    | Cân nặng    | Mức phí
     *      TIER_2:| 60x50x60 (cm) | 40kg        | 10.000 VND
     *      TIER_3:| 70x60x70 (cm) | 60kg        | 20.000 VND
     *      TIER_4:| 90x70x90 (cm) | 80kg        | 40.000 VND
     */
    'requests' => [[
        '_id' => 'HAN-BIKE-BULKY',
        'tier_code' => Tier::TIER_2,
    ]],
];
GoShip::updateOnDemandShipment($shipmentId, $data);

Xóa Vận đơn Đơn giao hoả tốc

use BeetechAsia\GoShip\Facades\GoShip;

$shipmentId = '56GDG8F';
GoShip::deleteOnDemandShipment($shipmentId);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Tri Nguyen Duc (Bee Tech - PHP)
• All Contributors

License

The MIT License (MIT). Please see License File for more information.