Shop-Import & Connector

Transaktionen: SAL16 Aufträge, SAL31 Tracking No. Import
Controller: SalesHeadApiController, SalesImportApiController
Basis: /api/salesHead/connector, /api/salesHead/importOrders, /api/salesImport

Business-Zweck

Der Connector-Flow ist reybex' Standardmuster für Shop-, Marktplatz- und Fulfillment-Systeme, die per REST (nicht über OMP-Jobs) Aufträge übergeben und Status zurückmelden. Typische Partner-Rolle:

Import – Shop-Bestellungen als SalesHead (Order) anlegen
Export/Polling – offene Aufträge aus reybex lesen (connectorStatus=0)
Rückmeldung – Tracking, Lieferschein, Rechnung, Abschluss (connectorStatus=1)

Im Gegensatz zum OMP-Modul (Amazon/eBay-Jobs, MarktplaceOrderTransfer) arbeitet der Connector pull-basiert: Das Partnersystem pollt reybex und bestätigt Bearbeitung.

→ Gesamtflow: Order-to-Cash

Kernbegriffe

Begriff	Bedeutung
`connectorStatus`	`0` = offen für Connector, `1` = vom Partner bearbeitet/abgeschlossen
`marktplaceOrderId`	Externe Shop-Bestellnummer – Idempotenz-Schlüssel
`marktplace`	Kanal-Referenz (z. B. Marktplace „Connector“)
`saveForConnector`	Backend-Methode hinter `POST /connector`
`showForConnector`	Backend-Methode hinter `GET /connector`
`SendPacks`	Packstück mit Tracking (`licenseplate`, `trackingCode`)
`referencingDocuments`	Kombi: LS + RE + Tracking in einem Connector-Call
`OrderStatus`	Workflow-Status (in Bearbeitung / abgeschlossen)

Connector-Lifecycle

connectorStatus im Detail

Wert	Bedeutung	GET /connector
`0`	Offen – Partner soll bearbeiten	Enthalten
`1`	Geschlossen – Rückmeldung erfolgt	Nicht enthalten

Zusätzliche Filter in showForConnector:

isDelete = 0
blockedDelivery = 0
DocType isOrder = 1 (oder FBA-Variante)
Positionen ohne Storno-Status (orderItemStatus not in 5, 12)

Architektur – Connector vs. OMP

Aspekt	Connector	OMP
Protokoll	REST Pull/Push	Interne Jobs + Marktplace-Konfig
Typische Quelle	Eigener Shop, Custom ERP	Amazon, eBay, …
Statusfeld	`connectorStatus`	`MarktplaceOrderTransfer.processingStatus`
Tracking-Rückmeldung	`POST /connector` + `sendPacks`	Marktplace-Action `updateOrders`
Doku	Diese Seite	OMP-Modulübersicht

Phase 1 – Auftrag importieren

Variante A: Standard Save (empfohlen)

Einzel- oder Batch-Anlage über normales Save – mit Pflichtfeld marktplaceOrderId:

json

POST /api/salesHead/
{
  "docType": { "id": 300001 },
  "customer": { "id": 1000001 },
  "marktplaceOrderId": "SHOP-2026-998877",
  "marktplace": { "id": 400001 },
  "orderDate": "2026-09-10T14:30:00",
  "orderDescription": "Shop #998877",
  "paymcond": { "id": 100001 },
  "currency": { "id": 1 },
  "receiver": {
    "name": "Max Mustermann",
    "street": "Hauptstraße 1",
    "zipcode": "10115",
    "city": "Berlin",
    "country": { "code": "DE" }
  },
  "items": [
    {
      "itemNumber": 1,
      "material": { "matCode": "SKU-RED-M" },
      "quantity": 2,
      "price": 29.99,
      "grossPrice": 35.69,
      "vatKey": { "id": 1 },
      "warehouse": { "id": 500001 }
    }
  ]
}

Response:

json

{
  "id": 1234567890123456,
  "docNumber": "AU-2026-00789",
  "connectorStatus": 0,
  "marktplaceOrderId": "SHOP-2026-998877",
  "totalAmount": 71.38
}

Variante B: importOrders

json

