Project Summary

Laravel DHL Shipping Middleware for Picqer

This project has been successfully scaffolded and is ready for configuration and testing.

What Has Been Created

1. Core Services ✅

DHLAuthService (app/Services/DHL/DHLAuthService.php)
- Handles JWT token authentication with DHL API
- Automatic token caching (1 hour)
- Token refresh on expiration
- Separate sandbox/production credentials
DHLShippingService (app/Services/DHL/DHLShippingService.php)
- Creates shipments via DHL Parcel DE API
- Transforms Picqer data to DHL format
- Retrieves shipment information
- Handles label download and storage

2. API Controller ✅

ShippingWebhookController (app/Http/Controllers/Api/ShippingWebhookController.php)
- Receives Picqer webhooks
- Validates incoming data
- Creates DHL shipments
- Returns tracking info and labels to Picqer
- Webhook signature verification (HMAC-SHA256)

3. Database ✅

Shipments Table (migration created and run)
- Stores all shipment data
- Picqer order information
- DHL request/response
- Shipping labels (binary storage)
- Status tracking
- Error logging
- Soft deletes enabled
Shipment Model (app/Models/Shipment.php)
- Full CRUD functionality
- Helper methods for status management
- JSON casting for API data
- Label retrieval methods

4. Configuration ✅

DHL Config (config/dhl.php)
- Sandbox/Production mode toggle
- API endpoints
- Authentication settings
- JWT token caching
- Shipper information
- Billing number
Picqer Config (config/picqer.php)
- Webhook settings
- Signature verification
- API credentials
Environment Variables (.env and .env.example)
- All required variables configured
- Clear documentation
- Separate sandbox/production credentials

5. API Routes ✅

POST /api/webhook/picqer/shipment - Create shipment
GET /api/shipments/{id} - Get shipment info
GET /api/shipments/{id}/label - Download label
GET /api/health - Health check

6. Testing Tools ✅

Test Command (php artisan dhl:test-connection)
- Tests DHL API credentials
- Verifies JWT authentication
- Shows configuration details
- Helpful error messages

7. Documentation ✅

README.md - Comprehensive project documentation
GETTING_STARTED.md - Step-by-step setup guide
API_EXAMPLES.md - Complete API examples and testing guide

Architecture Overview

┌─────────────┐
│   Picqer    │
│  (Webhook)  │
└──────┬──────┘
       │
       │ POST /api/webhook/picqer/shipment
       │
┌──────▼────────────────────────────────────────┐
│  Laravel Application (Middleware)             │
│                                               │
│  ┌─────────────────────────────────────────┐ │
│  │ ShippingWebhookController               │ │
│  │  - Validates Picqer data                │ │
│  │  - Creates Shipment record              │ │
│  │  - Calls DHLShippingService             │ │
│  └────────────┬────────────────────────────┘ │
│               │                               │
│  ┌────────────▼────────────┐                 │
│  │  DHLShippingService     │                 │
│  │  - Transforms data      │                 │
│  │  - Calls DHL API        │                 │
│  └────────────┬────────────┘                 │
│               │                               │
│  ┌────────────▼────────────┐                 │
│  │  DHLAuthService         │                 │
│  │  - Manages JWT tokens   │                 │
│  │  - Authenticates API    │                 │
│  └─────────────────────────┘                 │
│                                               │
│  ┌─────────────────────────────────────────┐ │
│  │  Database (SQLite)                      │ │
│  │  - Shipments table                      │ │
│  │  - Stores labels & tracking info        │ │
│  └─────────────────────────────────────────┘ │
└───────────────────┬───────────────────────────┘
                    │
                    │ API Call
                    │
         ┌──────────▼──────────┐
         │  DHL Parcel DE API  │
         │  (Sandbox/Prod)     │
         └─────────────────────┘

Key Features

✅ Dual Environment Support

Sandbox mode for testing
Production mode for live shipments
Easy switching via environment variable

✅ Secure Authentication

JWT token management
Automatic token refresh
Token caching for performance
Webhook signature verification

✅ Comprehensive Logging

All API calls logged
Error tracking
Debug information
Storage in storage/logs/laravel.log

✅ Data Persistence

All shipments stored in database
Original Picqer data preserved
DHL request/response archived
Labels stored as binary data

✅ Error Handling

Validation errors
API failures
Network timeouts
Graceful degradation

✅ RESTful API

Standard HTTP methods
JSON responses
Proper status codes
Clear error messages

Next Steps

Configure Credentials
- Get DHL API credentials from developer portal
- Add to .env file
- Configure shipper information
Test Connection
```
php artisan dhl:test-connection
```
Test API Endpoints
- Start server: php artisan serve
- Test health: curl http://localhost:8000/api/health
- Create test shipment (see API_EXAMPLES.md)
Configure Picqer
- Set up custom shipping method
- Configure webhook URL
- Add webhook secret
Monitor & Deploy
- Test with sandbox orders
- Review logs
- Switch to production when ready
- Deploy to production server

File Structure

