Fulfillment-Provider an Magento 2 anbinden: Praxisleitfaden

1. Was ein Fulfillment-Provider für Magento übernimmt

Ein Fulfillment-Provider wie DHL Fulfillment, Rhenus oder ein spezialisiertes 3PL-Unternehmen übernimmt Lagerhaltung, Kommissionierung, Verpackung und Versand physischer Bestellungen, die im Magento-Shop eingehen. Für den Shopbetreiber entfällt dadurch die eigene Lagerlogistik, gleichzeitig entsteht aber eine neue technische Abhängigkeit: Magento muss Bestellungen an den Fulfillment-Provider übertragen und dessen Rückmeldungen zu Versand und Bestand zuverlässig verarbeiten. Eine gute Fulfillment-Integration macht diesen externen Dienstleister für den Kunden im Idealfall unsichtbar.

Die Herausforderung liegt darin, dass ein Fulfillment-Provider in der Regel ein eigenes Warehouse-Management-System mit eigenem Datenmodell betreibt, das nicht 1 zu 1 zu Magentos Bestellmodell passt. Teillieferungen, mehrere Lagerorte oder Sonderregeln für gefährliche Güter erfordern eine Fulfillment-Integration, die über einen simplen Bestellexport hinausgeht und den kompletten Lebenszyklus einer Bestellung von der Übertragung bis zur Zustellbestätigung abbildet.

2. Architektur der Anbindung: Export, Import, Bestand

Eine belastbare Fulfillment-Integration besteht aus drei unabhängigen Datenflüssen, die jeweils eigene Latenzanforderungen haben. Der Bestellexport von Magento zum Fulfillment-Provider muss schnell erfolgen, damit Bestellungen zeitnah kommissioniert werden. Der Bestandsimport vom Fulfillment-Provider zurück nach Magento muss ebenfalls zeitnah sein, damit der Shop keine Artikel anbietet, die im Lager nicht mehr verfügbar sind. Der Versandstatus-Import kann demgegenüber mit etwas mehr Verzögerung laufen, ohne dass Kunden das bemerken.

Diese drei Datenflüsse sollten technisch getrennt implementiert werden, meist über eigene Consumer innerhalb von Magentos Message Queue Framework. Eine Fulfillment-Integration, die alle drei Flüsse in einem einzigen synchronen Skript bündelt, wird bei einem Ausfall des Fulfillment-Providers alle drei Funktionen gleichzeitig blockieren, statt nur den betroffenen Teilprozess zu pausieren.

<!-- app/code/Mironsoft/FulfillmentIntegration/etc/queue_topology.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:MessageQueue/etc/topology.xsd">
    <exchange name="fulfillment" type="topic" connection="amqp">
        <binding id="orderExportBinding" topic="fulfillment.order.export" destinationType="queue" destination="fulfillment_order_export"/>
        <binding id="stockImportBinding" topic="fulfillment.stock.import" destinationType="queue" destination="fulfillment_stock_import"/>
        <binding id="shipmentImportBinding" topic="fulfillment.shipment.import" destinationType="queue" destination="fulfillment_shipment_import"/>
    </exchange>
</config>

3. Bestellexport an den Fulfillment-Dienstleister

Sobald eine Bestellung im Checkout abgeschlossen und bezahlt ist, muss die Fulfillment-Integration sie strukturiert an den Provider übertragen: Artikel mit SKU und Menge, Lieferadresse, gewählte Versandart und gegebenenfalls Sonderhinweise wie eine Geschenkverpackung. Der Export sollte über den Observer für das Event sales_order_invoice_pay oder ein vergleichbares Ereignis ausgelöst werden, nicht bereits beim reinen Anlegen der Bestellung, damit unbezahlte oder stornierte Bestellungen nicht versehentlich kommissioniert werden.

Ein häufiger Fehler bei der Fulfillment-Integration ist, den Export synchron im Checkout-Prozess auszuführen. Das koppelt die Antwortzeit für den Kunden an die Verfügbarkeit des Fulfillment-Providers. Der Export sollte stattdessen asynchron über eine Message Queue erfolgen, mit einer Bestätigung vom Provider, dass die Bestellung angenommen wurde, bevor sie in Magento als erfolgreich an den Fulfillment-Provider übertragen markiert wird.

<?php

declare(strict_types=1);

namespace Mironsoft\FulfillmentIntegration\Model\Queue;

use Magento\Sales\Api\Data\OrderInterface;
use Psr\Log\LoggerInterface;

/**
 * Builds and sends the fulfillment order export payload to the 3PL provider.
 */
final class OrderExportProcessor
{
    public function __construct(
        private readonly FulfillmentApiClient $apiClient,
        private readonly LoggerInterface $logger
    ) {
    }