POST /api/salesHead/importOrders
{
  "orders": [
    {
      "marktplaceOrderId": "SHOP-2026-998878",
      "customerNo": "K-10001",
      "items": [
        { "matCode": "SKU-BLUE-L", "quantity": 1, "price": 39.99 }
      ]
    }
  ]
}

Hinweis Backend

Der Endpoint validiert u. a. das Vorhandensein eines Marktplace „Connector“. Partner sollten für produktive Importe POST /api/salesHead/ mit vollständigem SalesHead-Objekt bevorzugen und importOrders nur nutzen, wenn vom Projektteam freigegeben.

Idempotenz mit marktplaceOrderId

Regel: Vor jedem Import prüfen, ob bereits ein Auftrag mit gleicher marktplaceOrderId existiert.

bash

curl -G "$BASE_URL/api/salesHead/salesOrders" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter=marktplaceOrderId~eq~SHOP-2026-998877"

Situation	Verhalten Partner
Kein Treffer	Neu anlegen
Treffer, `connectorStatus=0`	Update statt Neuanlage (PATCH/save mit `id`)
Treffer, `connectorStatus=1`	Kein erneuter Import – ggf. Retoure SAL20

Phase 2 – Offene Aufträge exportieren (Polling)

bash

curl -G "$BASE_URL/api/salesHead/connector" \
  -H "Authorization: Bearer $TOKEN"

Optionale Query-Parameter:

Parameter	Wirkung
`vendor`	Nur Aufträge mit Material des Lieferanten (`customerNo`)
`isNotVirtualMaterial=1`	Keine virtuellen Artikel
`status=closed`	Nur `salesHead.status=2`
`isFbaOrSalesOrders=1`	Orders oder FBA
`isInvoiceSend=1`	E-Rechnung versendet – Spezialfall Rückmeldung

Response-Struktur (vereinfacht):

json

{
  "orders": [
    {
      "id": 1234567890123456,
      "docNumber": "AU-2026-00789",
      "connectorStatus": 0,
      "marktplaceOrderId": "SHOP-2026-998877",
      "customer": { "id": 1000001, "customerNo": "K-10001", "name": "Muster GmbH" },
      "items": [
        {
          "id": 9876543210,
          "material": { "matCode": "SKU-RED-M" },
          "quantity": 2,
          "openQuantity": 2,
          "deliveryStatus": 0
        }
      ]
    }
  ]
}

Polling-Empfehlung: Intervall 1–5 Minuten, max. 100 Aufträge pro Call (Backend-Limit). Bei Leerliste Backoff nutzen.

Phase 3 – Rückmeldung an Connector (saveForConnector)

POST /api/salesHead/connector verarbeitet ein Array salesHeads. Pro Eintrag eine der folgenden Aktionen:

3.1 Nur Status „in Bearbeitung“

json

{
  "salesHeads": [
    { "id": 1234567890123456 }
  ]
}

Setzt connectorStatus=1, orderStatus=inProcess (Typ 1).

3.2 Tracking / Packstück melden

json

{
  "salesHeads": [
    {
      "id": 1234567890123456,
      "sendPacks": {
        "licenseplate": "00340434161234567890",
        "carrierName": "DHL Paket"
      }
    }
  ]
}

Legt SendPacks an (wenn Tracking neu)
Setzt isSend=true, Versandart aus Shipping.name
connectorStatus=1, orderStatus=completed
Optional: MarktplaceOrderTransfer für OMP-Rückkanal

Response:

json

{
  "salesHeads": [
    {
      "id": 1234567890123456,
      "docNumber": "AU-2026-00789",
      "success": true,
      "message": "success",
      "sendPackId": 5555666677778888
    }
  ]
}

3.3 Rechnungsnummer als Connector-Referenz

json

{
  "salesHeads": [
    {
      "id": 1234567890123456,
      "invoiceNumber": "RE-EXTERN-12345"
    }
  ]
}

Setzt connectorReferenceNumber – für Shops, die externe Rechnungsnummern führen.

3.4 Kombi: Lieferschein + Rechnung + Tracking (referencingDocuments)

Vollständiger O2C-Abschluss in einem Call:

json

