Skip to content

JTL-WAWI API (OnPrem) (1.1)

JTL-Wawi-Version: 1.11.0.0

Introduction

Welcome to the JTL-WAWI technical API documentation. This guide is here to help developers understand how our REST API works and how it can be integrated into your existing systems. We'll delve into the details of authentication and data manipulation processes, providing clear examples along the way. Whether you're a developer or an IT professional, this documentation aims to give you a practical understanding, laying the groundwork for effectively using the JTL-WAWI API to enhance your processes.

Authentication

You register your application with the API by sending a POST request with the required information and corresponding keys. You can find the exact request details at https://wawi-api.jtl-software.com/?#tag/appRegistration. This information has to include the following:

  • AppId
  • DisplayName
  • Description
  • Version
  • ProviderName
  • ProviderWebsite
  • MandatoryApiScopes

This data is crucial for identifying and registering your application with the API. The API uses it to generate a temporary authentication ID that allows your application to access the necessary resources. After successful validation of this information, you will receive the API key required for future authentication and API requests.

Before you can begin the registration process, you must open JTL-Wawi (new interface) and start the registration process under 'Admin->App registration'. Only at this point are you authorised to send the first API call. This step in JTL-Wawi ensures that your application is properly registered and has permission to use the API.

The API will send you an authentication ID in the form of a token. Once you have received this token and successfully completed the registration in JTL-Wawi, you will send another request to the API by including this authentication ID in the URL path.

After successful validation of this second request by the API and confirmation of the correct information, you will be provided with the actual API key. It is important to note that this API key will not be displayed again!

This API key will be used in the future to authenticate requests to the API. It is of utmost importance that you securely store the API key upon receipt, as it cannot be retrieved from any other location in the system.

HTTP Header

To make a successful API request, it is essential to include the correct authentication data in the request header. Upper case and lower case is ignored. The header should contain the following information:

  • X-AppID: This is the name of your application, in this case "MyApp/1.0.0". It is used to identify your application.
  • X-AppVersion: This is where the version number of your application is entered, in this case "1.0.0".
  • X-RunAs: Here, a JTL-Wawi user can be specified to perform an API call on their behalf (more details in the documentation).
  • X-ChallengeCode: You can enter any custom value here. The X-ChallengeCode is used during app registration and must be the same for all registration requests. The maximum length is 30 characters.
  • Authorization: The API key. Example: "Wawi 00000000-0000-00000-0000-000000000000"
Download OpenAPI description
Languages
Servers
Mock server

https://developer.jtl-software.com/_mock/products/erpapi/openapi/

Local OnPremise Environment

http://127.0.0.1:64110/api/eazybusiness/

odata

worker

Planned

Operations

wms

Query all pick lists for a specific wms warehouse that are not completed.
Operations

warehouse

Query all warehouses
Operations

transactionStatus

Query all transaction status for sales order
Operations

tax

Returns the Taxrate for the given Item
Operations

item

Query all tax classes
Operations

Query Availabilities

Request

Query all availabilites for items

Security
Wawi
Headers
api-versionstring

Specify the desired API version, e.g. '1.0'. If not provided, the last available version is set.

x-appidstringrequired

This is the name of your application, e.g. "MyApp/1.0.0". It is used to identify your application.

x-appversionstringrequired

This is where the version number of your application is entered, e.g. "1.0.0".

x-runasstring

The User-Id (int or uuid) on whose behalf the request is executed. Requires scope 'Application.RunAs'.

X-SessionIdstring(uuid)

The id of a session in which the call will be executed.

curl -i -X GET \
  https://developer.jtl-software.com/_mock/products/erpapi/openapi/availabilities \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'api-version: string' \
  -H 'x-appid: string' \
  -H 'x-appversion: string' \
  -H 'x-runas: string'

Responses

Returns all availabilites for items.

Bodyapplication/jsonArray [
Idinteger(int32)(JTL.Data.Contracts.Keys.LieferstatusKey)required
Namestringrequired

The name of the availability state.

Example: "In Stock"
]
Response
application/json
[ { "Id": 0, "Name": "In Stock" } ]

