X-ERP Help

03. Endpoint reference

The 28 standard operations for sessions, catalog, shopping cart and help desk with parameters and results.

1. Partner authentication and sessions

A portal can verify partner credentials and then manage a recognizable partner session:

  1. POST /api/Partner/ValidateCredentials checks email address and password from the JSON request body. The response contains, among other things, isValid, isLockedOut, requiresPasswordChange and the discovered partner identity.
  2. POST /api/PartnerToken/CreateSession creates a session entry with partnerId, tokenHash and optionally expiresAt, deviceInfo and ipAddress. Without an expiration date, the documented status uses seven days.
  3. POST /api/PartnerToken/ValidateSession checks partnerId and tokenHash and updates the last activity. A missing or expired session is reported with HTTP 404.
  4. POST /api/PartnerToken/RevokeSession ends a single session on logout.

POST /api/PartnerToken/RevokeAllSessions and GET /api/PartnerToken/{partnerId}/GetActiveSessions are also available for session management. When revoking all sessions, the current one can be excluded via excludeTokenHash.

Important: These functions manage the business portal session. The technical cookie login for API users is described in the subchapter “Login and permissions”. A PartnerToken hash is not a bearer token.

2. Item catalog and partner related information

For a B2B webshop, GET /api/Webshop/GetArticles provides item information with optional parameters categoryId and searchQuery as well as the partner reference PartnerId. The answer can contain item name, image, price, sales price, availability, minimum quantity, delivery time and categories.

  • GET /api/Webshop/CarouselArticle/{articleId}/{PartnerId} loads the details of a single item for the specified partner.
  • GET /api/Webshop/GetCarouselArticles returns items for featured areas and carousels.
  • GET /api/Webshop/GetArticlesOrdered?PartnerId={partnerId} delivers already ordered items as partner-related suggestions.
  • GET /api/Webshop/GetOtherArticlesSold?PartnerId={partnerId} delivers additional items sold to this partner.
  • GET /api/Webshop/GetCarouselImages loads image data sets separately from item data if necessary.

For personalization and checkout preparation see below /api/WebshopUserCart additionally GetCustomerInfo, GetPartnerAddress and GetPartnerDiscountGroupInfo available. The customer profile contains, for example, partner group, language and sales price list; The address query provides the pre-assigned billing and delivery addresses. The discount query is required ArticleGroupId and DiscountGroupNameId.

3. Shopping cart and ordering

The shopping cart API maps a complete ordering process:

  1. GET /api/WebshopUserCart/GetWebshopUserCart?partnerId={partnerId} loads shopping cart positions, totals and user address information.
  2. POST /api/WebshopUserCart/AddToCart?partnerId={partnerId} adds an item or increases its quantity. For example, the JSON body contains {"articleId":"ART-1000","quantity":2}.
  3. PUT /api/WebshopUserCart/UpdateCartItem?id={cartItemId}&quantity={newQuantity} changes an item quantity. Quantity 0 removes the position; negative quantities are technically rejected.
  4. POST /api/WebshopUserCart/WebshopPlaceOrder?partnerId={partnerId}&employeeId={employeeId} converts the shopping cart into an X-ERP sales document. The JSON body contains deliveryAddress and billingAddress. Attention: The reference provided describes a document ID in the data field. The controller checked on September 18, 2026 actually returns data = 1. Therefore, do not use this value as a document ID; agree and test the document allocation for your server version.
  5. POST /api/WebshopUserCart/ClearCart?partnerId={partnerId} empties the shopping cart when explicitly requested. The checked order completion already removes the shopping cart items. An additional ClearCart call after checkout is therefore not necessary.

GET /api/WebshopUserCart/WebshopUserCartCount?partnerId={partnerId} returns the sum of the quantities for a shopping cart display. Item ratings can be saved with POST /api/WebshopUserCart/GiveRating and read with GET /api/WebshopUserCart/GetRatings?partnerId={partnerId}.

When completing the order, HTTP 404 means that there is no shopping cart; HTTP 422 can show an empty shopping cart. Do not trigger a purchase requisition again without checking after a connection has been lost: first clarify whether a document has already been created. This partner package does not describe an idempotency key for this call.

4. Helpdesk in the partner portal

A connected portal can display categories, tickets and their history:

  • GET /api/HelpdeskCategory/PageHelpdeskCategorysByParent/{ParentId}/{IncludeSubNodes}/{TopParentsOnly} loads categories for navigation and mapping.
  • GET /api/Helpdesk/{PartnerId}/{MyHelpdesksOnly}/PageFromViewForPartner returns the partner-related ticket list.
  • GET /api/HelpdeskDialog/{HelpdeskId}/PageFromViewByHelpdeskId loads the dialog entries of a ticket.
  • GET /api/HelpdeskDialogProtocol/{HelpdeskId}/PageByHelpdeskId loads the associated log entries.

PUT /api/Helpdesk updates a helpdesk record with a complete one Helpdeskobject in the request body. This write access is only used if direct ticket processing for the partner has been expressly agreed. Status changes can trigger notification processing.

Handle rights, answers and errors correctly

WebApi rights are based on the controller and the operation, for example Webshop-Read, WebshopUserCart-Create, Helpdesk-Update and PartnerToken-Read. If a required right is missing, X-ERP responds with HTTP 403 and a message about the missing right.

Use lots of detail and write calls APIEntityResponse<T> with the fields success, data and errorMessages. An HTTP status 200 does not automatically mean technical success: the integration must be additional success and evaluate the error messages.

Lists for categories and helpdesk sometimes use a page or grid result directly DataSourceLoadOptions. For page navigation and filtering are among other things skip, take, sort, filter and requireTotalCount provided. The exact format is coordinated based on the reference and the server version used.

At a minimum, handle HTTP 400 for incomplete or erroneous requests, HTTP 403 for missing rights, HTTP 404 for objects or sessions not found, and HTTP 422 for technical validation errors. Also note the exact parameter position: POST and PUT calls can also require additional query parameters in addition to a JSON body.

Complete data models

The OpenAPI file and sample templates are part of the developer package to be provided separately.

The OpenAPI file contains all 28 standard operations and the supplied schemas. It deliberately does not contain any automatically released internal or restricted extensions. The quick start describes the additional technical cookie login. Please note the version deviations when placing your order in the “Approvals and version notes” chapter.

Helpdesk update

PUT /api/Helpdesk expects a complete Helpdesk object, not an arbitrary partial patch. The supplied OpenAPI schema only describes Helpdesk openly and without fully formulated properties. Before writing a helpdesk project, the model that matches the target version and a released complete example must be available from the operator.