{
  "salesHeads": [
    {
      "id": 1234567890123456,
      "referencingDocuments": {
        "deliveryNoteDocTypeName": "Lieferschein Standard",
        "invoiceDocTypeName": "Rechnung Standard",
        "sendPackDocTypeName": "Lieferschein Standard",
        "trackingNumber": "00340434161234567890",
        "carrierName": "DHL Paket"
      }
    }
  ]
}

Pflichtfelder (Backend-Validierung):

deliveryNoteDocTypeName – Name des LS-DocTypes (isDelnote=true)
invoiceDocTypeName – Name des RE-DocTypes (isInvoice=true)
sendPackDocTypeName – muss gleich LS- oder RE-DocType-Name sein
trackingNumber, carrierName

Response bei Erfolg:

json

{
  "salesHeads": [
    {
      "id": 1234567890123456,
      "docNumber": "AU-2026-00789",
      "success": true,
      "deliveryNoteId": 1111222233334444,
      "invoiceId": 2222333344445555,
      "sendPackId": 5555666677778888
    }
  ]
}

Intern: referencingDocuments → Pack anlegen → connectorStatus=1.

Phase 4 – Tracking-Import (SAL31)

Für Massen-Updates aus Carrier-CSV (parallel zum Connector):

json

POST /api/salesImport/importFromCSV
{
  "importType": "tracking",
  "delimiter": ";",
  "mapping": {
    "docNumber": 0,
    "trackingNumber": 1,
    "carrierName": 2
  },
  "rows": [
    ["AU-2026-00789", "00340434161234567890", "DHL Paket"]
  ]
}

→ Sales Import API, Umlagerung & Import

Vollständiges Partner-Beispiel (cURL)

Schritt 1 – Auftrag anlegen

bash

curl -X POST "$BASE_URL/api/salesHead/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @order.json

Schritt 2 – Offene Orders pollen

bash

curl -G "$BASE_URL/api/salesHead/connector" \
  -H "Authorization: Bearer $TOKEN"

Schritt 3 – Nach Fulfillment abschließen

bash

curl -X POST "$BASE_URL/api/salesHead/connector" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "salesHeads": [{
      "id": 1234567890123456,
      "referencingDocuments": {
        "deliveryNoteDocTypeName": "Lieferschein Standard",
        "invoiceDocTypeName": "Rechnung Standard",
        "sendPackDocTypeName": "Lieferschein Standard",
        "trackingNumber": "00340434161234567890",
        "carrierName": "DHL Paket"
      }
    }]
  }'

Partner-Szenarien

Szenario 1 – Pure Fulfillment (WMS übernimmt LS/RE)

Shop → POST /salesHead/ mit marktplaceOrderId
WMS pollt GET /connector
WMS kommissioniert (INV06)
WMS meldet POST /connector mit referencingDocuments
Shop erhält Tracking aus Response

Szenario 2 – Nur Tracking-Rückmeldung

Lieferschein/Rechnung manuell in reybex UI
Partner meldet Tracking: POST /connector mit sendPacks
OMP-Marktplatz erhält ggf. updateOrders-Transfer

Szenario 3 – Drop-Shipping

Order-Import wie oben
POST /api/salesItem/createPurchaseRequest für fehlenden Bestand
PUR → WE → dann Connector-Rückmeldung

→ PUR Modulübersicht

Szenario 4 – Teillieferung

POST /api/salesHead/splitSales vor Connector-Abschluss
Pro Teillieferung separater referencingDocuments-Call
Restauftrag bleibt connectorStatus=0

Voraussetzungen

Voraussetzung	Modul
Order-DocType + Nummernkreis	SAL Konfiguration
DocType-Namen exakt für referencingDocuments	SAL (Groß/Kleinschreibung beachten)
Shipping/Carrier-Stamm (`carrierName`)	SMP / Versand
SalesHeadDocRule Order→DelNote→Invoice	SAL
Kunde + Material + Preise	SAL01, BAS02, SAL09
API-Berechtigung SAL16	PMS

Auswirkungen im ERP