Query Conditions

Request

Query all item conditions

Security
Wawi
Headers
api-versionstring

Specify the desired API version, e.g. '1.0'. If not provided, the last available version is set.

x-appidstringrequired

This is the name of your application, e.g. "MyApp/1.0.0". It is used to identify your application.

x-appversionstringrequired

This is where the version number of your application is entered, e.g. "1.0.0".

x-runasstring

The User-Id (int or uuid) on whose behalf the request is executed. Requires scope 'Application.RunAs'.

X-SessionIdstring(uuid)

The id of a session in which the call will be executed.

curl -i -X GET \
  https://developer.jtl-software.com/_mock/products/erpapi/openapi/conditions \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'api-version: string' \
  -H 'x-appid: string' \
  -H 'x-appversion: string' \
  -H 'x-runas: string'

Responses

Returns all conditions.

Bodyapplication/jsonArray [
Idinteger(int32)(JTL.Data.Contracts.Keys.ZustandKey)required
NamesArray of objects(JTL.Wawi.Rest.Contracts.Models.V1.Condition.ConditionNames)required

The list of the condition names.

Names[].​Namestringrequired

Name of a condition.

Example: "New"
Names[].​LanguageIsostringrequired

ISO code of the language of a condition.

Example: "DE"
]
Response
application/json
[ { "Id": 0, "Names": [] } ]

Query Items

Request

Query all items

Security
Wawi
Query
searchKeyWordstring

A search key word which is using many important item identificators. For more info see documentation or the configuration in the search in items in JTL-Wawi.

kKategorieinteger(int32)
kHerstellerinteger(int32)
kArtikelinteger(int32)
changedSincestring(date-time)

The date last changes were made to the item.

isActiveOnSalesChannelIdstring

The ID of the sales channel on which this item is active.

pageNumberinteger(int32)

Number of the page of items to fetch.

pageSizeinteger(int32)

Size of the page that is specified by pageNumber.

Headers
api-versionstring

Specify the desired API version, e.g. '1.0'. If not provided, the last available version is set.

x-appidstringrequired

This is the name of your application, e.g. "MyApp/1.0.0". It is used to identify your application.

x-appversionstringrequired

This is where the version number of your application is entered, e.g. "1.0.0".

x-runasstring

The User-Id (int or uuid) on whose behalf the request is executed. Requires scope 'Application.RunAs'.

X-SessionIdstring(uuid)

The id of a session in which the call will be executed.

curl -i -X GET \
  'https://developer.jtl-software.com/_mock/products/erpapi/openapi/items?searchKeyWord=string&kKategorie=0&kHersteller=0&kArtikel=0&changedSince=2019-08-24T14%3A15%3A22Z&isActiveOnSalesChannelId=string&pageNumber=0&pageSize=0' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'api-version: string' \
  -H 'x-appid: string' \
  -H 'x-appversion: string' \
  -H 'x-runas: string'

Responses

Returns all items, can be filtered by searchKeyWord and postalCode.

Bodyapplication/json
TotalItemsinteger(int32)required

Gets or sets the total number of items available in the data source.

PageNumberinteger(int32)required

Gets or sets the current page number in the paginated list.

PageSizeinteger(int32)required

Gets or sets the number of items per page in the paginated list.

ItemsArray of objects(JTL.Wawi.Rest.Contracts.Models.V1.Item.Item)required

Gets or sets the collection of items contained in the paged list.

Items[].​Idinteger(int32)(JTL.Data.Contracts.Keys.ArtikelKey)required
Items[].​SKUstringrequired

Item SKU. If no SKU is given when posting an item, the SKU will be generated automatically.

Example: "ART2394871"
Items[].​ManufacturerIdinteger(int32)(JTL.Data.Contracts.Keys.HerstellerKey)required
Items[].​ResponsiblePersonIdinteger(int32)(JTL.Wawi.ContactManagement.Core.Contracts.Domain.Keys.ProductComplianceContactKey)required
Items[].​IsActivebooleanrequired

