#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