gruene-seele/dev/product management/03-status-und-vorschlaege/ap-32-brueckenloesung-connector-update.md

AP-32 Brückenlösung — DHL-Label aus WooCommerce übernehmen (17.07.2026, Base64 seit 20.07.2026)

Kontext

Die vollständige DHL-API-Anbindung (AP-32) ist nachgelagert (Kundenentscheid 16.07.2026). Bis dahin: Das Label wird wie bisher im WooCommerce-Shop über das Plugin „DHL for WooCommerce" erstellt; bei der Übertragung der Bestellung ins Partnercenter kommt die Label-PDF selbst (Base64) plus Sendungsnummer mit.

Änderung 20.07.2026 (Code-Review vor Live-Release, Connector 1.5.0): Ursprünglich (1.4.0) wurde nur die label_url übertragen und das Partnercenter lud die PDF herunter. Das funktionierte in Produktion nicht: Das DHL-Plugin schützt den Label-Ordner wp-content/uploads/woocommerce_dhl_label/ per „deny from all" — der Abruf lief immer auf 403. Außerdem war der serverseitige Abruf einer vom Client gelieferten URL ein SSRF-Risiko und blockierte den wp/order-Request bis zu 20 s (WordPress bricht nach 5 s ab → Übertragung wäre shopseitig dauerhaft als fehlgeschlagen markiert worden). Jetzt liest der Connector die Datei direkt vom Shop-Dateisystem (label_path aus dem DHL-Meta) und schickt sie Base64-codiert mit — kein Download, kein SSRF, kein Timeout-Fenster.

Das Partnercenter speichert die PDF im privaten Storage (storage/app/wp-labels/) — Gründe:

1. Der Shop-Ordner ist zugriffsgeschützt, eine Verlinkung wäre tot; die lokale Kopie wird nur über die eingeloggte Admin-Route ausgeliefert (Kundenadresse auf dem Label!).
2. Die Kopie bleibt verfügbar, auch wenn das Label im Shop gelöscht/storniert wird.

Was das Partnercenter jetzt kann (Laravel-Seite, 17.07.2026 / Base64 20.07.2026)

• POST /api/wp/order akzeptiert zusätzlich (alles optional):
  • wp_label_pdf — die Label-PDF Base64-codiert (max. 10 MB dekodiert, Inhalt muss mit %PDF beginnen, sonst wird sie verworfen und nur geloggt)
  • wp_label_url — Original-URL im Shop, reines Herkunfts-Metadatum (wird nie abgerufen und nie verlinkt)
  • wp_tracking_number — Sendungsnummer (String oder Array bei Mehrpaket-Sendung)
• Neu POST /api/wp/label (Passport-Auth wie die übrigen wp/*-Endpoints) — Label nachreichen/aktualisieren, wenn es erst nach der Übertragung erstellt wird: { wp_order_number, wp_label_pdf, wp_tracking_number }
• POST /api/wp/status liefert je Bestellung zusätzlich tracking_number zurück (für den Tracking-Link an den Endkunden im Shop).
• Anzeige: Abwicklungs-Board + Bestell-Details zeigen „Label"-Download (nur die lokale Kopie — kein Shop-Link mehr, der Ordner ist zugriffsgeschützt) und die Sendungsnummer.
• Ein ungültiges/fehlendes Label blockiert die Bestell-Übertragung nie (Sendungsnummer + URL-Metadatum werden trotzdem gespeichert, Warnung im Log).

Update im Verbindungs-Plugin (WooCommerce-Seite) — umgesetzt 17.07.2026

Das DHL-Plugin speichert an der Bestellung das Meta-Feld _pr_shipment_dhl_label_tracking mit label_url, label_path, tracking_number (+ ggf. return_label_url). Das Update ist im Connector dev/partnercenter-api (PARTNERCENTER API Connector, Version 1.5.0) umgesetzt:

1. Label bei der Bestell-Übertragung mitschicken

public/partnercenter-api/partnercenter-api-requests/order.php:

• Helper compose_label_data() — liest das DHL-Meta-Feld und liefert seit 1.5.0 wp_label_pdf (Base64 aus label_path, s. u.) + wp_tracking_number (String oder Array) + wp_label_url (nur Metadatum); leeres Array, wenn weder Label noch Sendungsnummer existieren.
• Neuer Helper read_label_file() (1.5.0) — liest die Label-PDF vom Shop-Dateisystem: realpath muss innerhalb von wp-uploads liegen, .pdf-Endung, Inhalt muss mit %PDF beginnen; sonst false (dann geht nur die Sendungsnummer raus).
• write_order_items() (baut den POST wp/order des „Übertragen"-Buttons) merged die Label-Daten in den Request-Body.
• methods.php create(): Request-Timeout 30 s statt WordPress-Default 5 s (Payload trägt jetzt die Base64-PDF).

2. Label automatisch nachreichen (wenn es nach der Übertragung erstellt wird)

• Neue Datei public/woocommerce/dhl-label.php (PARTNERCENTER_API_WooCommerce_DHL_Label_Class): lauscht auf den Hook pr_save_dhl_label_tracking des DHL-Plugins (feuert nach dem Speichern des Meta-Felds, je Sendungsnummer) und ruft send_order_label() auf — aber nur, wenn die Bestellung bereits übertragen wurde (_partnercenter_api_order_fulfillment_forwarded gesetzt); sonst kommt das Label ohnehin mit der Übertragung mit.
• Neue öffentliche Methode send_order_label() in public/partnercenter-api/partnercenter-api.php + Trait-Methode write_order_label() → POST wp/label (nutzt die bestehende Auth-/Request-Infrastruktur des Connectors).
• Eingebunden über require_once im Haupt-Plugin-File; Version 1.3.3 → 1.4.0 → 1.5.0 (Base64-Übertragung, 20.07.2026).

Hinweise:

• Der Hook feuert je Sendungsnummer; der Endpoint ist idempotent (überschreibt Label + Sendungsnummer), Mehrfachaufrufe sind unkritisch.
• Die Label-Erstellung im Shop vor dem Übertragen ist der Normalfall (ein Request weniger); das Nachreichen ist das Sicherheitsnetz.
• Deployment: Der geänderte Plugin-Ordner dev/partnercenter-api muss in den WooCommerce-Shop eingespielt werden (ersetzt das installierte Plugin „PARTNERCENTER API Connector").

Offene Punkte / bewusst nicht enthalten

• Retourenlabel (return_label_url im Meta): bei Bedarf analog übertragbar — bräuchte ein weiteres Feld an shopping_orders.
• Etiketten-Sammel-PDF (AP-33c) und Label-Erstellung im Partnercenter (AP-32) bleiben nachgelagert; die neuen Spalten (tracking, wp_label_path) sind dafür wiederverwendbar.