Quick Reference

Quick Reference Card

🚀 Essential Commands

# Start development server
php artisan serve

# Test DHL API connection
php artisan dhl:test-connection

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

# Clear all caches
php artisan cache:clear

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

# Open database console
php artisan tinker

🌐 API Endpoints

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

📦 Test Shipment (curl)

curl -X POST http://localhost:8000/api/webhook/picqer/shipment \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TEST-001",
    "recipient": {
      "name": "Max Mustermann",
      "address_line_1": "Teststraße",
      "house_number": "1",
      "zipcode": "10115",
      "city": "Berlin",
      "country": "DE"
    }
  }'

🔧 Common Database Queries (Tinker)

// View all shipments
\App\Models\Shipment::all();

// View latest shipments
\App\Models\Shipment::latest()->take(10)->get();

// Find specific shipment
\App\Models\Shipment::find(1);

// Check failed shipments
\App\Models\Shipment::where('status', 'failed')->get();

// Count by status
\App\Models\Shipment::selectRaw('status, count(*) as count')
    ->groupBy('status')->get();

// Clear DHL token
\Cache::forget(config('dhl.jwt.cache_key'));

⚙️ Environment Variables

Required for Testing

DHL_MODE=sandbox
DHL_SANDBOX_CLIENT_ID=your_client_id
DHL_SANDBOX_CLIENT_SECRET=your_secret
DHL_BILLING_NUMBER=your_billing_number
DHL_SHIPPER_NAME="Your Company"
DHL_SHIPPER_STREET="Your Street"
DHL_SHIPPER_HOUSE_NUMBER="123"
DHL_SHIPPER_POSTAL_CODE="12345"
DHL_SHIPPER_CITY="Your City"
DHL_SHIPPER_COUNTRY=DE
DHL_SHIPPER_EMAIL="[email protected]"

For Production

DHL_MODE=production
DHL_PRODUCTION_CLIENT_ID=your_prod_client_id
DHL_PRODUCTION_CLIENT_SECRET=your_prod_secret

🔐 Security

Webhook Signature (HMAC-SHA256)

# Generate signature
PAYLOAD='{"order_id":"TEST",...}'
SECRET='your_secret'
echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET"

Disable Signature Verification (Testing Only)

PICQER_VERIFY_SIGNATURE=false

📊 Response Examples

Success

{
  "success": true,
  "shipment_id": 1,
  "tracking_number": "00340434161094015902",
  "label_url": "http://localhost:8000/api/shipments/1/label",
  "tracking_url": "https://www.dhl.de/..."
}

Error

{
  "success": false,
  "error": "Validation failed",
  "details": { ... }
}

🐛 Troubleshooting

JWT Token Error

# Clear token cache
php artisan cache:clear

# Test connection
php artisan dhl:test-connection

# Check credentials in .env

Webhook Signature Error

# Check secret matches
grep PICQER_WEBHOOK_SECRET .env

# Disable for testing
PICQER_VERIFY_SIGNATURE=false

Label Not Found

# Check shipment status
php artisan tinker
>>> \App\Models\Shipment::find(1)->status

# View DHL response
>>> \App\Models\Shipment::find(1)->dhl_response

📈 Monitoring

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

# Count shipments
php artisan tinker
>>> \App\Models\Shipment::count()

# Today's shipments
>>> \App\Models\Shipment::whereDate('created_at', today())->count()

# Success rate
>>> $total = \App\Models\Shipment::count();
>>> $success = \App\Models\Shipment::where('status', 'created')->count();
>>> echo round($success/$total*100, 2) . '%';

🔄 Mode Switching

Sandbox → Production

# 1. Update .env
DHL_MODE=production

# 2. Clear cache
php artisan cache:clear

# 3. Test connection
php artisan dhl:test-connection

# 4. Restart server
# (if using php artisan serve, Ctrl+C and restart)

📁 Important Files

File Purpose
.env Configuration
config/dhl.php DHL settings
app/Services/DHL/DHLAuthService.php JWT auth
app/Services/DHL/DHLShippingService.php Shipment creation
app/Http/Controllers/Api/ShippingWebhookController.php Webhook handler
routes/api.php API routes
storage/logs/laravel.log Logs
database/database.sqlite Database

📚 Documentation Files

  • README.md - Full documentation
  • GETTING_STARTED.md - Setup guide
  • API_EXAMPLES.md - API examples
  • PROJECT_SUMMARY.md - Project overview
  • CHECKLIST.md - Setup checklist

🆘 Getting Help

  1. Check logs: storage/logs/laravel.log
  2. Review documentation files
  3. Test DHL connection: php artisan dhl:test-connection
  4. Check database: php artisan tinker
  5. Verify .env configuration

📞 External Resources

Quick Health Check

curl http://localhost:8000/api/health

Quick Test

php artisan dhl:test-connection