Magento 2#

Magento 2 – Ausgang via REST-API (POST /rest/V1/orders). Benötigtes Addon: connector_magento2.

Überblick#

Mit dieser Integration legt Orderport Bestellungen, die aus einem anderen Kanal stammen (z. B. Ariba, Coupa, EDIFACT oder ein JSON-Webhook), direkt als Magento-2.4-Bestellung an – inklusive Kunde, Liefer- und Rechnungsadresse, Positionen sowie Zahlungs- und Versandart.

Magento ist in Orderport ein reines Zielsystem: Es gibt keinen Eingangs-Webhook von Magento. Orderport empfängt die Bestellung über einen der üblichen Eingänge, transformiert sie und schreibt sie per REST-API in den Shop.

Typischer Einsatzfall:

• Sie nehmen Bestellungen aus einem B2B-Einkaufsportal (cXML) oder per EDIFACT entgegen und wollen sie automatisch als Bestellung in Ihrem Magento-Shop sehen – ohne ein eigenes Magento-Modul zu entwickeln und zu pflegen.

Kompatibilität#

Unterstützte Versionen#

Bekannte Einschränkungen#

• Nur Ausgang. Magento sendet keine Bestellungen an Orderport. Die Integration legt ausschließlich Bestellungen in Magento an.
• Bestellungen werden als Gast angelegt. Jede importierte Order wird mit customer_is_guest = 1 erzeugt. Es findet kein Matching auf bestehende Magento-Kunden statt (anders als bei Shopware 6).
• Artikel müssen in Magento existieren. Positionen werden per SKU als product_type: simple übergeben. Magento weist die Bestellung zurück, wenn eine SKU nicht existiert – es gibt keinen Fallback auf „custom line items".
• Keine Versandkosten. shipping_amount wird fest auf 0.00 gesetzt; Versandkosten aus dem Quellsystem werden nicht übernommen.
• Eine Lieferadresse pro Bestellung (kein Split-Shipping).
• Ein Steuersatz pro Bestellung. Es wird ein konfigurierbarer Standard-Steuersatz auf die gesamte Bestellung angewendet – keine positionsabhängigen Steuersätze.
• Status-Updates/Stornierungen fließen nicht zurück. Eine einmal angelegte Bestellung wird von Orderport nicht weiter aktualisiert.
• Nur Einzelbestellungen. Keine Batch-Imports mehrerer Orders in einem Request.

Authentifizierung#

Orderport authentifiziert sich mit einem Integration Access Token (Bearer) an der Magento-REST-API. Der Token ist permanent – es gibt keinen OAuth-Token-Tausch und kein Ablaufdatum. Sie erzeugen ihn einmalig im Magento-Admin (siehe Einrichten im Shop).

Magento liefert vier Werte – Orderport braucht nur einen. Beim Aktivieren einer Integration zeigt Magento Consumer Key, Consumer Secret, Access Token und Access Token Secret an – das sind die vollständigen OAuth-1.0a-Zugangsdaten für signierte Requests. Orderport nutzt stattdessen Token-Authentifizierung und schickt nur den Access Token als Bearer-Header (Authorization: Bearer {access_token}). Tragen Sie also ausschließlich den Access Token ein; Consumer Key/Secret und Access Token Secret werden nicht benötigt.

Der Token wird in Orderport verschlüsselt gespeichert (Crypt) und nur zur Laufzeit zum Versand verwendet.

Einrichten in Orderport#

Pipeline anlegen (Ausgang nach Magento)#

1. Pipelines → Neue Pipeline → Simple Wizard → Ziel: Magento 2
2. Shop-URL und Integration Access Token eingeben, dann „Verbinden & Stores laden"
3. Sobald die Verbindung steht, lädt Orderport die Store Views aus Magento (/rest/V1/store/storeViews)
4. Zieleinstellungen wählen bzw. bestätigen:
   • Store View – das Ziel, in dem die Bestellung angelegt wird
   • Zahlungsart-Code – Magento-Code, z. B. checkmo, banktransfer (Default: checkmo)
   • Versandart-Code – Format carrier_method, z. B. flatrate_flatrate (Default: flatrate_flatrate)
   • Steuersatz (%) – Standard-Steuersatz für die Bestellung (Default: 19)
   • State / Status – Magento-Bestellzustand (Defaults: new / pending)
5. Quelle (Eingangsformat) und Mapping einrichten – die KI-Vorschläge greifen die wesentlichen Felder automatisch
6. Transport wird automatisch auf REST API mit Adapter magento2 gesetzt (POST, application/json, Bearer-Token)

Den Experten-Wizard können Sie ebenfalls nutzen: Ausgabeformat JSON, Adapter magento2 – die Magento-Felder werden dann im Transport-Schritt erfragt.

Mapping#

