Flat Sorter API (2.9, 2.10, 2.11)

This API is documented in OpenAPI Specification (OAS) format. In addition to standard OpenAPI syntax a few vendor extensions are used for easier documentation.

The standard UTF-8 is used for the character encoding for the data interchange between KiSoft One and the higher-level system.

Throughout this documentation, monospace letters are used for data definitions (fields, values, etc...).

When referencing certain values of data fields, every "value" is written in quotation marks.

All data fields are named in camelCase schema with lowercase first letter.

All component references in the OAS schema are named in PascalCase schema with uppercase first letter.

Since this specification can be used on non HTTP transport layers, it omits the use of URI parameters (e.g. PATCH /frameworkRoute/{clientNumber}/{orderNumber}).

A date attribute has to be transmitted as string in the following format: YYYY-MM-DD, e. g. 2024-03-15.

A time attribute has to be transmitted as string in the following format: HH:MM:SS, e. g. 14:30:00.

A date-time attribute has to be transmitted as string in the following format: YYYY-MM-DDTHH:MM:SSZ, e.g. 2024-01-24T14:15:22Z.

For the transmission of identifying attributes in the openAPI messages the following rules must be followed:

• for messages with clientNumber: for the same clientNumber each value of the identifying attribute (e. g. orderNumber, inboundDeliveryNumber, requestNumber) must be unique among all types of messages for this attribute.
• for messages without clientNumber: each value of the identifying attribute (e. g. requestNumber of message requestStorageReport) must be globally unique among all types of messages.

It is highly recommended to use HTTPS as the default transport layer for communication. Nevertheless, the interface may be used without any transport layer security.

Note that using the interface without transport layer security is not recommended and should only be used in isolated network environments to ensure communication interference is prevented.

This interface allows for application layer security by providing authentication methods.

Accessing the interface can be restricted to authenticated communication partners.

The following authentication flows are provided.

Client Credentials Flow (available in KiSoft One 2.10)

With machine-to-machine (M2M) applications, such as this host interface, the system authenticates and authorizes another app rather than a user. For this scenario, typical authentication schemes like username + password or social logins don't make sense. Instead, M2M apps use the Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4), in which they pass along their Client ID and Client Secret to authenticate themselves and get a token.

The flow contains the following interaction steps:

1. Your app authenticates with the Authorization Server using its Client ID and Client Secret (/oauth/token endpoint).
2. Authorization Server validates the Client ID and Client Secret.
3. Authorization Server responds with an Access Token.
4. Your application can use the Access Token to call an API on behalf of itself.
5. The API responds with requested data.

JSON and/or XML messages on e.g. simple TCP/IP connections without the URL and HTTP-method have to compensate for missing information. A corresponding encapsulation element/object has to be added in order to achieve this.

Information which would normally be part of the HTTP header, will be added as additional fields to the top element/object. (see examples below). The name of the object will compensate for the missing http request method and the http request path Response messages will contain an additional attribute called httpResponseStatus which represents the request status

Note: When using the Replychannels via Websockets, the same rules apply to the message syntax as are used with TCP/IP socket streams.

Note: XML messages always provide the encapsulating element including the attributes, to provide a valid xml document.

JSON Examples:

WEB-JSON: DELETE /goodsOutOrder

{
   "clientNumber": "DEFAULT",
   "orderNumber": "ORD_00001"
}

TCP-JSON:

"DeleteGoodsOutOrder": {
   "clientNumber": "DEFAULT",
   "orderNumber": "ORD_00001"
}

TCP-JSON Response:

"DeleteGoodsOutOrder_Response": {
  "httpResponseStatus": 200,
  "clientNumber": "DEFAULT",
  "orderNumber": "ORD_00001"
}

XML Examples:

WEB-XML: DELETE /goodsOutOrder

<DeleteGoodsOutOrder clientNumber="DEFAULT" orderNumber="UT-GO-00001" />

TCP-XML:

<DeleteGoodsOutOrder clientNumber="DEFAULT" orderNumber="UT-GO-00001" />

Response:

<DeleteGoodsOutOrder_Response clientNumber="DEFAULT" orderNumber="UT-GO-00001" httpResponseStatus="200"/>

For a further example see Example XML Message.

The base URL for the communication with KiSoft One for incoming messages is: /kisoft/oneapi/v1/

Incoming URL examples (KiSoft One is server):

• /kisoft/oneapi/v1/customer with html-method "PUT"
• /kisoft/oneapi/v1/goodsOutOrder with html-method "POST"
• /kisoft/oneapi/v1/relocationRequest/loadUnits with html-method "POST"

KiSoft One acts per default as server - and the higher-level system needs to establish permanent Websocket connections.

In order to provide response messages without the need for the higher level system to create a multitude of webhook endpoints a websocket connection is provided.

The websockets can be requested at the following paths:

• /kisoft/oneapi/v1/websocket/MovementData for all events regarding movement data
• /kisoft/oneapi/v1/websocket/StockChanges for all live stock changes
• /kisoft/oneapi/v1/websocket/Reports for requested reports and stock snapshots

It is only possible to create one socket connection per endpoint.

Since the websocket connection is no longer a http transport layer, modifications to the messages described in Using the Interface on Non-HTTP Transport Layers apply.

In order to detect connection loss during idle communication times, the heartbeat message is sent every 60 seconds if no other messages are sent during this period.

If the heartbeat or other messages are not acknowledged by the higher level system, the connection is terminated by KiSoft and a new connection has to be established by the higher level system.