Aktion	ERP-Wirkung
Order-Import	Reservierung INV, `connectorStatus=0`
sendPacks	`SendPacks`, `isSend`, ggf. MarktplaceTransfer
referencingDocuments	LS + RE + Bestandsabgang + Forderung
connectorStatus=1	Auftrag aus Export-Queue
Tracking CSV SAL31	Packstücke ohne Connector

Typische Fehlerquellen

Fehler	Ursache	Lösung
`salesHead does not exist`	Falsche ID in POST connector	ID aus GET /connector
DocType-Name nicht gefunden	Tippfehler in `*DocTypeName`	Exakten Namen aus SAL-Konfig
`sendPackDocTypeName must equal...`	Falscher Pack-Bezug	LS oder RE Name verwenden
`blocked for delivery`	`blockedDelivery=true`	Sperre in SAL16 aufheben
Duplikat-Auftrag	Keine Idempotenz	`marktplaceOrderId` prüfen
Pack existiert bereits	Gleiches `licenseplate`	Idempotent ignorieren oder neues Tracking
Carrier unbekannt	`Shipping.name` fehlt	Versandart anlegen
Leere GET /connector	Alle `connectorStatus=1`	Normal nach Abschluss

Weiterlesen

Thema	Link
Gesamtflow O2C	Order-to-Cash
Aufträge Detail	Aufträge SAL16
SalesHead API	—
Folgedokumente	—
Tracking Import	—
OMP Marktplatz	OMP-Modul (interne Projekt-Doku)
Stammdaten	BAS, Kunden
Lager/Versand	INV, Kommissionierung

Shop-Import & Connector ​

Business-Zweck ​

Kernbegriffe ​

Connector-Lifecycle ​

connectorStatus im Detail ​

Architektur – Connector vs. OMP ​

Phase 1 – Auftrag importieren ​

Variante A: Standard Save (empfohlen) ​

Variante B: importOrders ​

Idempotenz mit marktplaceOrderId ​

Phase 2 – Offene Aufträge exportieren (Polling) ​

Phase 3 – Rückmeldung an Connector (saveForConnector) ​

3.1 Nur Status „in Bearbeitung“ ​

3.2 Tracking / Packstück melden ​

3.3 Rechnungsnummer als Connector-Referenz ​

3.4 Kombi: Lieferschein + Rechnung + Tracking (referencingDocuments) ​

Phase 4 – Tracking-Import (SAL31) ​

Vollständiges Partner-Beispiel (cURL) ​

Schritt 1 – Auftrag anlegen ​

Schritt 2 – Offene Orders pollen ​

Schritt 3 – Nach Fulfillment abschließen ​

Partner-Szenarien ​

Szenario 1 – Pure Fulfillment (WMS übernimmt LS/RE) ​

Szenario 2 – Nur Tracking-Rückmeldung ​

Szenario 3 – Drop-Shipping ​

Szenario 4 – Teillieferung ​

Voraussetzungen ​

Auswirkungen im ERP ​

Typische Fehlerquellen ​

Weiterlesen ​

Shop-Import & Connector

Business-Zweck

Kernbegriffe

Connector-Lifecycle

connectorStatus im Detail

Architektur – Connector vs. OMP

Phase 1 – Auftrag importieren

Variante A: Standard Save (empfohlen)

Variante B: importOrders

Idempotenz mit marktplaceOrderId

Phase 2 – Offene Aufträge exportieren (Polling)

Phase 3 – Rückmeldung an Connector (saveForConnector)

3.1 Nur Status „in Bearbeitung“

3.2 Tracking / Packstück melden

3.3 Rechnungsnummer als Connector-Referenz

3.4 Kombi: Lieferschein + Rechnung + Tracking (referencingDocuments)

Phase 4 – Tracking-Import (SAL31)

Vollständiges Partner-Beispiel (cURL)

Schritt 1 – Auftrag anlegen

Schritt 2 – Offene Orders pollen

Schritt 3 – Nach Fulfillment abschließen

Partner-Szenarien

Szenario 1 – Pure Fulfillment (WMS übernimmt LS/RE)

Szenario 2 – Nur Tracking-Rückmeldung

Szenario 3 – Drop-Shipping

Szenario 4 – Teillieferung

Voraussetzungen

Auswirkungen im ERP

Typische Fehlerquellen

Weiterlesen