{
  "openapi": "3.0.2",
  "info": {
    "title": "SCX Public API",
    "version": "1.0",
    "x-logo": {
      "url": "https://scx-sandbox.ui.jtl-software.com/docs/scx.png"
    },
    "description": "SCX Public API\n"
  },
  "servers": [
    {
      "url": "https://scx-sbx.api.jtl-software.com",
      "description": "Sandbox Environment"
    },
    {
      "url": "https://scx.api.jtl-software.com",
      "description": "Production Environment"
    }
  ],
  "tags": [
    {
      "name": "Channel",
      "description": "Public channel discovery routes"
    }
  ],
  "paths": {
    "/v1/public/channel": {
      "get": {
        "operationId": "GetChannelList",
        "tags": [
          "Channel"
        ],
        "summary": "Channel List",
        "description": "List all channels available through SCX platform.\n",
        "parameters": [
          {
            "in": "query",
            "name": "offset",
            "description": "Pagination offset (number of channels to skip)",
            "required": false,
            "example": 0,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "description": "Maximum number of channels to return per page",
            "required": false,
            "example": 100,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "marketplace",
            "description": "Filter by marketplace country code (e.g. `DE`, `AT`, `CH`)",
            "required": false,
            "example": "DE",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "visibility",
            "description": "Filter channels by visibility scope:\n  * `JTL` — public JTL channels\n  * `THIRDPARTY` — third-party channels\n  * `ONBOARDING` — channels currently in onboarding\n  * `RESTRICTED` — channels with restricted access\n",
            "required": false,
            "example": "JTL",
            "schema": {
              "type": "string",
              "enum": [
                "JTL",
                "THIRDPARTY",
                "ONBOARDING",
                "RESTRICTED"
              ]
            }
          }
        ],
        "security": [
          {},
          {
            "SellerAuth": []
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ChannelList"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "ChannelList": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ChannelList"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseList"
            },
            "example": {
              "errorList": [
                {
                  "code": "VAL100",
                  "message": "Required field sellerId not found",
                  "severity": "error",
                  "hint": "Check the field `sellerId` — it must be a non-empty string."
                }
              ]
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseList"
            },
            "example": {
              "errorList": [
                {
                  "code": "GEN500",
                  "message": "Internal Server Error",
                  "severity": "error",
                  "hint": null
                }
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "ChannelList": {
        "description": "Paginated list of sales channels publicly available on the JTL marketplace platform.",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pagination"
          },
          {
            "properties": {
              "channelList": {
                "$ref": "#/components/schemas/SalesChannelList"
              }
            }
          }
        ],
        "required": [
          "channelList"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "total": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "ChannelFeatureList": {
        "type": "object",
        "properties": {
          "invoiceDocumentTransfer": {
            "description": "Indicates if Invoice can be shared between Channel and Seller Implementation. If this flag is set to\n`from-seller` a connected client implementation (such as JTL-Wawi) can upload invoice documents using\n`POST /v1/seller/order/invoice`. When flag is set to `from-channel` a connected client can receive invoice from\na Channel by `Channel:Order.Invoice` Event. A value `not-supported` indicates that no invoices can be transmitted\nbetween Seller and Channel.\n",
            "type": "string",
            "enum": [
              "not-supported",
              "from-channel",
              "from-seller"
            ],
            "default": "not-supported"
          },
          "priceUpdatesSupported": {
            "description": "Indicates whether the channel is able to process events of type Seller:Offer.PriceUpdate\n",
            "type": "boolean",
            "default": false
          },
          "quantityPriceSupported": {
            "description": "Does the channel support quantity price for quantity greater than 1. In SCX all offer prices are represented by\na quantity price data structure. In case there is no support for quantity prices on a certain channel only\nthe price for quantity 1 is taken into account. All other price settings may be ignored by the connected\nchannel.\n",
            "type": "boolean",
            "default": false
          },
          "remainingQuanitySupported": {
            "description": "Indicates if a channel is able to support a remaing quanity with each Order. The feature can be used\nby a connected client implementation (such as JTL-Wawi) to manage quanity updates on an channel.\n",
            "type": "boolean",
            "default": false
          },
          "variationsSupported": {
            "description": "Does the channel supports listing of variation offers. Variations are multiple similar (but not identical)\nitems in a offer listing. For example, a single offer could contain multiple items of the same brand and\nmodel that vary by color and size (like \"Blue, Large\" and \"Black, Medium\"). Each variation can have its own\nquantity and price.\n",
            "type": "boolean",
            "default": false
          },
          "returnTrackingRequired": {
            "description": "Indicates if a channel requires a return tracking code for an order item shipping update.\n",
            "type": "boolean",
            "default": false
          },
          "allowCombineOrders": {
            "description": "Indicates if a channel allows the combination of multiple separate orders into one.\n",
            "type": "boolean",
            "default": false
          },
          "stockUpdateWithoutEventSupported": {
            "description": "Indicates if a channel will fetch Stock updates per Route without need of SellerEventOfferStockUpdate.\n",
            "type": "boolean",
            "default": false
          }
        }
      },
      "MinimumClientsVersionRequired": {
        "type": "object",
        "required": [
          "type",
          "version"
        ],
        "properties": {
          "type": {
            "type": "string",
            "example": "Wawi",
            "description": "Type of Client. Set to `Wawi` for JTL-Wawi.\n"
          },
          "version": {
            "type": "string",
            "example": "1.11.0.3",
            "description": "Minimum Client Version required for channel selection and sign up.\nMust be a semantic version (e.g., 1.11.0.3).\n"
          }
        }
      },
      "IsPlatform": {
        "description": "Defines whether a channel is a platform channel. Is the property is set to true the channel is considered as a platform channel.\nThe platform property must be null\n- true = Platform Channel\n- false = Marketplace or normal Channel\n",
        "type": "boolean",
        "default": false,
        "example": false
      },
      "Platform": {
        "description": "Belonging to a platform.\nIf set, it is a marketplace channel.\nIf isPlatform = true, this property must not be set.\n",
        "type": "string",
        "default": null,
        "example": "AMAZON"
      },
      "MarketplaceChannelList": {
        "description": "Only set for Platform Channel, and contains all Marketplace Channel names that have been assigned to the platform.\n",
        "type": "array",
        "default": null,
        "example": [
          "JTL Marketplace FR",
          "JTL Marketplace DE",
          "JTL Marketplace GB"
        ]
      },
      "StockSyncGroup": {
        "type": "string",
        "nullable": true,
        "description": "Groups Marketplace Channels for stock synchronization.\nRules:\n- May ONLY be set when `platform` != null (Marketplace Channel).\n- Must be null when `isPlatform` = true (Platform Channel).\nSemantics:\n- All Channels with the same `stockSyncGroup` expect only ONE stock update per SKU\n  (ERP sends to exactly one Channel of the group).\n",
        "example": "AMAZON-EU"
      },
      "ChannelBasedData": {
        "type": "object",
        "required": [
          "marketplaceList",
          "displayName",
          "website",
          "supportContact",
          "vendor",
          "signUpUrl",
          "featureList"
        ],
        "properties": {
          "group": {
            "type": "string",
            "example": "MyBestDeals",
            "nullable": true
          },
          "currency": {
            "description": "Currency which are supported by the Channel. According to ISO-4217.\n",
            "type": "string",
            "example": "EUR"
          },
          "marketplaceList": {
            "description": "Country ISO code or a list of ISO codes which geografic market is supported.\n",
            "type": "array",
            "items": {
              "type": "string",
              "example": "DE"
            }
          },
          "supportedLanguages": {
            "description": "Laguage ISO code or a list of ISO codes which languages ars supported. According to ISO 639-1.\n",
            "type": "array",
            "items": {
              "type": "string",
              "example": "de"
            }
          },
          "displayName": {
            "description": "Channel Name\n",
            "type": "string",
            "example": "MyBestDeals.com"
          },
          "website": {
            "type": "string",
            "format": "uri",
            "example": "https://mybestdeals.de/sell-with-jtl"
          },
          "pricing": {
            "type": "string",
            "format": "uri",
            "example": "https://mybestdeals.de/sell-with-jtl#pricing",
            "nullable": true
          },
          "channelType": {
            "type": "string",
            "default": "MARKETPLACE",
            "enum": [
              "MARKETPLACE",
              "OTHER"
            ]
          },
          "supportContact": {
            "type": "string",
            "format": "email",
            "example": "support@mybestdeals.de"
          },
          "vendor": {
            "type": "string",
            "example": "JTL-Software"
          },
          "signUpUrl": {
            "description": "The SignUp URL ist required for register new Sellers with the SCX Channel API.\nSCX will create a Sign-Up ID to link a seller with SCX.\n",
            "type": "string",
            "example": "https://mysqlbestdeals.com/signup-for-scx?session={SESSION}"
          },
          "updateUrl": {
            "description": "The Update URL ist required for updating a existing Sellers with the SCX Channel API. If this URL is\nnot set it will use the signUpUrl as a fallback\n",
            "type": "string",
            "example": "https://mysqlbestdeals.com/signup-for-scx?session={SESSION}"
          },
          "logo": {
            "type": "string",
            "description": "URL of a Channel logo\n",
            "example": "https://mysqlbestdeals.com/logo.svg",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "Description text of a channel\n",
            "example": "MyBestDeals is the marketplace where customers find the best deals in the world.",
            "nullable": true
          },
          "appId": {
            "type": "string",
            "description": "AppId of a channel. Wawi use this to create Links to the Channel-Documentation\n",
            "example": "mybestdeals",
            "nullable": true
          },
          "featureList": {
            "$ref": "#/components/schemas/ChannelFeatureList"
          },
          "minimumClientsVersionRequired": {
            "type": "array",
            "description": "Must be a list of supported Clients. If at least one item is defined SCX will validate the Client version during sign up process. \nIf the list is empty or null, no client restrictions is in place.\n",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/MinimumClientsVersionRequired"
            }
          },
          "isPlatform": {
            "$ref": "#/components/schemas/IsPlatform"
          },
          "platform": {
            "$ref": "#/components/schemas/Platform"
          },
          "marketplaceChannelList": {
            "$ref": "#/components/schemas/MarketplaceChannelList"
          },
          "stockSyncGroup": {
            "$ref": "#/components/schemas/StockSyncGroup"
          }
        }
      },
      "SalesChannelBase": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/ChannelBasedData"
          }
        ],
        "properties": {
          "visibility": {
            "type": "string",
            "description": "Sales Channel visibility.\n\n* **JTL**: Channel provided directly by JTL\n* **THIRDPARTY**: Channel hostet, supported and accounted by a 3rd Party vendor\n* **ONBOARDING**: Channel is in on boarding process - these channels are only visible to selected user group\n* **RESTRICTED**: Channel can only be shown to select sellers\n* **(Deprecated) PUBLIC**: do not use\n",
            "enum": [
              "JTL",
              "THIRDPARTY",
              "ONBOARDING",
              "RESTRICTED"
            ],
            "example": "JTL"
          }
        }
      },
      "Channel": {
        "description": "This is the unique Channel name.\n",
        "type": "string",
        "example": "MYBESTDEALCOMDE",
        "pattern": "^\\w{5,15}$"
      },
      "SalesChannelData": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/SalesChannelBase"
          }
        ],
        "required": [
          "channel",
          "currency",
          "visibility",
          "marketplaceList",
          "displayName",
          "website",
          "supportContact",
          "vendor",
          "signUpUrl",
          "isPlatform"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          }
        }
      },
      "SalesChannel": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/SalesChannelData"
          },
          {
            "properties": {
              "statistics": {
                "type": "object",
                "properties": {
                  "rating": {
                    "type": "integer",
                    "example": 95
                  },
                  "avgOfferListingDelaySeconds": {
                    "type": "integer",
                    "example": 120
                  },
                  "avgOrderDelaySeconds": {
                    "type": "integer",
                    "example": 30
                  }
                }
              }
            }
          }
        ]
      },
      "SalesChannelList": {
        "type": "array",
        "minItems": 0,
        "maxItems": 50,
        "items": {
          "$ref": "#/components/schemas/SalesChannel"
        }
      },
      "ErrorResponseList": {
        "type": "object",
        "properties": {
          "errorList": {
            "nullable": true,
            "type": "array",
            "example": [
              {
                "code": "GEN700",
                "message": "Seller SELLER_4711 does not exist on channel kaufland.",
                "severity": "error",
                "hint": "i9n-order22"
              }
            ],
            "items": {
              "title": "Error",
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "GEN700"
                },
                "message": {
                  "type": "string",
                  "example": "Seller SELLER_4711 does not exist on channel kaufland."
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "error",
                    "warning",
                    "info"
                  ],
                  "default": "error"
                },
                "hint": {
                  "type": "string",
                  "nullable": true,
                  "example": "i9n-order22"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "SellerAuth": {
        "description": "You can create a JSON Web Token (JWT) by SignUp a JTL-Scx Subscription using the JTL Customer center.\nUsage format: Bearer <JWT>\n",
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}