README

A Laravel package for integrating with the Amazon Shipping API v2.

Installation

1. Install the package

composer require your-vendor/amazon-shipping-laravel

2. Publish the configuration

php artisan vendor:publish --tag=amazon-shipping-config

3. Run migrations

php artisan migrate

4. Configure environment variables

Add the following to your .env file:

AMAZON_SHIPPING_CLIENT_ID=your_client_id
AMAZON_SHIPPING_CLIENT_SECRET=your_client_secret
AMAZON_SHIPPING_REFRESH_TOKEN=your_refresh_token

# Optional - defaults shown
AMAZON_SHIPPING_SANDBOX=false
AMAZON_SHIPPING_API_URL=https://sellingpartnerapi-eu.amazon.com
AMAZON_SHIPPING_SANDBOX_URL=https://sandbox.sellingpartnerapi-eu.amazon.com
AMAZON_SHIPPING_BUSINESS_ID=AmazonShipping_IN
AMAZON_SHIPPING_TOKEN_TTL=60
AMAZON_SHIPPING_CACHE_KEY=amazon_shipping_access_token

Configuration

The configuration file config/amazon-shipping.php contains:

Key	Description	Default
`client_id`	Amazon SP-API Client ID	-
`client_secret`	Amazon SP-API Client Secret	-
`refresh_token`	Amazon SP-API Refresh Token	-
`api.sandbox`	Enable sandbox mode for testing	`false`
`api.base_url`	Production API base URL	`https://sellingpartnerapi-eu.amazon.com`
`api.sandbox_url`	Sandbox API base URL	`https://sandbox.sellingpartnerapi-eu.amazon.com`
`api.business_id`	Amazon Shipping Business ID	`AmazonShipping_IN`
`cache.token_ttl`	Access token cache duration (minutes)	`60`
`cache.token_key`	Cache key for access token	`amazon_shipping_access_token`

Supported Business IDs

Region	Business ID
India	`AmazonShipping_IN`
United States	`AmazonShipping_US`
United Kingdom	`AmazonShipping_UK`
Italy	`AmazonShipping_IT`
Spain	`AmazonShipping_ES`
France	`AmazonShipping_FR`
Japan	`AmazonShipping_JP`

Documentation

API	Description
Rates	Fetch shipping rates for a given shipment
Shipments	Purchase shipping labels and manage shipments
One-Click Shipment	Create shipments with automatic rate selection
Tracking	Track shipment status and events
Cancel Shipment	Cancel a purchased shipment
Shipment Documents	Re-download labels and get shipping documents
NDR Feedback	Submit non-delivery report feedback

API Logging

All API calls are automatically logged to the amazon_shipping_api_logs table:

Column	Description
`endpoint`	API endpoint called
`method`	HTTP method (GET, POST, etc.)
`service`	Service class that made the call
`status_code`	HTTP response status code
`status`	`success` or `failed`
`request_payload`	JSON request body
`response_payload`	JSON response body
`error_message`	Error details (if failed)
`duration_ms`	Request duration in milliseconds
`created_at`	Timestamp

Querying Logs

use AmazonShipping\Models\AmazonShippingApiLog;

// Get recent failed requests
$failedRequests = AmazonShippingApiLog::query()
    ->where('status', 'failed')
    ->latest()
    ->take(10)
    ->get();

// Get average response time for rates API
$avgDuration = AmazonShippingApiLog::query()
    ->where('endpoint', '/shipping/v2/shipments/rates')
    ->where('status', 'success')
    ->avg('duration_ms');

Testing

The package includes comprehensive tests that can be run in two ways:

Running Tests via Artisan Command

After installing the package, you can run the package tests using the built-in artisan command:

# Run all package tests
php artisan amazon-shipping:test

# Run only Feature tests
php artisan amazon-shipping:test --testsuite=Feature

# Run only Integration tests (requires sandbox credentials)
php artisan amazon-shipping:test --testsuite=Integration

# Run specific tests by filter
php artisan amazon-shipping:test --filter=RatesServiceTest

# Run with code coverage
php artisan amazon-shipping:test --coverage

Running Tests via PHPUnit Directly

You can also run the package tests directly using PHPUnit:

# Run all package tests
./vendor/bin/phpunit ./vendor/mohd-arbaaz/amazon-shipping-laravel/tests

# Run Feature tests only
./vendor/bin/phpunit ./vendor/mohd-arbaaz/amazon-shipping-laravel/tests/Feature

# Run Integration tests only
./vendor/bin/phpunit ./vendor/mohd-arbaaz/amazon-shipping-laravel/tests/Integration

# Run with the package's phpunit.xml configuration
./vendor/bin/phpunit --configuration ./vendor/mohd-arbaaz/amazon-shipping-laravel/phpunit.xml

Test Types

Test Suite	Description	Requires Credentials
Feature	Unit tests with mocked API responses	No
Integration	Live tests against Amazon Shipping Sandbox API	Yes

Integration Test Configuration

Integration tests call the actual Amazon Shipping Sandbox API. Configure sandbox credentials in your .env file:

AMAZON_SHIPPING_CLIENT_ID=your_sandbox_client_id
AMAZON_SHIPPING_CLIENT_SECRET=your_sandbox_client_secret
AMAZON_SHIPPING_REFRESH_TOKEN=your_sandbox_refresh_token
AMAZON_SHIPPING_SANDBOX=true
AMAZON_SHIPPING_BUSINESS_ID=AmazonShipping_IN  # or AmazonShipping_UK, etc.

Built-in region presets:

IN (India) - INR currency, GST tax details
UK (United Kingdom) - GBP currency
US (United States) - USD currency

Without credentials, integration tests are automatically skipped.

What Tests Verify

Test File	API Tested	Verifies
`RatesApiTest.php`	`getRates`	Rate retrieval, DTO hydration, DB storage
`PurchaseShipmentApiTest.php`	`purchaseShipment`	Shipment purchase, labels, tracking IDs
`OneClickShipmentApiTest.php`	`oneClickShipment`	Auto rate selection, label generation
`TrackingApiTest.php`	`getTracking`	Tracking info, event history
`CancelShipmentApiTest.php`	`cancelShipment`	Shipment cancellation
`ShipmentDocumentsApiTest.php`	`getShipmentDocuments`	Document retrieval, label re-download
`NdrFeedbackApiTest.php`	`submitNdrFeedback`	NDR actions (reschedule, reattempt, RTO)

Package Development

If you're contributing to this package, clone the repository and run tests locally:

# Clone the repository
git clone https://github.com/mohd-arbaaz/amazon-shipping-laravel.git
cd amazon-shipping-laravel

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run specific test suite
vendor/bin/phpunit --testsuite Feature
vendor/bin/phpunit --testsuite Integration

License

MIT License

mohd-arbaaz/amazon-shipping-laravel

包简介

关键字：

README 文档