X-ERP Hilfe

03. Endpunktreferenz

Die 28 Standardoperationen für Sitzungen, Katalog, Warenkorb und Helpdesk mit Parametern und Ergebnissen.

1. Partner-Anmeldung und Sitzungen

Ein Portal kann Partner-Zugangsdaten prüfen und anschließend eine wiedererkennbare Partner-Sitzung verwalten:

  1. POST /api/Partner/ValidateCredentials prüft E-Mail-Adresse und Passwort aus dem JSON-Request-Body. Die Antwort enthält unter anderem isValid, isLockedOut, requiresPasswordChange und die ermittelte Partneridentität.
  2. POST /api/PartnerToken/CreateSession legt einen Sitzungseintrag mit partnerId, tokenHash und optional expiresAt, deviceInfo und ipAddress an. Ohne Ablaufdatum verwendet der dokumentierte Stand sieben Tage.
  3. POST /api/PartnerToken/ValidateSession prüft partnerId und tokenHash und aktualisiert die letzte Aktivität. Eine fehlende oder abgelaufene Sitzung wird mit HTTP 404 gemeldet.
  4. POST /api/PartnerToken/RevokeSession beendet eine einzelne Sitzung beim Abmelden.

Für eine Sitzungsverwaltung stehen außerdem POST /api/PartnerToken/RevokeAllSessions und GET /api/PartnerToken/{partnerId}/GetActiveSessions bereit. Beim Widerruf aller Sitzungen kann die aktuelle über excludeTokenHash ausgenommen werden.

Wichtig: Diese Funktionen verwalten die fachliche Portal-Sitzung. Der technische Cookie-Login für API-Benutzer ist im Unterkapitel „Anmeldung und Berechtigungen“ beschrieben. Ein PartnerToken-Hash ist kein Bearer-Token.

2. Artikelkatalog und partnerbezogene Informationen

Für einen B2B-Webshop liefert GET /api/Webshop/GetArticles Artikelinformationen mit optionalen Parametern categoryId und searchQuery sowie dem Partnerbezug PartnerId. Die Antwort kann Artikelbezeichnung, Bild, Preis, Verkaufspreis, Verfügbarkeit, Mindestmenge, Lieferzeit und Kategorien enthalten.

  • GET /api/Webshop/CarouselArticle/{articleId}/{PartnerId} lädt die Details eines einzelnen Artikels für den angegebenen Partner.
  • GET /api/Webshop/GetCarouselArticles liefert Artikel für hervorgehobene Bereiche und Karussells.
  • GET /api/Webshop/GetArticlesOrdered?PartnerId={partnerId} liefert bereits bestellte Artikel als partnerbezogene Vorschläge.
  • GET /api/Webshop/GetOtherArticlesSold?PartnerId={partnerId} liefert weitere an diesen Partner verkaufte Artikel.
  • GET /api/Webshop/GetCarouselImages lädt bei Bedarf Bilddatensätze getrennt von Artikeldaten.

Für Personalisierung und die Vorbereitung des Checkouts stehen unter /api/WebshopUserCart zusätzlich GetCustomerInfo, GetPartnerAddress und GetPartnerDiscountGroupInfo zur Verfügung. Das Kundenprofil enthält beispielsweise Partnergruppe, Sprache und Verkaufspreisliste; die Adressabfrage liefert die vorbelegbaren Rechnungs- und Lieferadressen. Die Rabattabfrage benötigt ArticleGroupId und DiscountGroupNameId.

3. Warenkorb und Bestellung

Die Warenkorb-API bildet einen vollständigen Bestellablauf ab:

  1. GET /api/WebshopUserCart/GetWebshopUserCart?partnerId={partnerId} lädt Warenkorbpositionen, Summen und Benutzeradressinformationen.
  2. POST /api/WebshopUserCart/AddToCart?partnerId={partnerId} fügt einen Artikel hinzu oder erhöht dessen Menge. Der JSON-Body enthält beispielsweise {"articleId":"ART-1000","quantity":2}.
  3. PUT /api/WebshopUserCart/UpdateCartItem?id={cartItemId}&quantity={newQuantity} ändert eine Positionsmenge. Menge 0 entfernt die Position; negative Mengen werden fachlich abgelehnt.
  4. POST /api/WebshopUserCart/WebshopPlaceOrder?partnerId={partnerId}&employeeId={employeeId} wandelt den Warenkorb in einen X-ERP-Verkaufsbeleg um. Der JSON-Body enthält deliveryAddress und billingAddress. Achtung: Die gelieferte Referenz beschreibt eine Beleg-ID im Feld data. Der am 18.09.2026 geprüfte Controller liefert tatsächlich data = 1. Verwenden Sie diesen Wert daher nicht als Beleg-ID; vereinbaren und testen Sie die Belegzuordnung für Ihre Serverversion.
  5. POST /api/WebshopUserCart/ClearCart?partnerId={partnerId} leert den Warenkorb auf ausdrücklichen Aufruf. Der geprüfte Bestellabschluss entfernt bereits selbst die Warenkorbpositionen. Ein zusätzlicher ClearCart-Aufruf nach Checkout ist deshalb dort nicht erforderlich.

