Connector-Plugin 1.4.0: DHL-Label an das Partnercenter übertragen

compose_label_data() liest das Meta-Feld _pr_shipment_dhl_label_tracking
(DHL for WooCommerce); write_order_items() schickt Label-URL + Sendungsnummer
beim wp/order-Transfer mit. Neuer Listener auf pr_save_dhl_label_tracking
reicht Labels nach, die erst nach der Übertragung erstellt werden (nur bei
bereits übertragenen Bestellungen, via neuem wp/label-Endpoint).
Connector-Doku auf die konkrete Umsetzung aktualisiert.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

dev/partnercenter-api/partnercenter-api.php

@@ -3,7 +3,7 @@
 /**
  * Plugin Name: PARTNERCENTER API Connector
  * Description: Connect WooCommerce to PARTNERCENTER API
- * Version:     1.3.3
+ * Version:     1.4.0
  * Author:      Cross Media Cloud
  * Author URI:  https://www.cross-media-cloud.de
  * License:     GNU General Public License v2 or later
@@ -86,6 +86,8 @@ add_filter('PARTNERCENTER_API', 'partnercenter_api_init');
 require_once 'public/shortcode.php';
 // Load WooCommerce status related features
 require_once 'public/woocommerce/order-status.php';
+// Load DHL label forwarding ("DHL for WooCommerce" integration)
+require_once 'public/woocommerce/dhl-label.php';
 // Load endpoint
 require_once 'public/end-point.php';
 

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

@@ -137,6 +137,33 @@ trait PARTNERCENTER_API_Order
         return $data;
     }
 
+    /**
+     * Helper to read the DHL label data saved by the "DHL for WooCommerce" plugin.
+     *
+     * The plugin stores label URL and tracking number(s) as order meta.
+     *
+     * @return array Empty array when no label exists yet
+     *
+     * @since 1.4.0
+     */
+    private function compose_label_data()
+    {
+
+        // Get label meta written by "DHL for WooCommerce"
+        $label_meta = $this->order->get_meta('_pr_shipment_dhl_label_tracking');
+
+        // Check if a label was created for this order
+        if (! is_array($label_meta) || empty($label_meta['label_url'])) {
+            return [];
+        }
+
+        return [
+            'wp_label_url' => $label_meta['label_url'],
+            // String or array (multi parcel) - the API accepts both
+            'wp_tracking_number' => isset($label_meta['tracking_number']) ? $label_meta['tracking_number'] : null,
+        ];
+    }
+
     /**
      * Helper to create cart data.
      *
@@ -317,6 +344,11 @@ trait PARTNERCENTER_API_Order
             $request_body['wp_incentives'] = implode(', ', $incentives_strings_array);
         }
 
+        /*
+         * Add DHL label + tracking number (if a label was already created)
+         */
+        $request_body = array_merge($request_body, $this->compose_label_data());
+
         /*
          * Make the request
          */
@@ -327,6 +359,39 @@ trait PARTNERCENTER_API_Order
         return $this->handle_response($response);
     }
 
+    /**
+     * Push DHL label + tracking number for an already forwarded order.
+     *
+     * Used when the label is created (or re-created) AFTER the order
+     * has been forwarded to the PARTNERCENTER.
+     *
+     * @return bool
+     *
+     * @since 1.4.0
+     */
+    private function write_order_label()
+    {
+
+        // Get label data
+        $label_data = $this->compose_label_data();
+
+        // Nothing to send without a label
+        if (empty($label_data)) {
+            return false;
+        }
+
+        // Build body data
+        $request_body = array_merge([
+            'wp_order_number' => $this->order->get_id(),
+        ], $label_data);
+
+        // Send to API
+        $response = $this->create('wp/label', $request_body);
+
+        // Handle response
+        return $this->handle_response($response);
+    }
+
     /**
      * Try to cancel order.
      *

dev/partnercenter-api/public/partnercenter-api/partnercenter-api.php

@@ -163,6 +163,23 @@ class PARTNERCENTER_API_Requests
         return true;
     }
 
+    /**
+     * Push the DHL label of an already forwarded order to PARTNERCENTER.
+     *
+     * @since 1.4.0
+     *
+     * @return bool
+     */
+    public function send_order_label(int $order_id)
+    {
+
+        // Setup the order object
+        $this->setup_order($order_id);
+
+        // Send label data to API
+        return $this->write_order_label();
+    }
+
     /**
      * Handle retrieving of order from PARTNERCENTER.
      *

dev/partnercenter-api/public/woocommerce/dhl-label.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * Forward DHL labels created by the "DHL for WooCommerce" plugin.
+ *
+ * Normal case: the label is created BEFORE the order is forwarded - then
+ * write_order_items() sends label + tracking number along with the order.
+ * This listener covers the other case: the label is created (or re-created)
+ * AFTER the order has already been forwarded to the PARTNERCENTER.
+ */
+
+if (! defined('ABSPATH')) {
+    exit;
+}
+
+class PARTNERCENTER_API_WooCommerce_DHL_Label_Class
+{
+    /**
+     * PARTNERCENTER_API_WooCommerce_DHL_Label_Class constructor.
+     */
+    public function __construct()
+    {
+
+        // Listen to label creation by "DHL for WooCommerce"
+        // (fires once per tracking number, after the label meta was saved)
+        add_action('pr_save_dhl_label_tracking', [$this, 'pr_save_dhl_label_tracking'], 20, 2);
+
+    }
+
+    /**
+     * Push a freshly created DHL label to PARTNERCENTER.
+     *
+     * @param  array  $tracking_details  Carrier, tracking number, ship date, tracking URL
+     *
+     * @since 1.4.0
+     */
+    public function pr_save_dhl_label_tracking(int $order_id, $tracking_details)
+    {
+
+        // Only orders that have already been forwarded to the PARTNERCENTER -
+        // otherwise the label is sent along with the order transfer anyway
+        if (empty(get_post_meta($order_id, '_partnercenter_api_order_fulfillment_forwarded', true))) {
+            return;
+        }
+
+        // Load API
+        $partnercenter = apply_filters('PARTNERCENTER_API', false);
+        if ($partnercenter === false) {
+            return;
+        }
+
+        // Push label + tracking number to PARTNERCENTER
+        // (endpoint is idempotent - repeated calls just overwrite)
+        $partnercenter->send_order_label($order_id);
+
+    }
+}
+
+new PARTNERCENTER_API_WooCommerce_DHL_Label_Class;