Option: KiSoft One is Client for all Outgoing Reply Messages

If it is required, that the higher-level system acts as server and KiSoft One acts as client for all outgoing reply messages, which are marked with "EVENT", then the higher-level system needs to define the base URL warehouse specific. Knapp will add the reply path based on the message in cammelCase.

Outgoing URL example:

• https://10.89.17.1/one2host/oneapi/v1/goodsOutOrderReply

A flat sorter system consists of multiple different use cases depending on the deployed mode. For now Sort and Deliver is the first available mode within the flat sorter product. Different processing modes will be added in the future. Custom processing modes which are fitted to specific business can be implemented outside of the standard product.

The Sort and Deliver mode is one of the processing modes for a Flat Sorter. Sort and Deliver covers the essential needs for a typical goods-out processing. Loading units (e.g. a parcel or a carton) are pre-advised to the sorter and routed to their desired destination within the sorter once they arrive. A loading unit consists of only one item. No commissioning (order picking) takes place in this mode.

Transmit of order data including sortation process

Below diagram describes the basic process of transmitting a goods-out order to KiSoft including the followup sortation process. In the beginning the host system creates a goods out order. A goods out order consists of only one loadingUnit with a specific loadingUnitCode. The loadingUnitCode e.g. describes the optical identifyable barcode on the parcel/ carton. Destinations within the sorter are found based on the provided workCriteria that is both attached to the order and the destination (station).

Update station configuration

As described in above use case work stations must have a workCriteria assigned in order to receive orders matching the same criteria. In order to set the criteria for a given work station, the postWorkStationConfiguration message has to be sent. By sending this message the currently active criteria will be replaced. Loading units which are currently still on transport to the given work station will still be diverted to avoid non-matching trays circling.

Query all available work stations

A work station describes a dropoff/ divert/ chute within a flat sorter. Loading units will exit the sorter at this point. In order to query all work stations attached to the sorter, a PostRequestWorkStationStatus has to be sent without any content. This will cause the system to return all available work stations.

Configure a work station to receive anomaly items

Within a flat sorter it may happen that errors occur, like no read or no data items. In order to handle these special workCriteria can be assigned to work stations. In order to allow a station to receive no read items, assign SORTER_NO_READ to a work station. In addition to that SORTER_NO_DATA can be assigned for no data items. SORTER_CIRCULATION_REACHED might be assigned if items shall be diverted at a special work station when the number of allowed circulations is reached.

This section provides general supplementary messages.

The Sort and Deliver mode is one of the processing modes for a Flat Sorter. Sort and Deliver covers the essential needs for a typical goods-out processing. Loading units (e.g. a parcel or a carton) are pre-advised to the sorter and routed to their desired destination within the sorter once they arrive.

The following return codes can be sent to the higher level system:

Also the standard HTTP response status codes (e. g. 500) can be sent to the higher level system.

For further detail see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses.

The error numbers are built upon this schema:

• Severity (E):
  • Error
• System (AKO):
  • Knapp AG (A)
  • KiSoft One (KO)
• Module (XXXX):
  • General (GENR)
  • Masterdata (MAST)
  • Movementdata (MOVM)
  • Stock-Management (STOC)

The following error codes can be sent to the higher level system:

Example for message POST inboundDelivery:

<PostInboundDelivery clientNumber="DEFAULT" inboundDeliveryNumber="UT-INB-0001" priority="1" businessCase="GOODS_IN" supplierNumber="CUS_0000001">
  <VasTask taskReference="VASTASK01" workZone="DEC01" vasProcessingNote="vasProcessingNote 1" lineReference="Host-Reference-1" />
  <VasTask taskReference="VASTASK02" workZone="DEC01" vasProcessingNote="vasProcessingNote 2" lineReference="Host-Reference-1" />
  <AdditionalProperty key="PHARMACY_CODE" value="Pharmacia" />
  <AdditionalProperty key="USER_INSTRUCTION" value="validate the lot number" />
  <InboundDeliveryLine lineReference="Host-Reference-1" articleNumber="UT_ART_0000001" packSize="1" expectedQuantity="1" loadUnitCode="LOU_0000001" loadCarrier="SMALL" stockType="STANDARD" lotNumber="LOT1234567890" dateMark="2030-08-30" serialNumber="1234ABC" reservationCode="ORD_1234567" noteOnProcessing="handle with care" stockQuality="NEW">
    <StockLockReason>EXPIRED</StockLockReason>
    <StockLockReason>QS_REQUIRED</StockLockReason>
    <AdditionalProperty key="LINE_PROPERTY_HOST" value="value1" />
    <AdditionalProperty key="LINE_PROPERTY_SPECIAL" value="value2" />
  </InboundDeliveryLine>
  <InboundDeliveryLine lineReference="Host-Reference-2" articleNumber="UT_ART_0000002" packSize="1" expectedQuantity="999" loadUnitCode="LOU_0000002" loadCarrier="LARGE" stockType="STANDARD" lotNumber="LOT987654321" dateMark="2030-12-30" serialNumber="XYT_000000002" reservationCode="RESERVATION_CODE_02" noteOnProcessing="fragile" stockQuality="NEW" >
    <StockLockReason>HOST</StockLockReason>
    <StockLockReason>QS_REQUIRED</StockLockReason>
    <AdditionalProperty key="LINE_PROPERTY_HOST" value="Line2 value1" />
    <AdditionalProperty key="LINE_PROPERTY_SPECIAL" value="Line2 value2" />
  </InboundDeliveryLine>
</PostInboundDelivery>