GET /api/WebshopUserCart/WebshopUserCartCount?partnerId={partnerId} liefert die Summe der Mengen für eine Warenkorbanzeige. Artikelbewertungen können mit POST /api/WebshopUserCart/GiveRating gespeichert und mit GET /api/WebshopUserCart/GetRatings?partnerId={partnerId} gelesen werden.

Beim Bestellabschluss bedeutet HTTP 404, dass kein Warenkorb vorhanden ist; HTTP 422 kann einen leeren Warenkorb anzeigen. Eine Bestellanforderung nach einem Verbindungsabbruch nicht ungeprüft erneut auslösen: Zuerst klären, ob bereits ein Beleg angelegt wurde. Das vorliegende Partner-Paket beschreibt keinen Idempotenzschlüssel für diesen Aufruf.

4. Helpdesk im Partnerportal

Ein angebundenes Portal kann Kategorien, Tickets und deren Verlauf anzeigen:

  • GET /api/HelpdeskCategory/PageHelpdeskCategorysByParent/{ParentId}/{IncludeSubNodes}/{TopParentsOnly} lädt Kategorien für Navigation und Zuordnung.
  • GET /api/Helpdesk/{PartnerId}/{MyHelpdesksOnly}/PageFromViewForPartner liefert die partnerbezogene Ticketliste.
  • GET /api/HelpdeskDialog/{HelpdeskId}/PageFromViewByHelpdeskId lädt die Dialogeinträge eines Tickets.
  • GET /api/HelpdeskDialogProtocol/{HelpdeskId}/PageByHelpdeskId lädt die zugehörigen Protokolleinträge.

PUT /api/Helpdesk aktualisiert einen Helpdesk-Datensatz mit einem vollständigen Helpdesk-Objekt im Request-Body. Dieser Schreibzugriff wird nur eingesetzt, wenn die direkte Ticketbearbeitung für den Partner ausdrücklich vereinbart ist. Statusänderungen können eine Benachrichtigungsverarbeitung auslösen.

Rechte, Antworten und Fehler richtig behandeln

WebApi-Rechte orientieren sich am Controller und der Operation, beispielsweise Webshop-Read, WebshopUserCart-Create, Helpdesk-Update und PartnerToken-Read. Fehlt ein benötigtes Recht, antwortet X-ERP mit HTTP 403 und einer Meldung zum fehlenden Recht.

Viele Detail- und Schreibaufrufe verwenden APIEntityResponse<T> mit den Feldern success, data und errorMessages. Ein HTTP-Status 200 bedeutet deshalb nicht automatisch fachlichen Erfolg: Die Integration muss zusätzlich success und die Fehlermeldungen auswerten.

Listen für Kategorien und Helpdesk verwenden teilweise direkt ein Seiten- beziehungsweise Grid-Ergebnis mit DataSourceLoadOptions. Für Seitennavigation und Filterung sind unter anderem skip, take, sort, filter und requireTotalCount vorgesehen. Das genaue Format wird anhand der Referenz und der eingesetzten Serverversion abgestimmt.

Behandeln Sie mindestens HTTP 400 für unvollständige oder fehlerhafte Anfragen, HTTP 403 für fehlende Rechte, HTTP 404 für nicht gefundene Objekte oder Sitzungen sowie HTTP 422 für fachliche Validierungsfehler. Beachten Sie außerdem die genaue Parameterposition: Auch POST- und PUT-Aufrufe können neben einem JSON-Body zusätzliche Query-Parameter verlangen.

Vollständige Datenmodelle

Die OpenAPI-Datei und Beispielvorlagen gehören zum separat bereitzustellenden Entwicklerpaket.

Die OpenAPI-Datei enthält alle 28 Standardoperationen und die gelieferten Schemas. Sie enthält bewusst keine automatisch freigegebenen internen oder eingeschränkten Erweiterungen. Den zusätzlichen technischen Cookie-Login beschreibt der Schnellstart. Beachten Sie die Versionsabweichungen beim Bestellabschluss im Kapitel „Freigaben und Versionshinweise“.

Helpdesk-Update

PUT /api/Helpdesk erwartet ein vollständiges Helpdesk-Objekt, keinen beliebigen Teil-Patch. Das gelieferte OpenAPI-Schema beschreibt Helpdesk nur offen und ohne vollständig ausformulierte Eigenschaften. Vor einem schreibenden Helpdesk-Projekt müssen deshalb das zur Zielversion passende Modell und ein freigegebenes vollständiges Beispiel vom Betreiber vorliegen.