dev/product management /ap-32-brueckenloesung-connector-update.md

@@ -31,76 +31,47 @@ privaten Storage (`storage/app/wp-labels/`) — Gründe:
 - Ein fehlgeschlagener Label-Download blockiert die Bestell-Übertragung **nie**
   (URL wird gespeichert, Warnung im Laravel-Log).
 
-## Nötiges Update im Verbindungs-Plugin (WooCommerce-Seite)
+## 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`). Zwei Ergänzungen im Connector:
+(+ ggf. `return_label_url`). Das Update ist im Connector
+**`dev/partnercenter-api` (PARTNERCENTER API Connector, Version 1.4.0)** umgesetzt:
 
 ### 1. Label bei der Bestell-Übertragung mitschicken
 
-Im bestehenden Code, der den `POST /api/wp/order` aufbaut:
+`public/partnercenter-api/partnercenter-api-requests/order.php`:
 
-```php
-// DHL-Label (Plugin "DHL for WooCommerce") mitgeben, falls vorhanden
-$label_meta = $order->get_meta( '_pr_shipment_dhl_label_tracking' );
-if ( is_array( $label_meta ) && ! empty( $label_meta['label_url'] ) ) {
-    $body['wp_label_url']       = $label_meta['label_url'];
-    $body['wp_tracking_number'] = isset( $label_meta['tracking_number'] )
-        ? $label_meta['tracking_number'] // String oder Array — beides ok
-        : null;
-}
-```
+- Neuer Helper `compose_label_data()` — liest das DHL-Meta-Feld und liefert
+  `wp_label_url` + `wp_tracking_number` (String oder Array; leeres Array, wenn
+  noch kein Label existiert).
+- `write_order_items()` (baut den `POST wp/order` des „Übertragen"-Buttons)
+  merged die Label-Daten in den Request-Body.
 
 ### 2. Label automatisch nachreichen (wenn es nach der Übertragung erstellt wird)
 
-Das DHL-Plugin feuert beim Speichern eines Labels den Hook
-`pr_save_dhl_label_tracking` (das Meta-Feld ist zu diesem Zeitpunkt bereits
-gespeichert). Darauf lauschen und an den neuen Endpoint senden:
-
-```php
-add_action( 'pr_save_dhl_label_tracking', 'gs_push_dhl_label_to_partnercenter', 10, 2 );
-
-function gs_push_dhl_label_to_partnercenter( $order_id, $tracking_details ) {
-    $order = wc_get_order( $order_id );
-    if ( ! $order ) {
-        return;
-    }
-
-    $label_meta = $order->get_meta( '_pr_shipment_dhl_label_tracking' );
-    if ( ! is_array( $label_meta ) || empty( $label_meta['label_url'] ) ) {
-        return;
-    }
-
-    // Auth-Token/Basis-URL wie bei den bestehenden API-Aufrufen des Connectors
-    wp_remote_post( gs_partnercenter_api_url( '/wp/label' ), array(
-        'timeout' => 15,
-        'headers' => array(
-            'Authorization' => 'Bearer ' . gs_partnercenter_api_token(),
-            'Accept'        => 'application/json',
-        ),
-        'body'    => array(
-            'wp_order_number'    => $order->get_order_number(),
-            'wp_label_url'       => $label_meta['label_url'],
-            'wp_tracking_number' => isset( $label_meta['tracking_number'] )
-                ? $label_meta['tracking_number']
-                : null,
-        ),
-    ) );
-}
-```
+- 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.
 
 Hinweise:
 
-- `gs_partnercenter_api_url()` / `gs_partnercenter_api_token()` stehen für die
-  im Connector bereits vorhandene Basis-URL- und Token-Logik — bitte die
-  dortigen Funktionsnamen verwenden.
 - Der Hook feuert **je Sendungsnummer**; der Endpoint ist idempotent
   (überschreibt Label + Sendungsnummer), Mehrfachaufrufe sind unkritisch.
-- Ist die Bestellung noch nicht übertragen, antwortet `/wp/label` mit 400
-  („not found") — das ist ok: beim späteren `wp/order` kommt das Label ohnehin mit.
-- Wichtig: Die Label-Erstellung im Shop **vor** dem Übertragen ist der
-  Normalfall (ein Request weniger); das Nachreichen ist das Sicherheitsnetz.
+- 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