202 lines
4.7 KiB
Markdown
202 lines
4.7 KiB
Markdown
#DHL Dokuments
|
|
https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany-v2?language_content_entity=en#get-started-section/
|
|
|
|
# DHL Laravel Package
|
|
|
|
A comprehensive Laravel package for DHL shipping, tracking, and returns functionality with direct API integration.
|
|
|
|
## Features
|
|
|
|
- **Direct DHL API Integration**: No SDK dependencies, full control over API calls
|
|
- **German Address Parsing**: Automatic extraction of house numbers from German addresses
|
|
- **Queue Support**: Optional asynchronous processing for high-volume operations
|
|
- **Comprehensive Tracking**: Full tracking event history and status management
|
|
- **Return Label Generation**: Easy return shipment creation
|
|
- **Retry Mechanisms**: Built-in retry logic for API calls and file operations
|
|
- **Laravel Integration**: Native service providers, facades, and Eloquent models
|
|
|
|
## Installation
|
|
|
|
### 1. Add to composer.json
|
|
|
|
```json
|
|
{
|
|
"repositories": [
|
|
{
|
|
"type": "path",
|
|
"url": "./packages/acme-laravel-dhl"
|
|
}
|
|
],
|
|
"require": {
|
|
"acme/laravel-dhl": "*"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Install the package
|
|
|
|
```bash
|
|
composer update acme/laravel-dhl
|
|
```
|
|
|
|
### 3. Publish configuration and run migrations
|
|
|
|
```bash
|
|
php artisan vendor:publish --provider="Acme\Dhl\DhlServiceProvider" --tag="config"
|
|
php artisan migrate
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Add the following environment variables to your `.env` file:
|
|
|
|
```env
|
|
# DHL API Configuration
|
|
DHL_BASE_URL=https://api-eu.dhl.com
|
|
DHL_API_KEY=your_api_key_here
|
|
DHL_USERNAME=your_username
|
|
DHL_PASSWORD=your_password
|
|
DHL_BILLING_NUMBER=your_billing_number
|
|
|
|
# DHL Default Settings
|
|
DHL_PRODUCT=V01PAK
|
|
DHL_LABEL_FORMAT=PDF
|
|
DHL_PROFILE=STANDARD_GRUPPENPROFIL
|
|
|
|
# Optional Queue Settings
|
|
DHL_USE_QUEUE=false
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Creating a Shipment Label
|
|
|
|
```php
|
|
use DHL;
|
|
|
|
$orderData = [
|
|
'order_id' => 12345,
|
|
'weight_kg' => 2.5,
|
|
'shipper' => [
|
|
'name' => 'Your Company',
|
|
'street' => 'Musterstraße 123', // House number will be auto-parsed
|
|
'postalCode' => '12345',
|
|
'city' => 'Berlin',
|
|
'country' => 'DE'
|
|
],
|
|
'consignee' => [
|
|
'name' => 'Customer Name',
|
|
'street' => 'Kundenstraße 456', // House number will be auto-parsed
|
|
'postalCode' => '54321',
|
|
'city' => 'Munich',
|
|
'country' => 'DE'
|
|
]
|
|
];
|
|
|
|
$result = DHL::createLabel($orderData);
|
|
// Returns: ['shipmentNumber' => '123...', 'label_path' => 'dhl/labels/...']
|
|
```
|
|
|
|
### German Address Parsing
|
|
|
|
The package automatically handles German address formats by extracting house numbers from the street field:
|
|
|
|
```php
|
|
// Input: "Musterstraße 123a"
|
|
// Parsed to: street="Musterstraße", houseNumber="123a"
|
|
|
|
// Supported formats:
|
|
"Musterstraße 123" -> street: "Musterstraße", number: "123"
|
|
"Am Markt 7" -> street: "Am Markt", number: "7"
|
|
"Karl-Marx-Straße 156" -> street: "Karl-Marx-Straße", number: "156"
|
|
"Lindenstraße 1-3" -> street: "Lindenstraße", number: "1-3"
|
|
"Muster Str. 99" -> street: "Muster Str.", number: "99"
|
|
```
|
|
|
|
### Tracking Shipments
|
|
|
|
```php
|
|
use DHL;
|
|
|
|
// Get current tracking status
|
|
$status = DHL::track('1234567890123');
|
|
|
|
// Returns detailed tracking information including events
|
|
```
|
|
|
|
### Creating Return Labels
|
|
|
|
```php
|
|
use DHL;
|
|
|
|
$returnData = [
|
|
'original_shipment_id' => 1,
|
|
'return_reason' => 'Customer return',
|
|
// ... address data
|
|
];
|
|
|
|
$return = DHL::createReturn($returnData);
|
|
```
|
|
|
|
### Using Services Directly
|
|
|
|
```php
|
|
use Acme\Dhl\Services\ShippingService;
|
|
use Acme\Dhl\Services\TrackingService;
|
|
|
|
// Dependency injection in controllers
|
|
public function createLabel(ShippingService $shipping, Request $request)
|
|
{
|
|
$result = $shipping->createLabel($request->validated());
|
|
return response()->json($result);
|
|
}
|
|
```
|
|
|
|
## Database Schema
|
|
|
|
The package creates the following tables:
|
|
|
|
- `dhl_shipments` - Main shipment records (outbound and returns)
|
|
- `dhl_tracking_events` - Tracking event history
|
|
|
|
## Queue Configuration
|
|
|
|
For high-volume applications, enable queue processing:
|
|
|
|
```env
|
|
DHL_USE_QUEUE=true
|
|
```
|
|
|
|
When enabled, label creation and tracking updates will be processed asynchronously.
|
|
|
|
## Error Handling
|
|
|
|
The package includes comprehensive error handling:
|
|
|
|
- `DhlApiException` - General API errors
|
|
- `DhlAuthenticationException` - Authentication failures
|
|
- `DhlValidationException` - Data validation errors
|
|
|
|
## Testing
|
|
|
|
Run the included tests:
|
|
|
|
```bash
|
|
vendor/bin/phpunit packages/acme-laravel-dhl/tests/
|
|
```
|
|
|
|
## Address Parsing Tests
|
|
|
|
The package includes comprehensive tests for German address parsing:
|
|
|
|
```bash
|
|
vendor/bin/phpunit packages/acme-laravel-dhl/tests/Unit/AddressParserTest.php
|
|
```
|
|
|
|
## Logging
|
|
|
|
All API calls, address parsing, and errors are logged using Laravel's logging system. Check your logs for debugging information.
|
|
|
|
## License
|
|
|
|
MIT License
|