API reference
Every endpoint of the WinShop Web API, generated from the OpenAPI description of the demo instance.
This reference is generated from the OpenAPI description of the WinShop demo instance. That description reports its version as 0.0.0.
Your instance may differ
Each customer runs their own instance on their own release. Call GET /api/version on your instance and look the result up in the changelog to see what it has. The description your instance serves at https://<your-instance>/swagger is the exact truth for that instance.
How the reference is organised
| Section | Contents |
|---|---|
| Documents | Orders, delivery notes, intakes, internal transfers, invoices, claims, stock taking and point of sale. |
| Catalog | Product, Price list, Product repricing, Stock items and promotions. |
| Companies and finance | Companies, Credit, Financial receivables and Financial reimbursement. |
| Item lists | The reference tables: warehouses, units, VAT rates, colours, sizes and many more. One page per list. |
| Sys | Endpoints about the instance itself, such as its version. |
Document types share most of their operations, so the same set of pages repeats under each of them. Read Documents once and you can find your way around all of them.
How to read an endpoint page
Each page describes one endpoint, top to bottom:
- Method and path, for example
POST /api/documents/orders/internet. Put the address of your instance in front of it. - Authorization. Almost every endpoint needs a bearer token; see Authentication.
- Parameters in the path and in the query string. Array parameters repeat their key:
?itemIds=1&itemIds=2. - Request body, as an expandable schema. Open a nested object to see its fields.
- Responses by status code, with their schemas. Error responses share one body, described in Errors.
- Code samples in curl, C# and TypeScript. They use the placeholders
https://<your-instance>and<access-token>.
Replace the two placeholders and a sample runs as it is:
curl -X GET "https://<your-instance>/api/item-lists/warehouses" \
-H "Authorization: Bearer <access-token>"Things the pages do not repeat, because they hold everywhere:
- JSON is camelCase, dates have no time zone offset, and
nullvalues are left out. See Conventions. - A field marked as optional in a schema can still be required by the business rules of an endpoint. If it is, the request fails with
400and a message that names the field. - List endpoints named
filter-paginatedall work the same way. See Filtering and pagination.
What is not here
The reference covers the public API: what an external integration is meant to use. Endpoints that exist only to serve WinShop's own applications are left out on purpose. If you find such an endpoint on your instance, do not build on it; it can change without notice.
GET /api/health is also missing, because it is not part of the OpenAPI description. It is documented in the Overview.
New here?
Start with the Concepts. They explain the patterns that every endpoint in this reference follows.