    /**
     * Transforms and transmits an order to the fulfillment provider.
     *
     * @param OrderInterface $order Paid Magento order ready for fulfillment
     * @return void
     */
    public function export(OrderInterface $order): void
    {
        $payload = [
            'order_reference' => $order->getIncrementId(),
            'shipping_address' => $this->mapAddress($order->getShippingAddress()),
            'items' => $this->mapItems($order->getAllVisibleItems()),
            'shipping_method' => $order->getShippingMethod(),
        ];

        $response = $this->apiClient->createOrder($payload);

        if (!$response->isAccepted()) {
            $this->logger->error('Fulfillment provider rejected order', ['order' => $order->getIncrementId()]);
            throw new \RuntimeException('Fulfillment export rejected: ' . $response->getReason());
        }
    }

    /**
     * Maps a Magento shipping address to the provider address format.
     *
     * @param \Magento\Sales\Api\Data\OrderAddressInterface $address Order shipping address
     * @return array Address payload for the fulfillment API
     */
    private function mapAddress($address): array
    {
        return [
            'name' => $address->getFirstname() . ' ' . $address->getLastname(),
            'street' => implode(' ', $address->getStreet()),
            'city' => $address->getCity(),
            'postal_code' => $address->getPostcode(),
            'country' => $address->getCountryId(),
        ];
    }

    /**
     * Maps Magento order items to the provider item format.
     *
     * @param array $items Visible order items
     * @return array List of item payloads with SKU and quantity
     */
    private function mapItems(array $items): array
    {
        return array_map(static fn ($item) => [
            'sku' => $item->getSku(),
            'quantity' => (int) $item->getQtyOrdered(),
        ], $items);
    }
}

4. Lagerbestand und MSI-Synchronisation

Da der physische Bestand beim Fulfillment-Provider liegt, muss Magento über Multi Source Inventory regelmäßig aktuelle Bestandsdaten vom Provider empfangen. Die Fulfillment-Integration bildet dafür in MSI eine eigene Source für das externe Lager ab, deren Bestandsmenge ausschließlich über den Bestandsimport aktualisiert wird, nie manuell im Magento-Adminbereich. So bleibt eindeutig, welches System für welchen Wert verantwortlich ist.

Kritisch ist die Häufigkeit dieser Synchronisation: Ein täglicher Bestandsabgleich reicht bei Fast-Moving-Artikeln oft nicht aus und führt zu Überverkäufen, die im Nachhinein storniert werden müssen. Die meisten produktiven Fulfillment-Integrationen nutzen deshalb einen ereignisbasierten Bestandsabgleich, bei dem der Provider jede relevante Bestandsänderung sofort über einen Webhook meldet, ergänzt um einen stündlichen Vollabgleich als Sicherheitsnetz gegen verlorene Einzelereignisse.

5. Versandstatus und Tracking-Updates verarbeiten

Sobald der Fulfillment-Provider eine Bestellung verpackt und einem Versanddienstleister übergeben hat, muss die Fulfillment-Integration diesen Status inklusive Tracking-Nummer zurück nach Magento übertragen, damit der Kunde in seinem Kundenkonto den aktuellen Versandstatus sieht und die entsprechende Versandbestätigungs-E-Mail ausgelöst wird. Technisch bedeutet das, für die betroffene Bestellung einen Magento-Shipment-Datensatz mit der Tracking-Nummer des jeweiligen Versanddienstleisters anzulegen.

Bei Teillieferungen, wenn ein Artikel aus einer Bestellung separat versendet wird, muss die Fulfillment-Integration mehrere Shipment-Datensätze pro Bestellung korrekt abbilden können, jeweils mit den zugehörigen Artikelpositionen und einer eigenen Tracking-Nummer. Ein häufiger Implementierungsfehler ist, nur ein einziges Shipment pro Bestellung vorzusehen, was bei Teillieferungen zu falschen oder unvollständigen Tracking-Informationen im Kundenkonto führt.

{
  "event": "shipment.dispatched",
  "order_reference": "100003421",
  "shipment_id": "ffl-8821-1",
  "carrier": "dhl",
  "tracking_number": "00340434123456789012",
  "items": [
    { "sku": "SHIRT-BLUE-M", "quantity": 2 }
  ]
}

6. Retouren-Workflow mit dem Fulfillment-Partner

Retouren sind bei einer Fulfillment-Integration oft der am wenigsten durchdachte Teil, weil sie im Gegensatz zum Bestellprozess keinen linearen Ablauf haben. Ein Kunde meldet eine Retoure im Magento-Kundenkonto oder per E-Mail an, das physische Paket geht aber direkt an das Lager des Fulfillment-Providers, nicht an Magento. Die Fulfillment-Integration muss deshalb eine Rückmeldung vom Provider verarbeiten können, sobald die retournierte Ware im Lager eingegangen und geprüft wurde.