Indicates if the item is active.

Example: true
Items[].​CategoriesArray of objects(JTL.Wawi.Rest.Contracts.Models.V1.Item.CategoryReference)required

List of all the categories for the item.

Items[].​Categories[].​CategoryIdinteger(int32)(JTL.Data.Contracts.Keys.KategorieKey)required
Items[].​Categories[].​Namestringrequired

Name in the default language of the category.

Example: "House and Garden"
Items[].​Namestringrequired

Name of the item in the default language in JTL-Wawi.

Example: "Interdimensional goggles"
Items[].​Descriptionstringrequired

Full textdescription for the item

Example: "These goggles are a must have product. Everyone needs them. Buy them."
Items[].​ShortDescriptionstringrequired

Short description of the item in the default language in JTL-Wawi.

Example: "The best goggles anyone can buy"
Items[].​Identifiersobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemIdentifiers)required

Model Class: ItemIdentifiers

Items[].​Identifiers.​Gtinstringrequired

GTIN

Example: "8896982295860"
Items[].​Identifiers.​ManufacturerNumberstringrequired

Manufacturer number.

Example: "75"
Items[].​Identifiers.​ISBNstringrequired

ISBN

Example: "978-3-86680-192-9"
Items[].​Identifiers.​UPCstringrequired

UPC

Example: "889698229586"
Items[].​Identifiers.​AmazonFnskustringrequired

An item's Amazon FNSKU.

Example: "FN813S88A43"
Items[].​Identifiers.​AsinsArray of stringsrequired

A list of the item's ASINs.

Example: "B071GVGFQF"
Items[].​Identifiers.​OwnIdentifierstringrequired

A custom identifier for the item.

Example: "P446853"
Items[].​ComponentsArray of objects(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemComponent)required

Components for the item if the item is a bill of material.

Items[].​Components[].​ItemIdinteger(int32)(JTL.Data.Contracts.Keys.ArtikelKey)required
Items[].​Components[].​Quantitynumber(decimal)required

Quantity of the component in the bill of material.

Example: 2
Items[].​Components[].​SortNumberinteger(int32)required

Defines the order of the components when shown in lists and sales channels.

Example: 1
Items[].​ChildItemsArray of integers(int32)required

IDs of the child items, if the item is a parent item.

Example: ""
Items[].​ParentItemIdinteger(int32)(JTL.Data.Contracts.Keys.ArtikelKey)required
Items[].​ItemPriceDataobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemPrice)required

Model Class: ItemPrice

Items[].​ItemPriceData.​SalesPriceNetnumber(decimal)required

The net sales price of the item.

Example: 125.21
Items[].​ItemPriceData.​SuggestedRetailPricenumber(decimal)required

The suggested retail price for the item.

Example: 159.99
Items[].​ItemPriceData.​PurchasePriceNetnumber(decimal)required

The purchase price of the item.

Example: 99.73
Items[].​ItemPriceData.​EbayPricenumber(decimal)required

Default price in new listing templates.

Example: 149.99
Items[].​ItemPriceData.​AmazonPricenumber(decimal)required

Brutto price for new Amazon listings.

Example: 149.99
Items[].​ActiveSalesChannelsstringrequired

The list of active sales channels of the item. Only online shops and JTL-POS are permitted. Sales channels that are removed from this list will be deactivated for this item.

Example: ""
Items[].​SortNumberinteger(int32)required

The sort number of the item, used in some sales channels for ordering items.

Example: 0
Items[].​Annotationstringrequired

The item annotation.

Example: "Some additional internal info about the item"
Items[].​Addedstring(date-time)required

Date when the item was added to the system.

Example: "2023-01-15T13:00:00.0000000+00:00"
Items[].​Changedstring(date-time)required

Date of the last change made to the item. Only item data changes are relevant for this field, not changes in stock.

Example: "2023-01-15T13:00:00.0000000+00:00"
Items[].​ReleasedOnDatestring(date-time)required

The date when the item was put up for sale.

Example: "2023-01-15T13:00:00.0000000+00:00"
Items[].​StorageOptionsobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemStorageOption)required

