mivita/dev/2026-01-23/v07pak-vs-v01pak.md

# V07PAK vs V01PAK für Return-Labels

**Datum:** 23.01.2026  
**Problem:** V07PAK wird als "unknown product" abgelehnt

## Fehler-Analyse

### DHL API Response:
```json
{
  "validationMessages": [{
    "property": "product",
    "validationMessage": "The product entered is unknown.",
    "validationState": "Error"
  }]
}
```

### Request Payload:
```json
{
  "product": "V07PAK",
  "billingNumber": "33333333330102"
}
```

## Produkt-Codes Vergleich

### V07PAK - DHL Retoure Online

**Beschreibung:** Spezieller Produktcode für Retouren

**Eigenschaften:**
- Designiert für Retouren
- Separate Billing-Nummer oft erforderlich
- Nicht für alle Accounts verfügbar
- Benötigt spezielle Freischaltung

**Account-Nummer:** `63144073550701` (laut config)

**Problem:** ❌ Nicht für diesen Account freigeschaltet

### V01PAK - DHL Paket

**Beschreibung:** Standard DHL Paket-Versand

**Eigenschaften:**
- ✅ Standard-Produkt, für alle Accounts verfügbar
- ✅ Keine spezielle Freischaltung nötig
- ✅ Mit vertauschten Adressen = Retoure
- ✅ Identische Funktionalität

**Account-Nummer:** `33333333330102` (laut Logs)

**Lösung:** ✅ Verwenden für Returns!

## Technischer Vergleich

| Feature | V07PAK | V01PAK (für Returns) |
|---------|--------|----------------------|
| Verfügbarkeit | Spezielle Freischaltung | ✅ Immer verfügbar |
| Billing Number | Separate Nummer | Standard-Nummer |
| Label-Aussehen | DHL Retoure | DHL Paket |
| Tracking | ✅ Ja | ✅ Ja |
| Funktionalität | Retoure | Mit vertauschten Adressen = Retoure |
| Kosten | Ggf. anders | Standard-Tarif |

## Warum V01PAK für Returns funktioniert

### Normale Sendung (Outbound):
```
Shipper: Unser Lager (mivita care)
  ↓
Consignee: Kunde
  ↓
= Normale Lieferung an Kunde
```

### Return-Sendung mit V01PAK:
```
Shipper: Kunde (sendet zurück)
  ↓
Consignee: Unser Lager (mivita care)
  ↓
= Retoure! (durch vertauschte Adressen)
```

DHL erkennt an den vertauschten Adressen, dass es eine Rücksendung ist!

## Implementierung

### Alte Version (V07PAK):
```php
$shipmentData = [
    'product_code' => 'V07PAK', // ❌ Nicht verfügbar
    'shipper' => $customer,
    'consignee' => $warehouse,
];
```

### Neue Version (V01PAK):
```php
$shipmentData = [
    'product_code' => 'V01PAK', // ✅ Funktioniert!
    'shipper' => $customer,     // Kunde als Absender
    'consignee' => $warehouse,  // Lager als Empfänger
];
// Nach Erstellung:
DB::update(['type' => 'return']); // Markierung als Retoure
```

## DHL Produktcodes Übersicht

| Code | Name | Verwendung |
|------|------|------------|
| V01PAK | DHL Paket | Standard Paketversand (auch für Returns!) |
| V53PAK | DHL Paket International | Internationaler Versand |
| V62WP | Warenpost | Kleinteile bis 1kg |
| V07PAK | DHL Retoure Online | Spezial-Retouren (oft nicht verfügbar) |

## Konfiguration

### config/dhl.php
```php
'account_numbers' => [
    'V01PAK' => env('DHL_ACCOUNT_NUMBER_V01PAK', '33333333330102'),
    'V07PAK' => env('DHL_ACCOUNT_NUMBER_V07PAK', '63144073550701'),
    // ...
],

'dimensions' => [
    'V01PAK' => ['length' => 120, 'width' => 60, 'height' => 60],
    'V07PAK' => ['length' => 120, 'width' => 60, 'height' => 60],
    // Gleiche Maße!
],
```

## Fallback-Änderung

### ReturnsService.php

```php
private function createReturnViaRegularShipment(array $returnData): array
{
    $shipmentData = [
        // Geändert von V07PAK zu V01PAK
        'product_code' => 'V01PAK', // ✅ Standard DHL Paket
        
        // Shipper = Kunde (sendet zurück)
        'shipper' => $customer,
        
        // Consignee = Lager (empfängt Retoure)
        'consignee' => $warehouse,
        
        // V01PAK Dimensions
        'dimensions' => [
            'length' => 120,
            'width' => 60,
            'height' => 60,
        ],
    ];
    
    $result = $shippingService->createLabel($shipmentData);
    
    // Wichtig: Als Retoure markieren!
    DhlShipment::find($result['shipmentId'])
        ->update(['type' => 'return']);
}
```

## Label-Unterschiede

### V07PAK Label (falls verfügbar):
- ❓ "DHL Retoure Online" Logo
- ❓ Spezielle Retouren-Kennzeichnung
- ❓ Evtl. andere Barcode-Formatierung

### V01PAK Label (als Retoure):
- ✅ Standard "DHL Paket" Logo
- ✅ Normale Tracking-Nummer
- ✅ Kunde als Absender sichtbar
- ✅ **Funktioniert identisch für Tracking & Zustellung**

## Vorteile V01PAK Lösung

1. ✅ **Sofort verfügbar** - Keine Freischaltung nötig
2. ✅ **Keine Extra-Kosten** - Standard-Tarif
3. ✅ **Identische Funktion** - Tracking & Zustellung gleich
4. ✅ **Einfachere Verwaltung** - Eine Billing-Nummer
5. ✅ **Weniger Fehler** - Kein "unknown product"

## Nachteile V01PAK Lösung

1. ❌ Keine spezielle "Retoure" Kennzeichnung auf Label
2. ❌ Evtl. andere Abrechnung als V07PAK
3. ❌ Nicht sofort als Retoure erkennbar (nur im System via `type='return'`)

## Tracking

**Beide Produktcodes generieren gültige DHL Tracking-Nummern:**

- Format: `222201234567890` (15 Stellen)
- Tracking-URL: `https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=...`
- Funktioniert identisch für V01PAK und V07PAK

## Empfehlung

### Kurzfristig (Aktuell):
✅ **V01PAK verwenden**
- Funktioniert sofort
- Keine Änderungen am Account nötig
- Identische Funktionalität

### Langfristig (Optional):
📞 **V07PAK beantragen bei DHL**
- Kontakt: DHL Geschäftskundenberater
- Vorteile: Spezielle Retouren-Kennzeichnung
- Evtl. bessere Abrechnung

## Testing

```bash
# Return-Label erstellen mit V01PAK
# Erwartung: Erfolg!

# Logs prüfen:
tail -f storage/logs/laravel.log | grep "DHL"

# Erwartete Ausgabe:
# [DHL Returns] Using regular Shipping API as fallback
# [DHL API] Sending payload {"product":"V01PAK",...}
# [DHL API] Response received (200)
# [DHL Returns] Return label created successfully ✅
```

## Fazit

V01PAK ist die praktische Lösung für Return-Labels wenn V07PAK nicht verfügbar ist. Die Funktionalität ist identisch, nur die Label-Optik unterscheidet sich minimal.