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:

{
  "validationMessages": [{
    "property": "product",
    "validationMessage": "The product entered is unknown.",
    "validationState": "Error"
  }]
}

Request Payload:

{
  "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):

$shipmentData = [
    'product_code' => 'V07PAK', // ❌ Nicht verfügbar
    'shipper' => $customer,
    'consignee' => $warehouse,
];

Neue Version (V01PAK):

$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

'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

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

# 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.