URL https://wawi-api.jtl-software.com/
JTL-Software-GmbH partner@jtl-software.com
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.
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:
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.
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:
This is the name of your application, in this case "MyApp/1.0.0". It is used to identify your application.
This is where the version number of your application is entered, in this case "1.0.0".
The User-Id as int or uuid to run the Request, a JTL-Wawi user can be specified to perform an API call on their behalf (more details in the documentation, Optional). To use the Header, you must have the needed Scope 'Application.RunAs'
The sales order to create.
Model Class: CreateDepartureCountry
Model Class: CreateAddress
The date when the order was created.
Model Class: CreateSalesOrderPaymentDetail
Model Class: CreateSalesOrderShippingDetail
A customer comment on the sales order.
curl -i -X POST \
'https://developer.jtl-software.com/_mock/products/erpapi/openapi/v1/salesOrders?disableAutomaticWorkflows=true&renameSalesOrderNumberWhenAlreadyExists=true' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
-H 'x-appid: string' \
-H 'x-appversion: string' \
-H 'x-runas: string' \
-d '{
"Number": "A1004465",
"ExternalNumber": "D456-64894-132",
"BillingNumber": "RE-202404-10000",
"CompanyId": 1,
"DepartureCountry": {
"CountryISO": "DE",
"State": "Berlin",
"CurrencyIso": "EUR",
"CurrencyFactor": 1
},
"CustomerId": 1005,
"CustomerVatID": "DE12345",
"BillingAddress": {
"Company": "Sportbedarf Sommer",
"Company2": "Innovation Division",
"FormOfAddress": "Mr.",
"Title": "Dr.",
"FirstName": "John",
"LastName": "Doe",
"Street": "Main St. 123",
"Address2": "Floor 5, Apt 302",
"PostalCode": "12345",
"City": "Example City",
"State": "Example State",
"CountryIso": "DE",
"VatID": "DE123456789",
"PhoneNumber": "+49 1234 445556661",
"MobilePhoneNumber": "+49 160 123 4567",
"EmailAddress": "example@email.com",
"Fax": "+49 1234 4455566615"
},
"Shipmentaddress": {
"Company": "Sportbedarf Sommer",
"Company2": "Innovation Division",
"FormOfAddress": "Mr.",
"Title": "Dr.",
"FirstName": "John",
"LastName": "Doe",
"Street": "Main St. 123",
"Address2": "Floor 5, Apt 302",
"PostalCode": "12345",
"City": "Example City",
"State": "Example State",
"CountryIso": "DE",
"VatID": "DE123456789",
"PhoneNumber": "+49 1234 445556661",
"MobilePhoneNumber": "+49 160 123 4567",
"EmailAddress": "example@email.com",
"Fax": "+49 1234 4455566615"
},
"SalesOrderDate": "2023-02-01T12:45:00.0000000+00:00",
"SalesOrderPaymentDetails": {
"PaymentMethodId": 12,
"CurrencyIso": "EUR",
"CurrencyFactor": 1,
"PaymentTarget": 0,
"CashDiscount": 5,
"CashDiscountDays": 2
},
"SalesOrderShippingDetail": {
"ShippingMethodId": 3,
"ShippingPriority": 5,
"ShippingDate": "2023-01-15T13:00:00.0000000+00:00",
"EstimatedDeliveryDate": "2023-01-16T13:00:00.0000000+00:00",
"OnHoldReasonId": 1,
"ExtraWeight": 0.1
},
"ColorcodeId": 2,
"Comment": "an additional order comment",
"CustomerComment": "an additional customer comment",
"LanguageIso": "DE"
}'The created sales order.
Model Class: DepartureCountry
ISO code of the currency of the departure country.
Model Class: Address
Model Class: Address
Additional company information
Name of state in the customer's address
The date when the order was created.
Model Class: SalesOrderPaymentDetail
The payment method of the sales order.
The payment status of the sales order0=UnPayed | 1=PartialPayed | 2=Payed
The total gross amount of the sales order.
ISO code of the currency of the sales order.
The currency factor in the order at the time the order is created.
Date of payment that paid off the sales order.
The amount that is left to pay for this sales order.
The payment target of the sales order in days.
The cash discount of the sales order.
Model Class: SalesOrderShippingDetail
The shipping method of the sales order.
The delivery status of the sales order.0=DeliveryNotComplete | 1=DeliveryComplete | 2=DeliveryCompleteWithoutNote
The shipping priority of the sales order.
The notified shipping date of the sales order.
The estimated delivery date of the sales order.
The date when the sales order was delivered.
The ID of the on hold reason of the sales order.
Indicates if the invoice of the order was created in an external system, like Amazon VCS.
A customer comment on the sales order.
Indicates if the order has been cancelled. There is a special endpoint for cancelling sales orders.
Model Class: SalesOrderCancellationDetails
The id of the reason for cancelling the sales order.
A comment that adds further information to the cancellation.
{ "Id": 123, "Number": "A1004465", "ExternalNumber": "D456-64894-132", "BillingNumber": "RE-202404-10000", "CompanyId": 1, "DepartureCountry": { "CountryISO": "DE", "State": "Berlin", "CurrencyIso": "EUR", "CurrencyFactor": 1 }, "CustomerId": 1005, "CustomerVatID": "DE12345", "MerchantVatID": "DE12345", "BillingAddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "Shipmentaddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "SalesOrderDate": "2023-02-01T12:45:00.0000000+00:00", "SalesOrderPaymentDetails": { "PaymentMethodId": 12, "PaymentStatus": "", "TotalGrossAmount": 19.99, "CurrencyIso": "EUR", "CurrencyFactor": 1, "DateOfPayment": "2023-01-15T13:00:00.0000000+00:00", "StillToPay": 0, "PaymentTarget": 0, "CashDiscount": 5, "CashDiscountDays": 2 }, "SalesOrderShippingDetail": { "ShippingMethodId": 3, "DeliveryCompleteStatus": "", "ShippingPriority": 5, "ShippingDate": "2023-01-15T13:00:00.0000000+00:00", "EstimatedDeliveryDate": "2023-01-16T13:00:00.0000000+00:00", "DeliveredDate": "2023-01-15T13:00:00.0000000+00:00", "OnHoldReasonId": 1, "ExtraWeight": 0.1 }, "ColorcodeId": 2, "IsExternalInvoice": false, "Comment": "an additional order comment", "CustomerComment": "an additional customer comment", "IsCancelled": false, "LanguageIso": "DE", "CancellationDetails": { "CancellationReasonId": -4, "CancellationComment": "Change of mind (once again); we should consider terminating the customer relationship", "Date": "2023-02-01T12:45:00.0000000+00:00" }, "SalesChannelId": "1-1-1", "UserCreatedId": 1, "UserId": 1, "TransactionStatusId": 13 }
This is the name of your application, in this case "MyApp/1.0.0". It is used to identify your application.
This is where the version number of your application is entered, in this case "1.0.0".
The User-Id as int or uuid to run the Request, a JTL-Wawi user can be specified to perform an API call on their behalf (more details in the documentation, Optional). To use the Header, you must have the needed Scope 'Application.RunAs'
curl -i -X GET \
'https://developer.jtl-software.com/_mock/products/erpapi/openapi/v1/salesOrders/{salesOrderId}' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
-H 'x-appid: string' \
-H 'x-appversion: string' \
-H 'x-runas: string'Returns the sales order for the given id.
Model Class: DepartureCountry
ISO code of the currency of the departure country.
Model Class: Address
Model Class: Address
Additional company information
Name of state in the customer's address
The date when the order was created.
Model Class: SalesOrderPaymentDetail
The payment method of the sales order.
The payment status of the sales order0=UnPayed | 1=PartialPayed | 2=Payed
The total gross amount of the sales order.
ISO code of the currency of the sales order.
The currency factor in the order at the time the order is created.
Date of payment that paid off the sales order.
The amount that is left to pay for this sales order.
The payment target of the sales order in days.
The cash discount of the sales order.
Model Class: SalesOrderShippingDetail
The shipping method of the sales order.
The delivery status of the sales order.0=DeliveryNotComplete | 1=DeliveryComplete | 2=DeliveryCompleteWithoutNote
The shipping priority of the sales order.
The notified shipping date of the sales order.
The estimated delivery date of the sales order.
The date when the sales order was delivered.
The ID of the on hold reason of the sales order.
Indicates if the invoice of the order was created in an external system, like Amazon VCS.
A customer comment on the sales order.
Indicates if the order has been cancelled. There is a special endpoint for cancelling sales orders.
Model Class: SalesOrderCancellationDetails
The id of the reason for cancelling the sales order.
A comment that adds further information to the cancellation.
{ "Id": 123, "Number": "A1004465", "ExternalNumber": "D456-64894-132", "BillingNumber": "RE-202404-10000", "CompanyId": 1, "DepartureCountry": { "CountryISO": "DE", "State": "Berlin", "CurrencyIso": "EUR", "CurrencyFactor": 1 }, "CustomerId": 1005, "CustomerVatID": "DE12345", "MerchantVatID": "DE12345", "BillingAddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "Shipmentaddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "SalesOrderDate": "2023-02-01T12:45:00.0000000+00:00", "SalesOrderPaymentDetails": { "PaymentMethodId": 12, "PaymentStatus": "", "TotalGrossAmount": 19.99, "CurrencyIso": "EUR", "CurrencyFactor": 1, "DateOfPayment": "2023-01-15T13:00:00.0000000+00:00", "StillToPay": 0, "PaymentTarget": 0, "CashDiscount": 5, "CashDiscountDays": 2 }, "SalesOrderShippingDetail": { "ShippingMethodId": 3, "DeliveryCompleteStatus": "", "ShippingPriority": 5, "ShippingDate": "2023-01-15T13:00:00.0000000+00:00", "EstimatedDeliveryDate": "2023-01-16T13:00:00.0000000+00:00", "DeliveredDate": "2023-01-15T13:00:00.0000000+00:00", "OnHoldReasonId": 1, "ExtraWeight": 0.1 }, "ColorcodeId": 2, "IsExternalInvoice": false, "Comment": "an additional order comment", "CustomerComment": "an additional customer comment", "IsCancelled": false, "LanguageIso": "DE", "CancellationDetails": { "CancellationReasonId": -4, "CancellationComment": "Change of mind (once again); we should consider terminating the customer relationship", "Date": "2023-02-01T12:45:00.0000000+00:00" }, "SalesChannelId": "1-1-1", "UserCreatedId": 1, "UserId": 1, "TransactionStatusId": 13 }
0 - Keine Neuberechnung, auch wenn steuerrelevante Felder geändert wurden. 1 - Nettopreise beibehalten (Änderungen des Mehrwertsteuersatzes werden vom Kunden getragen). 2 - Bruttopreise beibehalten (Änderungen des Mehrwertsteuersatzes werden vom Einzelhändler getragen).
This is the name of your application, in this case "MyApp/1.0.0". It is used to identify your application.
This is where the version number of your application is entered, in this case "1.0.0".
The User-Id as int or uuid to run the Request, a JTL-Wawi user can be specified to perform an API call on their behalf (more details in the documentation, Optional). To use the Header, you must have the needed Scope 'Application.RunAs'
The sales order to update.
Model Class: UpdateDepartureCountry
Model Class: UpdateAddress
The date when the order was created.
Model Class: UpdateSalesOrderPaymentDetail
Model Class: UpdateSalesOrderShippingDetail
A customer comment on the sales order.
curl -i -X PATCH \
'https://developer.jtl-software.com/_mock/products/erpapi/openapi/v1/salesOrders/{salesOrderId}?disableAutomaticWorkflows=true&recalculateTax=0' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'X-SessionId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
-H 'x-appid: string' \
-H 'x-appversion: string' \
-H 'x-runas: string' \
-d '{
"ExternalNumber": "D456-64894-132",
"BillingNumber": "RE-202404-10000",
"CompanyId": 1,
"DepartureCountry": {
"CountryISO": "DE",
"State": "Berlin",
"CurrencyIso": "EUR",
"CurrencyFactor": 1
},
"CustomerId": 1005,
"CustomerVatID": "DE12345",
"BillingAddress": {
"Company": "Sportbedarf Sommer",
"Company2": "Innovation Division",
"FormOfAddress": "Mr.",
"Title": "Dr.",
"FirstName": "John",
"LastName": "Doe",
"Street": "Main St. 123",
"Address2": "Floor 5, Apt 302",
"PostalCode": "12345",
"City": "Example City",
"State": "Example State",
"CountryIso": "DE",
"VatID": "DE123456789",
"PhoneNumber": "+49 1234 445556661",
"MobilePhoneNumber": "+49 160 123 4567",
"EmailAddress": "example@email.com",
"Fax": "+49 1234 4455566615"
},
"Shipmentaddress": {
"Company": "Sportbedarf Sommer",
"Company2": "Innovation Division",
"FormOfAddress": "Mr.",
"Title": "Dr.",
"FirstName": "John",
"LastName": "Doe",
"Street": "Main St. 123",
"Address2": "Floor 5, Apt 302",
"PostalCode": "12345",
"City": "Example City",
"State": "Example State",
"CountryIso": "DE",
"VatID": "DE123456789",
"PhoneNumber": "+49 1234 445556661",
"MobilePhoneNumber": "+49 160 123 4567",
"EmailAddress": "example@email.com",
"Fax": "+49 1234 4455566615"
},
"SalesOrderDate": "2023-02-01T12:45:00.0000000+00:00",
"SalesOrderPaymentDetails": {
"PaymentMethodId": 12,
"CurrencyIso": "EUR",
"CurrencyFactor": 1,
"PaymentTarget": 0,
"CashDiscount": 5,
"CashDiscountDays": 2
},
"SalesOrderShippingDetail": {
"ShippingMethodId": 3,
"ShippingPriority": 5,
"ShippingDate": "2023-01-15T13:00:00.0000000+00:00",
"EstimatedDeliveryDate": "2023-01-16T13:00:00.0000000+00:00",
"OnHoldReasonId": 1,
"ExtraWeight": 0.1
},
"ColorcodeId": 2,
"Comment": "an additional order comment",
"CustomerComment": "an additional customer comment",
"LanguageIso": "DE"
}'The updated sales order.
Model Class: DepartureCountry
ISO code of the currency of the departure country.
Model Class: Address
Model Class: Address
Additional company information
Name of state in the customer's address
The date when the order was created.
Model Class: SalesOrderPaymentDetail
The payment method of the sales order.
The payment status of the sales order0=UnPayed | 1=PartialPayed | 2=Payed
The total gross amount of the sales order.
ISO code of the currency of the sales order.
The currency factor in the order at the time the order is created.
Date of payment that paid off the sales order.
The amount that is left to pay for this sales order.
The payment target of the sales order in days.
The cash discount of the sales order.
Model Class: SalesOrderShippingDetail
The shipping method of the sales order.
The delivery status of the sales order.0=DeliveryNotComplete | 1=DeliveryComplete | 2=DeliveryCompleteWithoutNote
The shipping priority of the sales order.
The notified shipping date of the sales order.
The estimated delivery date of the sales order.
The date when the sales order was delivered.
The ID of the on hold reason of the sales order.
Indicates if the invoice of the order was created in an external system, like Amazon VCS.
A customer comment on the sales order.
Indicates if the order has been cancelled. There is a special endpoint for cancelling sales orders.
Model Class: SalesOrderCancellationDetails
The id of the reason for cancelling the sales order.
A comment that adds further information to the cancellation.
{ "Id": 123, "Number": "A1004465", "ExternalNumber": "D456-64894-132", "BillingNumber": "RE-202404-10000", "CompanyId": 1, "DepartureCountry": { "CountryISO": "DE", "State": "Berlin", "CurrencyIso": "EUR", "CurrencyFactor": 1 }, "CustomerId": 1005, "CustomerVatID": "DE12345", "MerchantVatID": "DE12345", "BillingAddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "Shipmentaddress": { "Id": 100, "Company": "Sportbedarf Sommer", "Company2": "Innovation Division", "FormOfAddress": "Mr.", "Title": "Dr.", "FirstName": "John", "LastName": "Doe", "Street": "Main St. 123", "Address2": "Floor 5, Apt 302", "PostalCode": "12345", "City": "Example City", "State": "Example State", "CountryIso": "DE", "VatID": "DE123456789", "PhoneNumber": "+49 1234 445556661", "MobilePhoneNumber": "+49 160 123 4567", "EmailAddress": "example@email.com", "Fax": "+49 1234 4455566615" }, "SalesOrderDate": "2023-02-01T12:45:00.0000000+00:00", "SalesOrderPaymentDetails": { "PaymentMethodId": 12, "PaymentStatus": "", "TotalGrossAmount": 19.99, "CurrencyIso": "EUR", "CurrencyFactor": 1, "DateOfPayment": "2023-01-15T13:00:00.0000000+00:00", "StillToPay": 0, "PaymentTarget": 0, "CashDiscount": 5, "CashDiscountDays": 2 }, "SalesOrderShippingDetail": { "ShippingMethodId": 3, "DeliveryCompleteStatus": "", "ShippingPriority": 5, "ShippingDate": "2023-01-15T13:00:00.0000000+00:00", "EstimatedDeliveryDate": "2023-01-16T13:00:00.0000000+00:00", "DeliveredDate": "2023-01-15T13:00:00.0000000+00:00", "OnHoldReasonId": 1, "ExtraWeight": 0.1 }, "ColorcodeId": 2, "IsExternalInvoice": false, "Comment": "an additional order comment", "CustomerComment": "an additional customer comment", "IsCancelled": false, "LanguageIso": "DE", "CancellationDetails": { "CancellationReasonId": -4, "CancellationComment": "Change of mind (once again); we should consider terminating the customer relationship", "Date": "2023-02-01T12:45:00.0000000+00:00" }, "SalesChannelId": "1-1-1", "UserCreatedId": 1, "UserId": 1, "TransactionStatusId": 13 }