Orderport schreibt in eine kanonische JSON-Struktur, die der magento2-Adapter in das Magento-Order-Entity übersetzt. Die verfügbaren Zielfelder sind unten dokumentiert. Spezialfälle (z. B. Preis-Modus brutto vs. netto) lassen sich im Mapping-Editor anpassen.

Einrichten im Shop#

Integration anlegen (Magento-Admin)#

1. System → Erweiterungen → Integrationen → Neue Integration hinzufügen
2. Name vergeben und mit Ihrem Admin-Passwort bestätigen
3. Im Reiter API die Ressourcen-Zugriffe wählen – mindestens:
   • Verkäufe → Vorgänge → Bestellungen → Erstellen (Anlegen von Orders)
   • Shops → Einstellungen → Alle Shops bzw. Lesezugriff auf Store Views (für den Verbindungstest)
4. Speichern → die Integration erscheint in der Liste
5. Aktivieren klicken und die Berechtigungen bestätigen → Magento zeigt nun den Access Token an
6. Den Access Token kopieren und in Orderport als Integration Access Token hinterlegen

Access Token als Bearer erlauben (Magento 2.4.4+)#

Seit Magento 2.4.4 dürfen Integration Access Tokens standardmäßig nicht als eigenständige Bearer-Tokens verwendet werden. Solange diese Option aus ist, lehnt Magento jeden REST-Aufruf mit 401 und der irreführenden Meldung „The consumer isn't authorized to access %resources." ab – unabhängig davon, welche Ressourcen die Integration freigeschaltet hat.

1. Stores → Configuration → Services → OAuth → Consumer Settings
2. Allow OAuth Access Tokens to be used as standalone Bearer tokens auf Yes / Ja setzen
3. Speichern und ggf. den Cache leeren

Dies ist eine globale OAuth-Einstellung, kein Berechtigungsproblem der Integration. Ohne sie funktioniert der Bearer-Token von Orderport nicht.

Die im Wizard angegebenen Codes für Zahlungs- und Versandart müssen aktiven Magento-Methoden entsprechen (z. B. checkmo = Scheck / Zahlungsanweisung, flatrate_flatrate = Pauschalbetrag). Stimmt der Code nicht mit einer aktivierten Methode überein, weist Magento die Bestellung zurück.

Technische Details#

Kanonische Eingangs-Struktur (Adapter-Input)#

Das Mapping schreibt in diese JSON-Struktur; der magento2-Adapter konsumiert sie:

{
  "order": {
    "number": "ORD-2024-001",
    "date": "2024-03-15",
    "currency": "EUR",
    "total": 1500.00
  },
  "customer": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "bestellung@muster.de",
    "phone": "+49 89 123456",
    "company": "Muster GmbH"
  },
  "shipping": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Industriestr. 42",
    "zip": "80331",
    "city": "München",
    "country": "DE"
  },
  "items": [
    { "sku": "WIDGET-001", "name": "Premium Widget Blau", "quantity": 10, "price": 150.00 }
  ]
}

Verfügbare Zielfelder#

Ausgangs-Payload (Magento-Order-Entity)#

Der magento2-Adapter erzeugt ein { "entity": { … } }-Objekt für POST /rest/V1/orders mit u. a.:

• store_id, state, status, *_currency_code
• customer_email, customer_firstname, customer_lastname, customer_is_guest: 1
• items[] (sku, name, qty_ordered, price, row_total, product_type: "simple")
• subtotal, subtotal_incl_tax, tax_amount, grand_total, total_qty_ordered
• shipping_amount: 0.00
• billing_address und extension_attributes.shipping_assignments[].shipping (Adresse + method)
• payment.method

Preis-Modus und Steuer#

Die Preise aus den Positionen werden 1:1 übernommen – Magento rechnet nichts neu. Orderport leitet Zwischensumme, Steuerbetrag und Gesamtbetrag aus den Positionen und dem Standard-Steuersatz ab:

• price_mode: "net" (Default) – die Positionspreise gelten als Netto; der Bruttowert wird mit dem Steuersatz hochgerechnet, anschließend wird die Steuer wieder herausgerechnet.
• price_mode: "gross" – die Positionspreise gelten als Brutto und werden direkt verwendet (price_incl_tax / row_total_incl_tax werden gesetzt).

Bei einem Steuersatz von 0 entfällt die Steueraufteilung; Zwischensumme = Gesamtbetrag.

Adapter-Konfiguration#

Die folgenden Werte werden im Wizard erfragt und im Transport unter config.magento2 abgelegt:

Hinweis: Die Shop-URL muss öffentlich erreichbar sein. URLs auf interne oder private Adressen werden beim Verbindungstest abgelehnt.

Fehlerbehebung#

Nächste Schritte#

• Feldmapping – Felder verfeinern und transformieren
• REST API – Transport-Details für den Ausgang
• cXML – häufige Quelle für Magento-Bestellungen