Diese Rückmeldung löst in Magento typischerweise die Erstellung einer Gutschrift und je nach Zustand der Ware eine Bestandskorrektur in der entsprechenden MSI-Source aus. Wichtig ist, dass die Fulfillment-Integration zwischen wiederverkaufsfähiger und beschädigter Ware unterscheidet, weil nur erstere den verfügbaren Bestand erhöhen darf. Ohne diese Unterscheidung verkauft der Shop Artikel erneut, die tatsächlich nicht mehr verkaufsfähig sind.

7. Fehlerszenarien: Teillieferungen und Abweichungen

In der Praxis treten bei jeder Fulfillment-Integration Abweichungen auf: Ein Artikel ist im Lager tatsächlich nicht verfügbar, obwohl der Bestand das signalisiert hatte, eine Adresse ist unzustellbar, oder der Provider kann nur einen Teil der Bestellung ausliefern. Für jedes dieser Szenarien braucht die Integration einen definierten Rückkanal: Bei einem nicht verfügbaren Artikel storniert das System automatisch die betroffene Position und informiert den Kunden, statt die gesamte Bestellung unbestimmt in der Warteschleife zu belassen.

Bei Teillieferungen muss die Fulfillment-Integration zwischen einer geplanten Teillieferung, etwa weil ein Artikel aus einem anderen Lager nachgeliefert wird, und einer ungeplanten Teillieferung wegen tatsächlicher Bestandsabweichung unterscheiden. Nur bei Letzterer sollte automatisch eine Benachrichtigung an das Category Management gehen, damit die Bestandsdaten im PIM oder ERP korrigiert werden, bevor sich der Fehler wiederholt.

8. SLA-Monitoring und Eskalationsprozesse

Fulfillment-Provider arbeiten in der Regel mit vertraglich vereinbarten Service Level Agreements, etwa einer maximalen Zeit zwischen Bestelleingang und Versand. Eine gute Fulfillment-Integration misst diese Zeit automatisch für jede Bestellung und meldet Überschreitungen, statt sich auf manuelle Stichproben zu verlassen. Ein Dashboard, das die durchschnittliche und die maximale Verarbeitungszeit der letzten 24 Stunden zeigt, deckt systematische Probleme beim Provider auf, bevor Kunden sich beschweren.

Für kritische Abweichungen, etwa wenn eine Bestellung seit mehr als 48 Stunden ohne Versandbestätigung im System steht, sollte die Fulfillment-Integration automatisch eine Eskalation an den zuständigen Ansprechpartner beim Provider auslösen, statt darauf zu warten, dass ein Mitarbeiter des Shops den Rückstand manuell entdeckt. Diese Automatisierung reduziert die Reaktionszeit bei echten operativen Problemen erheblich.

9. Anbindungsmodelle im Vergleich

Für die technische Anbindung eines Fulfillment-Providers stehen mehrere Modelle zur Wahl, die sich in Latenz und Implementierungsaufwand deutlich unterscheiden.

Für die meisten Magento-Shops mit einem einzelnen Fulfillment-Provider ist eine REST-API-Kopplung mit ereignisbasierten Webhook-Ergänzungen für zeitkritische Ereignisse wie Bestandsknappheit der beste Kompromiss aus Implementierungsaufwand und Aktualität. Wer mehrere Provider gleichzeitig orchestriert, etwa für unterschiedliche Länder, profitiert von einer dedizierten Fulfillment-Middleware, die die Fulfillment-Integration für alle Provider vereinheitlicht.

10. Zusammenfassung

Eine belastbare Fulfillment-Integration in Magento 2 trennt Bestellexport, Bestandsabgleich und Versandstatus-Import in drei unabhängige, asynchrone Datenflüsse mit jeweils eigenen Latenzanforderungen. MSI bildet den Bestand des Fulfillment-Providers als eigene Source ab, Shipment-Datensätze mit korrekter Tracking-Nummer machen Teillieferungen für den Kunden nachvollziehbar, und ein durchdachter Retouren-Workflow unterscheidet zwischen wiederverkaufsfähiger und beschädigter Ware.

Fehlerszenarien wie unzustellbare Adressen oder tatsächliche Bestandsabweichungen brauchen definierte, automatisierte Rückkanäle statt manueller Nacharbeit. SLA-Monitoring mit automatischer Eskalation stellt sicher, dass Verzögerungen beim Fulfillment-Provider auffallen, bevor sie sich in Kundenbeschwerden niederschlagen. Diese Bausteine zusammen machen eine Fulfillment-Integration zu einem robusten, weitgehend unsichtbaren Teil der Bestellabwicklung.

11. FAQ: Fulfillment-Provider an Magento 2 anbinden