Integrationskonzept – Haufe X360 ? nopCommerce 4.8, erstellt am: 2025-09-09
1. Ziel & Scope
Ziel ist die Echtzeit-nahe Anbindung von Haufe X360 (Acumatica-basiertes ERP) an nopCommerce 4.8 mittels Eigenentwicklung über das Commerce API Framework. Die Integration umfasst Produkte, Lagerbestände, Kunden, Adressen, Bestellungen und Versandinformationen.
2. Architekturübersicht
Die Integration erfolgt über dieses Plugin und einen Webservice in nopCommerce, das REST-Endpunkte bereitstellt. Haufe X360 und nopCommerce kommunizieren über REST-API (OAuth2) mit dem Plugin. Die Kommunikation ist zeit- und ereignisgesteuert (Push/Webhook oder Polling).
3. Endpunkte & Datenflüsse
Folgende Endpunkte werden im Plugin bzw. Webservice bereitgestellt:
- POST /Plugins/Acme.Sync/ProductUpsert
- POST /Plugins/Acme.Sync/InventorySync
- POST /Plugins/Acme.Sync/CustomerUpsert
- POST /Plugins/Acme.Sync/AddressUpsert
- POST /Plugins/Acme.Sync/OrderCreate
- POST /Plugins/Acme.Sync/ShipmentUpdate
4. Sicherheitskonzept
Die Endpunkte sind durch HMAC-Signaturen abgesichert. Jeder Request enthält die Header X-Timestamp, X-Nonce und X-Signature. Zusätzlich wird Idempotenz durch externe Schlüssel (z.?B. externalCustomerId, externalRef) sichergestellt.
5. Preis- & Steuerlogik
Preise werden aus X360 übernommen. PriceClasses werden auf CustomerRoles im Shop gemappt. Steuerzonen (TaxZones) und Steuerkategorien (TaxCategories) werden 1:1 übernommen. Die Brutto-/Netto-Logik wird synchronisiert.
6. Adressvalidierung
Vor dem Speichern von Adressen erfolgt eine Validierung Die Validierung ist fail-soft: ungültige Adressen werden markiert, aber nicht blockiert.
7. Multi-Warehouse Handling
Lagerbestände werden je Lager (Warehouse) übertragen. nopCommerce führt Bestände pro Lager. Die Lagercodes werden 1:1 zwischen X360 und nop gemappt.
8. Teststrategie
Es werden Unit-Tests für DTOs und Services sowie End-to-End-Tests durchgeführt. Besonderes Augenmerk liegt auf Preis-/Steuerkonsistenz, Adressvalidierung, Idempotenz und Fehlerbehandlung.
9. Risiken & Mitigation
- OAuth2-Komplexität: Mit Refresh-Token und Zeitdrift-Handling mitigiert.
- Datenqualität (Adressen): Durch Validierung und Logging mitigiert.
- Preislogik unklar: Platzhalterstruktur implementiert, später konfigurierbar.
- Rate Limits: Retry-Mechanismus mit Backoff implementiert.
10. Projektplan (Phasen & Milestones)
- Phase 1: Setup, Endpunkte, X360 Auth
- Phase 2: Business-Logik, Inventory, Orders
- Phase 3: Preis-/Steuerlogik, Adressvalidierung, Tests
- Phase 4+: Optionale Features, kundenspezifische Anpassungen