Model Class: ItemStorageOption

Items[].​StorageOptions.​InventoryManagementActivebooleanrequired

Indicates if inventory management for the item is active, meaning that the item displays stock quantities.

Example: true
Items[].​StorageOptions.​SplitQuantitybooleanrequired

Indicates if the item can be split into quantities less than 1.

Example: false
Items[].​StorageOptions.​GlobalMinimumStockLevelnumber(decimal)required

Defines the minimum quantity that should always be in stock. For example, when calculating purchasing orders.

Example: 15
Items[].​StorageOptions.​Bufferinteger(int32)required

The buffer of the item. Used when selling time-delayed across different sales channels, so as not to sell more than is in stock.

Example: 5
Items[].​StorageOptions.​SerialNumberItembooleanrequired

Indicates the item's serial number when shipping the sales orders.

Example: false
Items[].​StorageOptions.​SerialNumberTrackingbooleanrequired

Indicates if serial numbers are to be identified during a goods receipt process from a supplier.

Example: false
Items[].​StorageOptions.​SubjectToShelfLifeExpirationDatebooleanrequired

Indicates if the item has an expiration date, also known as a best before date.

Example: false
Items[].​StorageOptions.​SubjectToBatchItembooleanrequired

Indicates whether the item is a batch item or not.

Example: false
Items[].​StorageOptions.​ProcurementTimeinteger(int32)required

The procurement time indicates how many days it will take for the goods to be ready for shipment if they are currently out of stock. Procurement time is determined automatically on the basis of the supplier’s delivery time. By default, the delivery time of the default supplier is used as the procurement time. If additional processing time (in days) has been specified, this is added to the procurement time.

Example: 3
Items[].​StorageOptions.​DetermineProcurementTimeAutomaticallybooleanrequired

If this option is set, the procurement time will be calculated from the default supplier's shipment time.

Example: false
Items[].​StorageOptions.​AdditionalHandlingTimeinteger(int32)required

Indicates the additional processing time in days required to process. It is always added to the delivery time.

Example: 3
Items[].​CountryOfOriginstringrequired

The country of origin of the item.

Example: "DE"
Items[].​ConditionIdinteger(int32)(JTL.Data.Contracts.Keys.ZustandKey)required
Items[].​ShippingClassIdinteger(int32)(JTL.Data.Contracts.Keys.VersandklasseKey)required
Items[].​ProductGroupIdinteger(int32)(JTL.Data.Contracts.Keys.WarengruppeKey)required
Items[].​TaxClassIdinteger(int32)(JTL.Data.Contracts.Keys.SteuerklasseKey)required
Items[].​Dimensionsobject(JTL.Wawi.Rest.Contracts.Models.V1.Common.Dimensions)required

Model Class: Dimensions

Items[].​Dimensions.​Lengthnumber(decimal)required

Length

Example: 10.5
Items[].​Dimensions.​Widthnumber(decimal)required

Width

Example: 5.8
Items[].​Dimensions.​Heightnumber(decimal)required

Height

Example: 3
Items[].​Weightsobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemWeights)required

Model Class: ItemWeights

Items[].​Weights.​ItemWeigthnumber(decimal)required

The weight of the item in kilograms.

Example: 5
Items[].​Weights.​ShippingWeightnumber(decimal)required

The shipping weight of the item in kilograms.

Example: 5.5
Items[].​AllowNegativeStockbooleanrequired

This option allows you to sell a higher quantity of the item than is actually in stock.

Example: false
Items[].​Quantitiesobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemQuantities)required

Model Class: ItemQuantities

Items[].​Quantities.​MinimumOrderQuantitynumber(decimal)required

The minimum order quantity of the item.

Example: 0
Items[].​Quantities.​MinimumPurchaseQuantityForCustomerGroupArray of objects(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemMinimumPurchaseQuantityForCustomerGroup)required

A collection of minimum order quantities for different customer groups.

