Bestell-Endpunkt (Orders)

Hinweis: Import/Delete erfordern orders:write. Lagerbuchung erfolgt automatisch beim Create. Bestehende Audit-Logs (Status-History) bleiben revisionssicher erhalten.

Erstellt oder aktualisiert eine Bestellung. POST = Create, PUT mit orders_id = Update. Alle Felder werden über den zentralen OrderBuilder-Service validiert und persistiert.

Minimal-Payload (Create)

{
  "data": [{
    "customers_id": 51,
    "payment_method": "PayPal",
    "products": [
      {"products_id": 42, "quantity": 2, "products_price": "29.99"}
    ]
  }]
}

Voll-Payload mit allen Optionen

{
  "data": [{
    "customers_id": 51,
    "language_id": 2,
    "payment_method": "Stripe",
    "shipping_method": "DHL",
    "tax_flag": 1,
    "totals_mode": "auto",
    "expected_total": "59.98",
    "strict_totals": true,
    "currency": "EUR",
    "products": [
      {
        "products_id": 42,
        "quantity": 2,
        "products_price": "29.99",
        "products_tax": "19.00",
        "attributes": [
          {"option_id": 1, "value_id": 5}
        ]
      }
    ],
    "external_reference": {
      "source": "amazon",
      "external_id": "AMZ-12345"
    },
    "tracking": [
      {"service_provider": "DHL", "code": "1234567890", "link": "https://nolp.dhl.de/?piececode=1234567890"}
    ]
  }]
}

Über totals_mode wird gesteuert, wie die Bestellsummen berechnet werden:

Wenn tax_flag nicht explizit gesetzt ist, wird es aus der Kundengruppe abgeleitet:

• customers_groups.show_tax = 1 + DISPLAY_PRICE_WITH_TAX = true → tax_flag = 1 (Brutto)
• customers_groups.show_tax = 0 → tax_flag = 0 (Netto)
• Steuerbefreite Gruppen (z.B. EU-USt-ID) → tax_flag = 2 (Steuerfrei)

Interpretation von products_price je nach tax_flag

⚠️ Wichtig für Marktplatz-Importe: Wenn der Marketplace Netto-Preise schickt, MUSS tax_flag: 0 explizit gesetzt werden — sonst werden die Preise (bei einer Brutto-Kundengruppe) als Brutto interpretiert.

Wenn language_id nicht im Payload steht, wird kaskadiert aufgelöst:

1. Payload-Wert (wenn gesetzt)
2. customers.language_id aus dem Kundenstamm
3. DEFAULT_LANGUAGE aus der Shop-Konfiguration (Code-Lookup in languages-Tabelle)
4. Fallback: 1 (Englisch)

Hinweis: $_SESSION['languages_id'] ist im xoPort-Kontext bewusst KEIN Fallback — sonst würde die Sprache des Admin-API-Callers ungewollt auf die Kundenbestellung übertragen werden.

Optional kann der Caller den erwarteten Gesamtbetrag mitschicken — der Shop vergleicht und schlägt bei Abweichung Alarm:

• expected_total (decimal): Erwartete ot_total-Summe nach Berechnung.
• strict_totals (boolean, Default false):
  • false → Drift wird als Warnung in der Response ausgegeben, Bestellung wird trotzdem erstellt.
  • true → Bestellung wird abgelehnt, wenn berechneter Total ≠ expected_total (Toleranz: 0,01 €).

Verwendung: Marktplatz-Importe, wo der Marketplace die finale Summe schon kennt — Shop validiert, dass Preis × Menge × Steuer + Versand auch lokal die gleiche Summe ergeben.

Für Anbindungen, die nur Kundennummer, abweichende Lieferadresse und SKU/Menge kennen — die Bestellung wird so angelegt, dass sie Preise, Merkmale, Versand und Bestätigung exakt wie eine manuelle Shop-Bestellung trägt (Dropship-Parität, z. B. SPV → SST).

Steuerzeile pro Satz (v2.32.0): ot_tax wird je Steuersatz mit rate-genauem Titel im Frontend-Format geschrieben — „zzgl. USt. 19 %“ (Netto) bzw. „inkl. USt. 19 %“ (Brutto), sofern MODULE_ORDER_TOTAL_PREFIX=true.

external_reference — Marktplatz-Anbindung

Verknüpft die Bestellung mit einer externen Quelle. Erlaubte Felder:

• source (string, required): z.B. amazon, ebay, otto, kaufland.
• external_id (string, required): ID/Nummer beim Marketplace.
• marketplace_id (int, optional): Interne XONIC-Marketplace-ID.

tracking — Sendungsverfolgung

Array von Tracking-Einträgen. Pro Eintrag erlaubt:

• service_provider (alias: method): Carrier-Name (DHL, DPD, UPS, …).
• code (alias: tracking_number): Sendungsnummer.
• link: Tracking-URL.
• label_link: Versandlabel-URL (PDF).
• external_id: ID beim Versanddienstleister.
• is_retoure (bool): Retoure-Sendung statt Ausgangssendung.

status_history — Status-Verlauf

Append-only Audit-Log. Pro Eintrag: orders_status_id, comments, customer_notified (0/1), date_added.

customer_notified auf Order-Ebene

Boolean, kontrolliert ob beim Status-Wechsel der Bestätigungs-Mail-Versand getriggert wird.

curl -X POST "https://shop.de/xpanel/xoport/Import/JSON/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{
      "customers_id": 51,
      "payment_method": "PayPal",
      "tax_flag": 0,
      "expected_total": "71.38",
      "products": [{"products_id": 42, "quantity": 2, "products_price": "29.99", "products_tax": "19.00"}]
    }]
  }'

Beispiel-Response (Success)

{
  "success": true,
  "api_version": "2.32.0",
  "type": "orders",
  "operation": "create",
  "data": [{
    "orders_id": 46482,
    "customers_id": 51,
    "ot_subtotal": "59.98",
    "ot_tax": "11.40",
    "ot_total": "71.38",
    "totals_mode": "auto",
    "tax_flag": 0,
    "language_id": 2
  }],
  "warnings": []
}

Beispiel-Response (Drift-Check fehlgeschlagen, strict_totals=true)

{
  "success": false,
  "api_version": "2.32.0",
  "error": {
    "code": "TOTAL_DRIFT",
    "message": "Calculated ot_total 71.38 differs from expected_total 70.00 (diff: 1.38).",
    "details": {"expected": "70.00", "calculated": "71.38", "tolerance": "0.01"}
  }
}

Nicht-fatale Warnungen (Bestellung wird trotzdem angelegt, Rückgabe in warnings[]): PRODUCT_MODEL_NOT_FOUND, RECALC_PRODUCT_NOT_FOUND, CATEGORY_DISCOUNT_UNAVAILABLE, SHIPPING_AUTO_FAILED, SHIPPING_AUTO_EMPTY, TOTAL_DRIFT (außer bei strict_totals=true), UNKNOWN_FIELD.

Bestellungen lesen — Query-Parameter: