> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Replaces the persisted synchronisation configuration (dbo.tShopKonfiguration) of a connector account.
> Replaces the persisted synchronisation configuration (dbo.tShopKonfiguration) of a connector account. Section-scoped: no other part of the connector account - base data, credentials, customer groups, languages, currencies, shipping methods - is read or written. Full replacement, not a patch: the request describes the complete desired state of the configuration section, and every writable field must be sent. Omitting an optional field sets it to null (its documented 'unrestricted / not set' meaning), so a GET-modify-PUT round trip is the intended usage; use UpdateConnector for field-wise partial updates. A connector account that has no configuration row yet gets one created by this call, which is why a partial write is not offered here - 'leave unchanged' has no meaning against a row that does not exist. Persists only: it does not contact the Connector endpoint at any point. Two groups of ConnectorConfiguration fields are deliberately not writable and are not part of this request. Live-only fields reported by the connected endpoint's handshake (PlatformName, PlatformVersion, ProtocolVersion, EndpointVersion, IsOldConnector, ServerInfo) are not persisted at all and can never be written. DummyCategoryId is system-managed - the import pipeline assigns the fallback category itself when an imported product has no category - so it is read-only here and its stored value is preserved unchanged by this call. Submitting any of those names is not an error on REST, where unknown body properties are ignored; on GraphQL the schema rejects them as unknown input fields.
## OpenAPI
````yaml /openapi/erp/2.1.json put /v2/sales-channels/{salesChannelId}/connector/configuration
openapi: 3.0.0
info:
title: JTL-WAWI API (Cloud)
description: "JTL-Wawi-Version: 2.2.0-alpha.9415+Sha.4655524\r\n# Introduction\r\n\r\nWelcome 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.\r\n\r\n# Authentication\r\n\r\nYou 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://developer.jtl-software.com/products/erp/swagger/appregistration. This information has to include the following:\r\n\r\n* AppId\r\n* DisplayName\r\n* Description\r\n* Version\r\n* ProviderName\r\n* ProviderWebsite\r\n* MandatoryApiScopes\r\n\r\nThis 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.\r\n\r\nBefore 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.\r\n\r\nThe 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.\r\n\r\nAfter 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!\r\n\r\nThis 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."
contact:
name: JTL-Software-GmbH
url: https://developer.jtl-software.com/
email: partner@jtl-software.com
version: '2.1'
x-application-version: 2.2.0.0
servers:
- url: https://api.jtl-cloud.com/erp
description: Production Environment Cloud API Gateway
security: []
tags:
- name: WMS
description: >-
Query all pick
lists for a specific wms warehouse that are not completed.
- name: Wawi App
description: >-
Get a
specific customer
- name: Warehouses
description: >-
Queries all
storage locations for a given warehouse.
- name: Units
description: Development
- name: Transaction Status
description: >-
Queries all transaction statuses for a sales
order.
- name: Tax
description: >-
Returns the tax
rate for the given item.
- name: Inventory
description: >-
Queries
stocks for a specific item, warehouse or storage location.
- name: Sales Order
description: Planned
- name: Sales Invoice Correction
description: Planned
- name: Return
description: >-
Create a new
return with associated items and packages.
- name: Item
description: >-
Queries all
responsible persons.
- name: Refund
description: Planned
- name: Property
description: >-
Queries all
properties of items.
- name: Printer
description: >-
Retrieves all
installed printers.
- name: Master Data
description: >-
Queries
all on hold reasons for sales orders.
- name: Manufacturer
description: Development
- name: Label
description: Development
- name: Sales Invoice
description: Planned
- name: Info
description: >-
Returns the
status of the API.
- name: Features
description: >-
Returns the
available feature sets with release state and API version.
- name: Extensibility
description: Planned
- name: Shipment
description: Development
- name: Delivery Note
description: Planned
- name: Custom Field
description: Development
- name: Customer
description: >-
Deletes a
specific customer.
- name: Authentication
description: >-
DEPRECATED seit Wawi 2.2.0: No-Op. Seit
Wawi 2.1.0 registriert sich die Wawi selbst per JWT.
- name: Attribute
description: Development
- name: Sales Quotation
description: >-
Execute
the printing of a sales quotation
- name: Production
- name: Resources
- name: Company
- name: Sales Orders
- name: Marketplace Order
- name: Marketplace Offer
- name: Marketplace Invoicing
- name: Sales Channel
- name: Payment
- name: Warehouse Assistant
- name: Worker
paths:
/v2/sales-channels/{salesChannelId}/connector/configuration:
put:
tags:
- wawi
- Sales Channel
summary: >-
Replaces the persisted synchronisation configuration
(dbo.tShopKonfiguration) of a connector account.
description: >-
Replaces the persisted synchronisation configuration
(dbo.tShopKonfiguration) of a connector account. Section-scoped: no
other part of the connector account - base data, credentials, customer
groups, languages, currencies, shipping methods - is read or written.
Full replacement, not a patch: the request describes the complete
desired state of the configuration section, and every writable field
must be sent. Omitting an optional field sets it to null (its documented
'unrestricted / not set' meaning), so a GET-modify-PUT round trip is the
intended usage; use UpdateConnector for field-wise partial updates. A
connector account that has no configuration row yet gets one created by
this call, which is why a partial write is not offered here - 'leave
unchanged' has no meaning against a row that does not exist. Persists
only: it does not contact the Connector endpoint at any point. Two
groups of ConnectorConfiguration fields are deliberately not writable
and are not part of this request. Live-only fields reported by the
connected endpoint's handshake (PlatformName, PlatformVersion,
ProtocolVersion, EndpointVersion, IsOldConnector, ServerInfo) are not
persisted at all and can never be written. DummyCategoryId is
system-managed - the import pipeline assigns the fallback category
itself when an imported product has no category - so it is read-only
here and its stored value is preserved unchanged by this call.
Submitting any of those names is not an error on REST, where unknown
body properties are ignored; on GraphQL the schema rejects them as
unknown input fields.
operationId: Connector_SaveConnectorConfiguration
parameters:
- name: salesChannelId
in: path
required: true
description: >-
Sales channel id of the connector account whose configuration is
replaced.
schema:
type: string
- name: x-tenant-id
in: header
required: true
schema:
type: string
format: uuid
description: The tenant ID for the target ERP instance.
requestBody:
x-name: SaveConnectorConfigurationRequest
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.Endpoints.V2.Connector.SaveConnectorConfigurationRequest
required: true
x-position: 1
responses:
'200':
description: >-
The configuration was replaced. Returns the configuration as
persisted, re-read after the write - not an echo of the request - so
normalised values (uppercased ShippingCountryIso, omitted optionals
resolved to null) and the preserved read-only DummyCategoryId are
visible to the caller.
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorConfiguration
'400':
description: >-
A submitted value is outside its allowed range or does not match its
required format - for example ShippingCountryIso is not a two-letter
ISO 3166-1 alpha-2 code, or a count is negative. Nothing is written.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'401':
description: Unauthorized.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'403':
description: Forbidden.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'404':
description: >-
Malformed or invalid sales channel id, or no Connector account
exists for the specified sales channel id.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'500':
description: Internal server error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
security:
- oauth2-authorization-code:
- saleschannels.write
- oauth2-client-credentials:
- saleschannels.write
components:
schemas:
JTL.Wawi.Verkaufskanaele.PublicApi.Endpoints.V2.Connector.SaveConnectorConfigurationRequest:
type: object
description: >-
Request model for SaveConnectorConfiguration command endpoint.
Route parameters bind from the route, query parameters from the query
string, everything else from the body.
additionalProperties: false
required:
- canImport
- shouldImportItemsAndCategories
- shouldImportOrdersAndCustomers
- shouldImportImages
- canUpload
- shouldUploadItemComplete
- shouldUploadItemPriceRestricted
- shouldUploadItemStockRestricted
- shouldUploadCustomers
- shouldUploadImages
- shouldRefreshExistingItems
- shouldRefreshCustomers
- shouldDeleteImagesOnImport
- shouldWawiCalculateTaxRate
- shouldWawiCalculateTaxRateForShipping
- pullCount
- quickSyncCount
- sendOnlyAssignedManufacturers
properties:
canImport:
type: boolean
description: The connector account is allowed to import data from the endpoint.
shouldImportItemsAndCategories:
type: boolean
description: Items and categories are imported.
shouldImportOrdersAndCustomers:
type: boolean
description: Orders and customers are imported.
shouldImportImages:
type: boolean
description: Item images are imported.
canUpload:
type: boolean
description: The connector account is allowed to upload data to the endpoint.
shouldUploadItemComplete:
type: boolean
description: Items are uploaded completely, rather than price/stock-restricted.
shouldUploadItemPriceRestricted:
type: boolean
description: Item uploads are restricted to prices only.
shouldUploadItemStockRestricted:
type: boolean
description: Item uploads are restricted to stock only.
shouldUploadCustomers:
type: boolean
description: Customer data is uploaded.
shouldUploadImages:
type: boolean
description: Images are uploaded.
shouldRefreshExistingItems:
type: boolean
description: Existing items are merged/refreshed rather than only added.
shouldRefreshCustomers:
type: boolean
description: Existing customer data is refreshed.
shouldDeleteImagesOnImport:
type: boolean
description: Images are deleted on import.
shouldWawiCalculateTaxRate:
type: boolean
description: >-
The Wawi calculates the tax rate for items, rather than taking the
endpoint-reported one.
shouldWawiCalculateTaxRateForShipping:
type: boolean
description: >-
The Wawi calculates the tax rate for shipping, rather than taking
the endpoint-reported one.
maximumTransferRate:
type: number
description: >-
Maximum transfer rate for uploads, in megabytes. Omit or send null
for unrestricted.
format: decimal
imagesCount:
type: integer
description: >-
Maximum number of images transferred per run. Omit or send null for
unrestricted.
format: int32
entityCount:
type: integer
description: >-
Maximum number of entities transferred per run. Omit or send null
for unrestricted.
format: int32
pullCount:
type: integer
description: >-
Maximum pull count per sync run. The desktop client offers 1-1000
here; the API only requires a non-negative value, so an existing
out-of-range row stays round-trippable.
format: int32
quickSyncCount:
type: integer
description: >-
Maximum quick-sync count per sync run. The desktop client offers
1-1000 here; the API only requires a non-negative value, so an
existing out-of-range row stays round-trippable.
format: int32
sendOnlyAssignedManufacturers:
type: boolean
description: >-
Manufacturer data sent to the endpoint is filtered to only assigned
manufacturers.
shippingCountryIso:
type: string
description: >-
The shipping/departure country as an ISO 3166-1 alpha-2 country
code. Omit or send null to clear it. Matching is case-insensitive;
the value is stored and returned in the canonical UPPERCASE form
(ADR-85).
JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorConfiguration:
type: object
description: >-
The persisted synchronisation configuration of a connector account
(dbo.tShopKonfiguration). Live-only, non-persisted fields reported by
the connected endpoint's handshake (PlatformName, PlatformVersion,
ProtocolVersion, EndpointVersion, IsOldConnector, ServerInfo) are not
part of this DB-backed read.
additionalProperties: false
required:
- canImport
- shouldImportItemsAndCategories
- shouldImportOrdersAndCustomers
- shouldImportImages
- canUpload
- shouldUploadItemComplete
- shouldUploadItemPriceRestricted
- shouldUploadItemStockRestricted
- shouldUploadCustomers
- shouldUploadImages
- shouldRefreshExistingItems
- shouldRefreshCustomers
- shouldDeleteImagesOnImport
- shouldWawiCalculateTaxRate
- shouldWawiCalculateTaxRateForShipping
- pullCount
- quickSyncCount
- sendOnlyAssignedManufacturers
properties:
canImport:
type: boolean
description: The connector account is allowed to import data from the endpoint.
shouldImportItemsAndCategories:
type: boolean
description: Items and categories are imported.
shouldImportOrdersAndCustomers:
type: boolean
description: Orders and customers are imported.
shouldImportImages:
type: boolean
description: Item images are imported.
canUpload:
type: boolean
description: The connector account is allowed to upload data to the endpoint.
shouldUploadItemComplete:
type: boolean
description: Items are uploaded completely, rather than price/stock-restricted.
shouldUploadItemPriceRestricted:
type: boolean
description: Item uploads are restricted to prices only.
shouldUploadItemStockRestricted:
type: boolean
description: Item uploads are restricted to stock only.
shouldUploadCustomers:
type: boolean
description: Customer data is uploaded.
shouldUploadImages:
type: boolean
description: Images are uploaded.
shouldRefreshExistingItems:
type: boolean
description: Existing items are merged/refreshed rather than only added.
shouldRefreshCustomers:
type: boolean
description: Existing customer data is refreshed.
shouldDeleteImagesOnImport:
type: boolean
description: Images are deleted on import.
shouldWawiCalculateTaxRate:
type: boolean
description: >-
The Wawi calculates the tax rate for items, rather than taking the
endpoint-reported one.
shouldWawiCalculateTaxRateForShipping:
type: boolean
description: >-
The Wawi calculates the tax rate for shipping, rather than taking
the endpoint-reported one.
maximumTransferRate:
type: number
description: >-
Maximum transfer rate for uploads, in megabytes, or null if
unrestricted.
format: decimal
imagesCount:
type: integer
description: >-
Maximum number of images transferred per run, or null if
unrestricted.
format: int32
entityCount:
type: integer
description: >-
Maximum number of entities transferred per run, or null if
unrestricted.
format: int32
pullCount:
type: integer
description: Maximum pull count per sync run.
format: int32
quickSyncCount:
type: integer
description: Maximum quick-sync count per sync run.
format: int32
sendOnlyAssignedManufacturers:
type: boolean
description: >-
Manufacturer data sent to the endpoint is filtered to only assigned
manufacturers.
shippingCountryIso:
type: string
description: >-
The shipping/departure country as an ISO 3166-1 alpha-2 country
code, or null if not set. Canonical form is UPPERCASE (ADR-85);
matching is case-insensitive.
dummyCategoryId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.KategorieKey'
description: >-
Fallback category for uncategorized imported items, or null if not
set.
FastEndpoints.ProblemDetails:
type: object
additionalProperties: false
properties:
type:
type: string
default: https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1
title:
type: string
default: One or more validation errors occurred.
status:
type: integer
format: int32
default: 400
instance:
type: string
default: /api/route
traceId:
type: string
default: 0HMPNHL0JHL76:00000001
detail:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails_Error'
JTL.Data.Contracts.Keys.KategorieKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
FastEndpoints.ProblemDetails_Error:
type: object
additionalProperties: false
properties:
name:
type: string
default: Error or field name
reason:
type: string
default: Error reason
code:
type: string
severity:
type: string
securitySchemes:
oauth2-authorization-code:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.jtl-cloud.com/oauth2/auth
tokenUrl: https://auth.jtl-cloud.com/oauth2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
saleschannels.read: Grants permission to read sales channels.
saleschannels.write: Grants permission to create and modify sales channels.
all.read: Allows the application to read all data.
customers.read: Grants permission to read customer data.
customers.write: Grants permission to create and modify customer data.
customfields.read: Grants permission to read custom fields.
customfields.write: Grants permission to create and modify custom fields.
deliveries.read: Grants permission to read deliveries.
deliveries.write: Grants permission to create and modify deliveries.
deliverynotes.print: Grants permission to print and output delivery notes.
deliverynotes.read: Grants permission to read delivery notes.
deliverynotes.write: Grants permission to create and modify delivery notes.
extensibility.integration: >-
Grants permission to manage extensions and integrations of the
JTL-Wawi.
inventories.read: Grants permission to read stock levels.
invoices.read: Grants permission to read invoices.
invoices.write: Grants permission to create and modify invoices.
labels.read: Grants permission to read labels.
labels.write: Grants permission to create and modify labels.
masterdata.read: >-
Read master data such as shipping methods, payment methods, color
codes and tax classes.
orders.read: Grants permission to read orders.
picklists.read: Grants permission to read pick lists.
picklists.write: Grants permission to create and modify pick lists.
returns.read: Grants permission to read returns.
returns.write: Grants permission to create and modify returns.
salesinvoicecorrections.read: Grants permission to read invoice corrections.
salesinvoicecorrections.write: Grants permission to create and modify invoice corrections.
salesorders.print: Grants permission to print and output sales orders.
salesorders.read: Grants permission to read sales orders.
salesorders.write: Grants permission to create and modify sales orders.
system.config.read: Grants permission to read the system configuration.
system.config.write: Grants permission to modify the system configuration.
taxes.read: Grants permission to read tax data.
warehouse.read: Grants permission to read warehouse data.
wawiapp.all: Grants access to Wawi app related operations.
currencies.read: Grants read access to currencies.
jera.read: Grants read access to JERA internal endpoints.
paymentmethods.read: Grants read access to payment methods.
payments.read: Ermöglicht den Lesezugriff auf Zahlungen.
payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
salesinvoices.print: Grants permission to print and output sales invoices.
salesinvoices.read: Grants read access to sales invoices.
salesinvoices.write: Grants write access to sales invoices.
salesquotations.print: Grants permission to print and output sales quotations.
salesquotations.read: Grants read access to sales quotations.
salesquotations.write: Grants write access to sales quotations.
system.worker.read: Worker-Synchronisationen lesen
system.worker.write: Worker-Synchronisationen schreiben
resources.read: Grants permission to read resource management data.
resources.write: Grants permission to create and modify resource management data.
pps.read: Grants permission to read production data.
pps.write: Grants permission to create and modify production data.
channels.read: Grants permission to read marketplace channels.
invoices.print: >-
Grants permission to print marketplace external documents
(invoices, credit notes).
marketplaceoffers.read: Grants permission to read marketplace offers and offer failures.
marketplaceoffers.write: Grants permission to create and modify marketplace offers.
notifications.read: Grants permission to read marketplace notifications.
orders.write: >-
Grants permission to modify marketplace order data (exclude/reset
cancellation, payment, return and shipping uploads).
masterdata.write: Write master data
taxes.write: Grants permission to create and modify tax data.
application.runas: >-
Allows the application to execute requests on behalf of another
user.
oauth2-client-credentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth.jtl-cloud.com/oauth2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
saleschannels.read: Grants permission to read sales channels.
saleschannels.write: Grants permission to create and modify sales channels.
all.read: Allows the application to read all data.
customers.read: Grants permission to read customer data.
customers.write: Grants permission to create and modify customer data.
customfields.read: Grants permission to read custom fields.
customfields.write: Grants permission to create and modify custom fields.
deliveries.read: Grants permission to read deliveries.
deliveries.write: Grants permission to create and modify deliveries.
deliverynotes.print: Grants permission to print and output delivery notes.
deliverynotes.read: Grants permission to read delivery notes.
deliverynotes.write: Grants permission to create and modify delivery notes.
extensibility.integration: >-
Grants permission to manage extensions and integrations of the
JTL-Wawi.
inventories.read: Grants permission to read stock levels.
invoices.read: Grants permission to read invoices.
invoices.write: Grants permission to create and modify invoices.
labels.read: Grants permission to read labels.
labels.write: Grants permission to create and modify labels.
masterdata.read: >-
Read master data such as shipping methods, payment methods, color
codes and tax classes.
orders.read: Grants permission to read orders.
picklists.read: Grants permission to read pick lists.
picklists.write: Grants permission to create and modify pick lists.
returns.read: Grants permission to read returns.
returns.write: Grants permission to create and modify returns.
salesinvoicecorrections.read: Grants permission to read invoice corrections.
salesinvoicecorrections.write: Grants permission to create and modify invoice corrections.
salesorders.print: Grants permission to print and output sales orders.
salesorders.read: Grants permission to read sales orders.
salesorders.write: Grants permission to create and modify sales orders.
system.config.read: Grants permission to read the system configuration.
system.config.write: Grants permission to modify the system configuration.
taxes.read: Grants permission to read tax data.
warehouse.read: Grants permission to read warehouse data.
wawiapp.all: Grants access to Wawi app related operations.
currencies.read: Grants read access to currencies.
jera.read: Grants read access to JERA internal endpoints.
paymentmethods.read: Grants read access to payment methods.
payments.read: Ermöglicht den Lesezugriff auf Zahlungen.
payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
salesinvoices.print: Grants permission to print and output sales invoices.
salesinvoices.read: Grants read access to sales invoices.
salesinvoices.write: Grants write access to sales invoices.
salesquotations.print: Grants permission to print and output sales quotations.
salesquotations.read: Grants read access to sales quotations.
salesquotations.write: Grants write access to sales quotations.
system.worker.read: Worker-Synchronisationen lesen
system.worker.write: Worker-Synchronisationen schreiben
resources.read: Grants permission to read resource management data.
resources.write: Grants permission to create and modify resource management data.
pps.read: Grants permission to read production data.
pps.write: Grants permission to create and modify production data.
channels.read: Grants permission to read marketplace channels.
invoices.print: >-
Grants permission to print marketplace external documents
(invoices, credit notes).
marketplaceoffers.read: Grants permission to read marketplace offers and offer failures.
marketplaceoffers.write: Grants permission to create and modify marketplace offers.
notifications.read: Grants permission to read marketplace notifications.
orders.write: >-
Grants permission to modify marketplace order data (exclude/reset
cancellation, payment, return and shipping uploads).
masterdata.write: Write master data
taxes.write: Grants permission to create and modify tax data.
application.runas: >-
Allows the application to execute requests on behalf of another
user.
````