01. Quick start

Target

You register an API user and then read the item catalog for a authorized business partner. Only then do business processes that write data follow. All examples assume a test company database.

Before the first call

Ask the operator to provide you with the HTTPS base address, the exact company database name, an API account, a permitted PartnerId and test items. The account requires Webshop-Read to access the catalog for the first time. The PartnerId designates a business partner in X-ERP, for example a customer; it does not automatically identify the developer or reseller.

Step 1: Login API account

The checked server code provides POST /api/WebApiUser/WebApiLogin. Use Content-Type: application/json.

{"email":"api@example.invalid","password":"IHR_PASSWORT","databaseName":"TESTFIRMA","rememberMe":false,"keepLoggedIn":false}

If successful, the checked controller responds with HTTP 200 and {"message":"Login successful."}. The HTTP client needs to store the session cookie obtained via Set-Cookie. The login response is not an APIEntityResponse and does not contain a bearer token. The endpoint is not part of the original fh allowlist; have this login method confirmed for your installation.

Step 2: Read item

Send using the same HTTP session and the cookie received:

GET /api/Webshop/GetArticles?PartnerId=123
Accept: application/json

Replace 123 with the authorized PartnerId. Check HTTP status, JSON content and success. Expected answer pattern, not guaranteed complete item structure:

{"success":true,"data":[],"errorMessages":[]}

An empty list is a possible result. The specific DTO fields are in the OpenAPI file. Use a known test item to check the item ID, price and availability.

Step 3: Evaluate the result

• HTTP 200 and success=true: technically successful call.
• HTTP 200 with HTML instead of JSON: possibly redirected to a login page; Check session and destination address.
• HTTP 401 or login redirect: Login or cookie is missing or has expired.
• HTTP 403: check required WebApi permission.
• HTTP 200 and success=false: evaluate errorMessages.

PowerShell template

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

After deploying the developer package: Unpack it, read README.txt and start under PowerShell 7:

./quickstart.ps1 -BaseUrl https://ihr-server.example -DatabaseName TESTFIRMA -PartnerId 123

The script queries the access data interactively and only carries out authentication and catalog queries. It has been syntactically checked, but not run against your production X-ERP installation.

Next step

Read login and permissions before connecting shopping cart or orders. Each integration requires its own check of its company and customer assignment.