dhlshipping/
├── app/
│   ├── Console/Commands/
│   │   └── TestDHLConnection.php      # Test command
│   ├── Http/Controllers/Api/
│   │   └── ShippingWebhookController.php  # Webhook handler
│   ├── Models/
│   │   └── Shipment.php               # Shipment model
│   └── Services/DHL/
│       ├── DHLAuthService.php         # Authentication
│       └── DHLShippingService.php     # Shipment creation
├── config/
│   ├── dhl.php                        # DHL configuration
│   └── picqer.php                     # Picqer configuration
├── database/
│   ├── database.sqlite                # SQLite database
│   └── migrations/
│       └── *_create_shipments_table.php
├── routes/
│   └── api.php                        # API routes
├── .env                               # Environment config
├── .env.example                       # Environment template
├── README.md                          # Main documentation
├── GETTING_STARTED.md                 # Setup guide
└── API_EXAMPLES.md                    # API examples

Environment Variables Reference

# DHL Configuration
DHL_MODE=sandbox                       # sandbox | production
DHL_TIMEOUT=30                         # API timeout (seconds)
DHL_CONNECT_TIMEOUT=10                 # Connection timeout

# Sandbox Credentials
DHL_SANDBOX_CLIENT_ID=                 # From DHL Developer Portal
DHL_SANDBOX_CLIENT_SECRET=             # From DHL Developer Portal

# Production Credentials
DHL_PRODUCTION_CLIENT_ID=              # From DHL Developer Portal
DHL_PRODUCTION_CLIENT_SECRET=          # From DHL Developer Portal

# Shipper Information
DHL_BILLING_NUMBER=                    # Your DHL billing number
DHL_SHIPPER_NAME=                      # Company name
DHL_SHIPPER_STREET=                    # Street name
DHL_SHIPPER_HOUSE_NUMBER=              # House number
DHL_SHIPPER_POSTAL_CODE=               # Postal code
DHL_SHIPPER_CITY=                      # City
DHL_SHIPPER_COUNTRY=DE                 # Country code
DHL_SHIPPER_EMAIL=                     # Contact email

# Picqer Configuration
PICQER_WEBHOOK_SECRET=                 # Webhook secret
PICQER_VERIFY_SIGNATURE=true           # Enable signature check
PICQER_SUBDOMAIN=                      # Your Picqer subdomain (optional)
PICQER_API_KEY=                        # Your Picqer API key (optional)

Commands

# Start development server
php artisan serve

# Test DHL connection
php artisan dhl:test-connection

# View routes
php artisan route:list --path=api

# Run migrations
php artisan migrate

# Clear cache
php artisan cache:clear

# View logs
tail -f storage/logs/laravel.log

# Database operations
php artisan tinker

API Endpoints Summary

Endpoint	Method	Purpose
`/api/health`	GET	Health check & status
`/api/webhook/picqer/shipment`	POST	Create shipment from Picqer
`/api/shipments/{id}`	GET	Get shipment details
`/api/shipments/{id}/label`	GET	Download shipping label

Status Codes

200 OK - Successful GET request
201 Created - Successful shipment creation
401 Unauthorized - Invalid webhook signature
404 Not Found - Shipment not found
422 Unprocessable Entity - Validation failed
500 Internal Server Error - Server error

Database Status Tracking

Shipments can have the following statuses:

pending - Initial state
processing - Being processed
created - Successfully created at DHL
failed - Creation failed
cancelled - Cancelled

Troubleshooting

If you encounter issues:

Check logs: tail -f storage/logs/laravel.log
Verify credentials: php artisan dhl:test-connection
Check database: php artisan tinker → \App\Models\Shipment::all()
Clear cache: php artisan cache:clear
Review documentation: See README.md and GETTING_STARTED.md

Resources

DHL Developer Portal: https://developer.dhl.com/
DHL API Docs: https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany-v2
Picqer API Docs: https://picqer.com/en/api/custom-shippingmethod
Laravel Docs: https://laravel.com/docs

Project Status: ✅ Ready for Configuration

The Laravel application has been fully scaffolded with all necessary components. You can now:

Add your DHL and Picqer credentials to .env
Test the DHL connection with php artisan dhl:test-connection
Start testing with sandbox orders
Configure Picqer webhook integration
Switch to production when ready

All the middleware functionality is in place and ready to connect Picqer with DHL Parcel DE Shipping API!

Project Summary

#Project Summary

#Laravel DHL Shipping Middleware for Picqer

#What Has Been Created

#1. Core Services ✅

#2. API Controller ✅

#3. Database ✅

#4. Configuration ✅

#5. API Routes ✅

#6. Testing Tools ✅

#7. Documentation ✅

#Architecture Overview

#Key Features

#Next Steps

#File Structure

#Environment Variables Reference

#Commands

#API Endpoints Summary

#Status Codes

#Database Status Tracking

#Troubleshooting

#Resources

#Project Status: ✅ Ready for Configuration

Project Summary

Laravel DHL Shipping Middleware for Picqer

What Has Been Created

1. Core Services ✅

2. API Controller ✅

3. Database ✅

4. Configuration ✅

5. API Routes ✅

6. Testing Tools ✅

7. Documentation ✅

Architecture Overview

Key Features

Next Steps

File Structure

Environment Variables Reference

Commands

API Endpoints Summary

Status Codes

Database Status Tracking

Troubleshooting

Resources

Project Status: ✅ Ready for Configuration