JTL-Marketplaces (SCX)
/
Developer Guide
Last updated

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Developer Guide

With the JTL-Channel API, you can:

  • Describe connected marketplace data structure by providing category and attribute data
  • Manage product and offer listings
  • Update price and quantity of a listing
  • Manage orders
  • Manage the post-order process (returns, refunds)

Target Audience:

  • Marketplaces who wanting to connect with sellers who use JTL-Software with an eazyAuction subscription
  • Software developers who want to connect to a marketplace

Terminology

  • Channel: A channel is defined as a connection to a marketplace or any external system which can be connected to the JTL-Channel API.
  • Seller: A seller is a person identified by a unique ID (SellerId) who wants to offer and sell his goods on the connected Channel.
  • Event: An Event is an action initiated from a seller. A channel need to react to events in order to create or update a listing or to process post order actions.
  • Seller API: This is the Channel API counterpart. The ERP system JTL-Wawi is connected with the Seller API.

Development cycle

API - Hosts

Sandbox: https://scx-sbx.api.jtl-software.com

Production: https://scx.api.jtl-software.com

Prerequisite

To access the JTL-Channel API you will need an API refresh token. These token are created during the onboarding process together with JTL. If you are interested to connect your marketplace with the JTL ecosystem, please do not hesitate to contact us.

https://www.jtl-software.de/kontakt

Development

The Channel implementation runs on your own infrastructure. You as the Channel integrator have the full responsibility to run, manage and secure your application.

Error Handling

Error responses are indicated by an HTTP status code >=400. The Channel API uses a consistent error response format for all API errors.

{
    "errorList": [
        {
            "code": "VAL100",
            "message": "orderList[0].sellerId: SellerId darf nicht leer sein und maximal 50 alphnumerische Zeichen beinhalten",
            "severity": "error",
            "hint": null
        },
        {
            "code": "VAL100",
            "message": "orderList[0].orderStatus: Ungültiger oder unbekannter Order Status. Muss einer der folgenden Werte sein UNACKED, CREATED, ACCEPTED, SHIPPED, PARTIALLY_SHIPPED, CANCELED_BY_SELLER, CANCELED_BY_BUYER",
            "severity": "error",
            "hint": null
        },
        {
            "code": "VAL100",
            "message": "orderList[0].orderStatus: Ungültiger oder unbekannter Order Status. Muss einer der folgenden Werte sein UNACKED, CREATED, ACCEPTED, SHIPPED, PARTIALLY_SHIPPED, CANCELED_BY_SELLER, CANCELED_BY_BUYER",
            "severity": "error",
            "hint": null
        }
    ]
}

We are supporting language de (German) as default. This can be changed to en by setting the Accept-Language header.

Setup of a local JTL-Wawi instance

It may be helpful to use the JTL-Wawi ERP System during development to create new listings or manage orders.

To connect the ERP System with the sandbox environment install a JTL-Wawi Version 1.8+.

Connect to MSSQL Server directly

Add the seller's refresh token - the token will be created during onboarding process.

INSERT INTO SCX.tRefreshToken 
(cRefreshToken, nType)
VALUES 
(N'<SellerAPI-RefreshToken>', 1);

Switch API Host to Sandbox

UPDATE dbo.tOptions 
SET cValue ='https://scx-sbx.api.jtl-software.com' 
WHERE ckey = 'SCX.URL'

Restart JTL-Wawi

Using the Seller-API directly

To test workflows and to send test data to the channel API, you can directly use the Seller API. Please see the technical documentation and our Postman Collection.

Channel-API Documentation https://scx-sandbox.ui.jtl-software.com/docs/api_channel.html

Seller-API Documentation https://scx-sandbox.ui.jtl-software.com/docs/api_seller.html

Postman Collection https://www.postman.com/jtl-eazyauction/workspace/jtl-scx-public

Previous page
Next page