> ## 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.
# Declaratively replaces the complete set of customer-group mappings of a connector account and pushes the resulting mapping live to the Connector endpoint.
> Declaratively replaces the complete set of customer-group mappings of a connector account and pushes the resulting mapping live to the Connector endpoint. The request describes the full desired state - provided assignments are upserted and every mapping not contained in the request is cleared. An EndpointId that is neither already mapped nor currently reported by the Connector endpoint (stale data) is silently ignored, exactly as if it had not been submitted. Persistence of the resulting write always succeeds independently of the later live push outcome; a failed or timed-out live push is reported via LiveSyncStatus/LiveSyncError but does not roll back the persisted assignments or change the response code. This command has no IsDefault input - a customer group's default flag, like its display name, is reported by the Connector endpoint itself; it is never accepted from or echoed back with authority by this write path, so a GET-modify-PUT round trip cannot change or need to preserve it. For an EndpointId not already mapped, EndpointName/IsDefault are instead resolved with one live read from the Connector endpoint before anything is persisted - unlike the later live push, a failure of this live read does fail the whole request (502/504) and persists nothing, because it is needed to build a valid response.
## OpenAPI
````yaml /openapi/erp/2.1.json put /v2/sales-channels/{salesChannelId}/connector/customer-groups
openapi: 3.0.0
info:
title: JTL-WAWI API (Cloud)
description: "JTL-Wawi-Version: 2.2.0-alpha.8292+Sha.bcd1bc9\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 Seller
- name: Seller
- 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/customer-groups:
put:
tags:
- wawi
- Sales Channel
summary: >-
Declaratively replaces the complete set of customer-group mappings of a
connector account and pushes the resulting mapping live to the Connector
endpoint.
description: >-
Declaratively replaces the complete set of customer-group mappings of a
connector account and pushes the resulting mapping live to the Connector
endpoint. The request describes the full desired state - provided
assignments are upserted and every mapping not contained in the request
is cleared. An EndpointId that is neither already mapped nor currently
reported by the Connector endpoint (stale data) is silently ignored,
exactly as if it had not been submitted. Persistence of the resulting
write always succeeds independently of the later live push outcome; a
failed or timed-out live push is reported via
LiveSyncStatus/LiveSyncError but does not roll back the persisted
assignments or change the response code. This command has no IsDefault
input - a customer group's default flag, like its display name, is
reported by the Connector endpoint itself; it is never accepted from or
echoed back with authority by this write path, so a GET-modify-PUT round
trip cannot change or need to preserve it. For an EndpointId not already
mapped, EndpointName/IsDefault are instead resolved with one live read
from the Connector endpoint before anything is persisted - unlike the
later live push, a failure of this live read does fail the whole request
(502/504) and persists nothing, because it is needed to build a valid
response.
operationId: Connector_SaveConnectorCustomerGroups
parameters:
- name: salesChannelId
in: path
required: true
description: >-
Sales channel id of the Connector whose customer groups are
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: SaveConnectorCustomerGroupsRequest
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.Endpoints.V2.Connector.SaveConnectorCustomerGroupsRequest
required: true
x-position: 1
responses:
'200':
description: >-
Successfully replaced the customer-group mappings. Returns the
persisted mappings together with the outcome of the live push to the
Connector endpoint.
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.SaveConnectorCustomerGroupsCommandResponse
'400':
description: >-
A provided CustomerGroupId does not exist; the same CustomerGroupId
is named more than once; or the same EndpointId (compared
case-insensitively) is used by more than one assignment. No mapping
is changed.
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'
'502':
description: >-
At least one submitted EndpointId is not already mapped, and the
Connector endpoint could not be reached, rejected the request, or
returned an invalid response while resolving it. No mapping is
changed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'504':
description: >-
At least one submitted EndpointId is not already mapped, and the
Connector endpoint did not respond within the request timeout while
resolving it. No mapping is changed.
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.SaveConnectorCustomerGroupsRequest:
type: object
description: >-
Request model for SaveConnectorCustomerGroups command endpoint.
Route parameters bind from the route, query parameters from the query
string, everything else from the body.
additionalProperties: false
required:
- customerGroups
properties:
customerGroups:
type: array
description: >-
The complete desired set of customer-group mappings for the
connector account. Any existing mapping not contained in this list
is cleared.
items:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorCustomerGroupMappingAssignment
JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.SaveConnectorCustomerGroupsCommandResponse:
type: object
description: >-
Declaratively replaces the complete set of customer-group mappings of a
connector account and pushes the resulting mapping live to the Connector
endpoint. The request describes the full desired state - provided
assignments are upserted and every mapping not contained in the request
is cleared. An EndpointId that is neither already mapped nor currently
reported by the Connector endpoint (stale data) is silently ignored,
exactly as if it had not been submitted. Persistence of the resulting
write always succeeds independently of the later live push outcome; a
failed or timed-out live push is reported via
LiveSyncStatus/LiveSyncError but does not roll back the persisted
assignments or change the response code. This command has no IsDefault
input - a customer group's default flag, like its display name, is
reported by the Connector endpoint itself; it is never accepted from or
echoed back with authority by this write path, so a GET-modify-PUT round
trip cannot change or need to preserve it. For an EndpointId not already
mapped, EndpointName/IsDefault are instead resolved with one live read
from the Connector endpoint before anything is persisted - unlike the
later live push, a failure of this live read does fail the whole request
(502/504) and persists nothing, because it is needed to build a valid
response. - Response
additionalProperties: false
required:
- customerGroups
- liveSyncStatus
- liveSyncError
properties:
customerGroups:
type: array
description: >-
The persisted customer-group mappings, minus any submitted
EndpointId ignored as stale (see the command description). For an
EndpointId already mapped, EndpointName/IsDefault are carried over
unchanged from the previously persisted state, exactly as before
this call. For a first-time EndpointId, both are instead resolved
from a live read performed before persisting, so IsDefault is always
a definite, known value here too, never a guess - EndpointName can
still be null there if the endpoint itself reports no usable
localized name for that group, the same case
QueryConnectorCustomerGroups already tolerates. This list is
independent of the later live push outcome reported in
LiveSyncStatus/LiveSyncError - it reflects what was persisted, not a
re-pull after that push, so it does not depend on or wait for the
push to succeed.
items:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorCustomerGroupListItem
liveSyncStatus:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorLiveSyncStatus
description: Outcome of the live push to the Connector endpoint.
liveSyncError:
$ref: >-
#/components/schemas/JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorLiveSyncError
description: >-
Details of the live sync outcome. Code and Message are not set when
LiveSyncStatus is Synced (omitted in REST JSON, null in GraphQL),
and populated when it is SyncFailed or SyncTimedOut. Always present
as an object (rather than the field itself being nullable) because
Command response properties do not support optional-field validation
the way GET model properties do - this shape sidesteps that
generator limitation.
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.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorCustomerGroupMappingAssignment:
type: object
description: >-
A single desired customer-group mapping assignment for a connector
account (which internal Wawi customer group an endpoint-side customer
group is mapped to).
additionalProperties: false
required:
- endpointId
- customerGroupId
properties:
endpointId:
type: string
description: The customer group's identifier on the endpoint side.
customerGroupId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.KundenGruppeKey'
description: >-
ID of the internal Wawi customer group this endpoint group is mapped
to.
JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorCustomerGroupListItem:
type: object
description: >-
A single customer group as reported by the Connector endpoint, merged
with its Wawi-side mapping if one exists.
additionalProperties: false
required:
- endpointId
- isDefault
properties:
endpointId:
type: string
description: >-
The customer group's identifier on the endpoint side. Always present
— rows the endpoint reports without a usable identifier are not
returned.
endpointName:
type: string
description: >-
The customer group's display name on the endpoint side, or null if
no usable localized name was reported.
customerGroupId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.KundenGruppeKey'
description: >-
ID of the internal Wawi customer group this endpoint group is mapped
to, or null if the endpoint group has not been mapped yet.
isDefault:
type: boolean
description: >-
This customer group is the default customer group for the connector
account.
JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorLiveSyncStatus:
type: integer
description: 0 = Unknown, 1 = Synced, 2 = SyncFailed, 3 = SyncTimedOut
format: int32
x-enumNames:
- Unknown
- Synced
- SyncFailed
- SyncTimedOut
enum:
- 0
- 1
- 2
- 3
JTL.Wawi.Verkaufskanaele.PublicApi.DataTransferObjects.V2.Connector.ConnectorLiveSyncError:
type: object
description: >-
Details of the live push outcome to the Connector endpoint. Code and
Message are not set on success (LiveSyncStatus.Synced - omitted in REST
JSON, null in GraphQL) and populated on failure or timeout.
additionalProperties: false
properties:
code:
type: string
description: >-
Machine-readable error code of the live sync failure, not set on
success (omitted in REST JSON, null in GraphQL).
message:
type: string
description: >-
Human-readable message describing the live sync failure, not set on
success (omitted in REST JSON, null in GraphQL).
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
JTL.Data.Contracts.Keys.KundenGruppeKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
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).
sellers.read: >-
Grants permission to read marketplace sellers and their
configuration.
sellers.write: >-
Grants permission to create and modify marketplace sellers and
their configuration.
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).
sellers.read: >-
Grants permission to read marketplace sellers and their
configuration.
sellers.write: >-
Grants permission to create and modify marketplace sellers and
their configuration.
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.
````