Items[].​Quantities.​MinimumPurchaseQuantityForCustomerGroup[].​CustomerGroupIdinteger(int32)(JTL.Data.Contracts.Keys.KundenGruppeKey)required
Items[].​Quantities.​MinimumPurchaseQuantityForCustomerGroup[].​PermissibleOrderQuantitynumber(decimal)required

The permissible order quantity for the item. Indicates the increments in which the item is sold.

Example: 149.99
Items[].​Quantities.​MinimumPurchaseQuantityForCustomerGroup[].​MinimumPurchaseQuantitynumber(decimal)required

The minimum purchase quantity for a customer group.

Example: 1
Items[].​Quantities.​MinimumPurchaseQuantityForCustomerGroup[].​IsActivebooleanrequired

Indicates if this setting is active or deactivated.

Example: true
Items[].​Quantities.​PermissibleOrderQuantitynumber(decimal)required

The permissible order quantity for the item. Indicates the increments in which the item is sold.

Example: 0
Items[].​DangerousGoodsobject(JTL.Wawi.Rest.Contracts.Models.V1.Item.ItemDangerousGoods)required

Model Class: ItemDangerousGoods

Items[].​DangerousGoods.​UnNumberstringrequired

The UN number for the item.

Example: "0070"
Items[].​DangerousGoods.​HazardNostringrequired

The hazard number for the item.

Example: "Class1 explosives"
Items[].​Taricstringrequired

Taric code of the item.

Example: "61071100"
Items[].​SearchTermsstringrequired

Search terms for the item.

Example: "goggles, magnification, lenses"
Items[].​PriceListActivebooleanrequired

Indicates if the item is in the price list.

Example: false
Items[].​IgnoreDiscountsbooleanrequired

Indicates if discounts are to be disregarded.

Example: false
Items[].​AvailabilityIdinteger(int32)(JTL.Data.Contracts.Keys.LieferstatusKey)required
TotalPagesinteger(int32)read-only

Gets the total number of pages based on the total number of items and the page size.

HasPreviousPagebooleanread-only

Gets a value indicating whether there is a previous page available in the paginated list.

HasNextPagebooleanread-only

Gets a value indicating whether there is a next page available.

NextPageNumberinteger(int32)read-only

Gets the number of the next page if there is one; otherwise, returns the total number of pages.

PreviousPageNumberinteger(int32)read-only

Gets the number of the previous page. If there is no previous page, it returns 1.

Response
application/json
{ "TotalItems": 0, "PageNumber": 0, "PageSize": 0, "Items": [ {} ], "TotalPages": 0, "HasPreviousPage": true, "HasNextPage": true, "NextPageNumber": 0, "PreviousPageNumber": 0 }

supplier

Query all suppliers
Operations

stock

Query stocks for a specific item, warehouse or storage location
Operations

shippingmethod

Query all shipping methods
Operations

salesorder

Query all sales orders
Operations

cancellationreason

Planned

Operations

salesinvoicecorrection

Development

saleschannel

Get all sales channels
Operations

return

Create a new return with associated items and packages.
Operations

returnstate

Planned

Operations

returnreason

Planned

Operations

property

Query all properties for items
Operations

printer

Returns all Installed Printers
Operations

paymentmethod

Query all payment methods
Operations

onholdreason

Query all on hold reasons for sales orders
Operations

offer

Execute the printing of a Offer
Operations

Configuration

Planned

Operations

invoice

Planned

Operations

info

Returns the status of the API
Operations

features

Returns the available feature sets with release state and API version
Operations

Extensibility

Planned

Operations

shipping

Development

deliverynote

Planned

Operations

customer

Query all customers
Operations

customerGroup

Query all customer groups
Operations

customerCategory

Query all customer categories
Operations

creditnote

Execute the printing of a CreditNote
Operations

company

Query all companies
Operations

colorcodes

Query all color codes for sales orders
Operations

category

Query all categories
Operations

appRegistration

Send a registration request for an (external) application
Operations

login

Sends a request to log in the user / dynamically assign the WAWI user. Only use this request if your API uses SSL.
Operations

logout

Sends a request to log out the user
Operations

accountingData

Planned

Operations