• End Points
  • Using the SHARK WMS Cloud End Points
• Authentication and Security
  • Headers
• Typical Integration to an ERP/Host System
  • Level 1 - Basic Support for Picking by Orders
  • Level 2 - Get Confirmation back to the Host System
  • Level 3 - Add support for Inbound Orders
  • Level 4 - Add support for Stock Adjustment
• General Formatting
  • Date-Time
• Master Data
  • Packages
• Processing Orders
  • Inbound Orders
  • Outbound Orders (Picking)
    • Import Rules for Orders
  • Updating Outbound Orders
    • Partly Deliveries
  • Updating Purchase (put-away) Orders
  • Special Requirements
    • Auto processing of orders
    • Reserved Purchases
    • Incoming Inspection
    • Batch Number Registration
    • Serial Number Registration
• Outbound Orders (Picking)
  • Updating Pick Orders
  • Part List functionality
  • Order Processing without Confirmation
  • Order Processing using Webhooks
  • Order Processing using Polling
• Stock Taking Orders
• Reports
• WebHook
  • Order State
• Reference Documentation
• Tools for Testing

SHARK WMS supports integration to other systems, using a REST based web service API. It is used to provide an interface for external Host/ERP systems for on-line handling of orders and exchange of other information like article master data, inventorying requests, etc. Orders can be transferred from the Host system and SHARK may return an acknowledge back, when the order has been processed. Might also return stock adjustments, when the actually number of articles on stock does not fit with the expected count or when an order could not be fulfilled completely. In general, the purpose is, that SHARK and the host system can be used as one homogeneous system.

The reference documentation, for the latest version (1.2) can be found here

Previous versions:

• The reference documentation, for version 1.1.2

The REST API has some great advantages compares to exchanging information by files:

• It is fast, the order is created immediately in SHARK when it is sent by the Host.
• It is reliable. The Host get an immediately confirmation back if the order was created successfully as a status code and possible error message from the REST call.
• It works over the Internet and does not need any shared folders or ftp servers.

The return of confirmations and other asynchronous events, can be done in 3 ways:

• Using Webhooks. This is the preferred method, it requires no development in SHARK and has a low overhead and fast response. The user species an URL to call, when a certain event occurs. It requires the host is able to provide an URL for a web server.
• Using polling. Might be easier to implement in some systems, especially if the Host system does not have its own rest server. It requires more resources, since it has to ask at fixed intervals, if any confirmations are available.
• If the host system has a web service API itself, the confirmation can be done using that, but it requires implementation of the API in SHARK, typical done by a Groovy script.

It is also possible to work without acknowledge back, this might be OK for some setups.

The REST API is supported both for cloud based installations and on-prim (own server).

For the Cloud solution, use this URL: https://restapi.sharkwms.com/1.1/, a token is required for authentization. This can be obtained from the Shark PC client.

For on-premise installations, the URL depends on where the software is installed.

End Points

Using the SHARK WMS Cloud End Points

Authentication and Security

The REST API utilizes a token-based authentication system known as Bearer authentication.

Bearer authentication, also referred to as token authentication, is an HTTP authentication scheme that uses security tokens called bearer tokens. When accessing protected resources, the client must include this token in the Authorization header of the request using the following format: Authorization: Bearer .

The token is a JWT (JSON Web Token) and the signing algorithm being used is HMAC SHA-256. It is generated by using a Shark PC client.

For enhanced security, it is strongly recommended to use HTTPS (SSL) to encrypt the token during transmission. This ensures that the token remains secure and cannot be intercepted by unauthorized parties.

The token should be included in the request header within the Authorization field, as shown in the example below:

POST /1.0/order HTTP/1.1
accept: */*
Authorization: Bearer THISISMYTOKEN
Content-Type: application/json

The SHARK WMS cloud version supports only encrypted communication using either TLS 1.1 or TLS 1.2.

TLS 1.2 (Transport Layer Security 1.2) is a cryptographic protocol designed to provide secure communication over a computer network. It ensures privacy, data integrity, and authentication between the applications.

Headers

Required headers.

Typical Integration to an ERP/Host System

What is needed for a typical implementation? There is no standard answer and the integration can be simple or complex, depending on the requirements.

This is the proposed priority of integration phases. Only level 1 is required to have the basic functionality for a working system.

Level 1 - Basic Support for Picking by Orders

A minimum solution, for an integration that support picking of orders from the warehouse. At this level storing of goods is supposed to be done “manually”, without involving the Host System. Typical most of the time is spend picking, so this first level may be an easy way to get a lot of the benefits from an integration.

This is a one-way communication and requires a minimal of effort at the Host side.

Level 2 - Get Confirmation back to the Host System

For the simple integration, the Host had no ideas if the order actually was successfully carried out. The next step could be to add a confirmation for a picked order back to the host.

Level 3 - Add support for Inbound Orders

The next step, could be to integrate support for inbound orders. This does actually not require any new implemenation of end-points. The same post/order format is used, used with another order type parameter and perhaps some other fields.

Level 4 - Add support for Stock Adjustment

Telegram when the stock is changed without an order from the ERP system. This could be the result of a stock error that is adjusted by an operator or other operations that change the stock.

General Formatting

Date-Time

Date/time values are formatted as defined by RFC 3339, for example 2017-07-21T17:32:28Z.

Master Data

Master data is basic information about the articles. The most important information is the article number and description, but other information can be transferred as well. SHARK will create new articles and update the description, when met in an imported order, but the Master Data allows more information and will also work if SHARK is used with the Manual Transactions (transactions with no host-orders), this could be the case in an initial store process, where goods are moved from old locations into SHARK without orders.

Packages

Packages are using for handling different package sizes for the articles. It is optional information that can be specified with the article master data.

Processing Orders

This section shows the flow of information in different possible configurations.

Inbound Orders

The Host may send an order when inbound goods are expected. When the goods are received, it will be matched against the order. Typical reasons to receive goods are:

• Purchase orders.
• Returned goods from customers.
• Produced items from own production.
• Replenishment from other storage locations.

A minimum inbound order may have this body:

{
  "orderNumber": "MYORDERNUMBER01",
  "orderTypeID": 2,
  "orderline": [
    {
      "articleNumber": "1234567890",
      "qty": 1.0
    }
  ]
}

The OrderTypeID is 2, this defines it is an inbound order.

Basic2 flow of goods reception with acknowledgement back to the host for each received line

(1) The Host might send the inbound order as soon as possible (when it is created) or delayed until it is needed. It is also possible to make the actually registration in the Host System and then let the Host send an in-bound order with the actually received goods. This might end in a two step process, but can have other advantages.

Outbound Orders (Picking)

The Host sends orders to request goods to be picked. This can for example be sales orders to customers or production orders.

Confirmation back to the host can be:

• When the order is finalized and confirmed.
• When the order is picked completely (no confirmation).
• Line by line.

Import Rules for Orders

The following table shows the configuration parameters and how SHARK reacts in various situations when importing picking orders.

Updating Outbound Orders

Some times it might be required to update an existing pick order. This should be avoided if possible, but if not, here is the rules and behavior when it happens.

To start, it is important to understand the life-cycle of an order.

When an order is resend, with the same order number/delivery note number, it will replace the existing order and delete the previous order!

Partly Deliveries

Inbound orders are often partly delivered, this means that the expected quantity to be received must be registered at several times. To make the Host aware of the received goods, it can be practical to confirm by transactions, this means that the same order line can be confirmed several times.

Updating Purchase (put-away) Orders

It can be required to modify an already sent order. This is possible with the limitation, that when the first goods are registers on one order line, it can no longer be changed. When changing an order the whole order is send again.

Special Requirements

Some special requirements can optionally be supported like:

• Reservation of articles for a specific picking order.
• Inspection of incoming goods.
• Registration of batch/lot and serial numbers.

Auto processing of orders

For the order line, there is an “auto” flag that can be used to automatically process the order line immediately. It does also require the location field to be defined.

Reserved Purchases

A feature that support purchases reserved for a specific sales order.

Incoming Inspection

Used to flag purchases that must be inspected before they are released for picking.

When an order line with incoming goods are marked for inspection, it is decided at the reception time, if the articles are accepted or stored for inspection. In case all or some articles are stored for inspection, they will be put on a location where the stock is locked and cannot be picked with ordinary orders. The location is also marked with the incoming order number.

The Host can get a list of all items waiting for inspection using the GET /Inspection endpoint.

The Host can change the status of items waiting for inspection using the PUT /Inspection endpoint.

Batch Number Registration

The batch number of incoming goods must be registered. The batch number can be reported back to the Host.

Serial Number Registration

Serial numbers of incoming articles must be registered. The serial number can be reported back to the Host.

Outbound Orders (Picking)

The Host sends orders to request goods to be picked. This can for example be sales orders to customers or production orders.

Confirmation back to the host can be:

• When the order is finalized and confirmed.
• When the order is picked completely (no confirmation).
• Line by line.

Updating Pick Orders

Some times it might be required to update an existing pick order. This should be avoided if possible, but if not, here is the rules and behavior when it happens.

To start, it is important to understand the life-cycle of an order.

When an order is resend, with the same order number/delivery note number, it will replace the existing order and delete the previous order!

Part List functionality

SHARK supports creation of parts list from a master order. This feature allows a single order line to be broken down into multiple picks of different articles and thereby supporting a setup where the articles stored in the warehouse are sub components of a structure. The part list is supplied with each order from the host and is not stored in SHARK, this means all maintenance of the part list is done in the Host system.

Each order line that contains a part list will create a separate sub-order. The sub order with the part list has to be picked before the master order and must be stored on a location first. This is useful if picking the part list also involves some small production, like for example assembly of the parts or just packing of the product.

In the master order, the part list will be seen as an article with the name:

<master order number>.<part list number>.<master order orderline linenumber>

This means the picked part list order will be stored with a unique article number, to ensure it goes to the correct master order.

The Master Order will have a back order status, until all part lists in the order have been picked.

Order Processing without Confirmation

This is the flow if information, when the integration has no acknowledge back. This is by far the most simple way to make an integration.

Order Processing using Webhooks

This is the flow if information, when the integration is based on webhooks.

Order Processing using Polling

This flow is an example of how a polling based integration can be made.

Stock Taking Orders

A stock taking order can be created as any other order, just use OrderTypeID=19.

The only parameters that are used are order number, article number, batch number and owner. The rest is ignored.

After the order is executed (counted), it will be acknowledge in the usual order acknowledge format, with the original order number and OrderTypeID=19. The following fields have special meaning:

The quantity is always the total stock quantity for this article and not only the specific counted location. Thereby the Host System does not have to care about articles stored on multiple locations.

Example that will create an inventory order “INV004”, requesting a count of two articles.

{
  "orderNumber": "INV004",
  "orderTypeID": 19,
  "orderline": [
    {
      "articleNumber": "67547"
    },
    {
      "articleNumber": "20087"      
    }
  ]
}

Reports

The integration allows reports defined in the database to be returned. There are standard reports and it is also possible to have user defined reports.

Data is returned as json and is compatible with Excel, thereby it is possible to use it for extraction of data, directly into Excel.

Step 1 - Open the Connection Dialog for the data source.

Step 2 - Enter the required connection information.

Enter the URL, it is

• https://restapi.sharkwms.com/1.1/report?reportName=.*
• Add a new header “Authorization”.
• Add the value for Authorization, it is “Bearer + ". The token is a unique token for your installation.
• Remember to press Add header, when the info is entered.
• Press OK

Step 3 - Select the data, using the Power Query Editor

When the connection is entered successfully, Excel will fetch the data and open the Power Query Editor.

Do the following steps:

Select and right-click the data-List and Drill Down the data (get rid of the metadata)

Select List, right-click and convert the list to a table

This will ask for delimiters, use the default “None” and press OK

Then unpack the columns by pressing the small icon in the column, choose the default “all” or select specific columns

The selecteddata is now visible

Save the Excel sheet for later use. Press refresh to update the data.

WebHook

Webhooks are user defined web callbacks using HTTP POST.

SHARK supports webhooks to notify to an external system, when certain events occurs. These events are typical when SHARK has data ready to be read by the external system. The big advantage is that polling thereby can be avoided.

The body of the webhook is a json data structure with all the required information.

In version 1.1, this structure for an order confirmation looks like this:

{
  "nextID": 0,
  "documentID": 0,
  "status": "string",
  "orderTypeID": 0,
  "orderNumber": "string",
  "deliveryDate": "2019-08-24T14:15:22Z",
  "owner": "string",
  "deliverNoteNumber": "string",
  "carrier": "string",
  "weight": "string",
  "colli": "string",
  "misc": {
    "misc1": "string",
    "misc2": "string",
    "misc3": "string",
    "misc4": "string",
    "misc5": "string",
    "misc6": "string",
    "misc7": "string",
    "misc8": "string",
    "misc9": "string",
    "misc10": "string"
  },
  "orderline": [
    {
      "status": "string",
      "lineNumber": 0,
      "articleNumber": "string",
      "qtyOrdered": 0,
      "qty": 0,
      "costCenter": "string",
      "costCenterText": "string",
      "user": "string",
      "time": "2019-08-24T14:15:22Z",
      "misc": [
      ],
      "serialNumbers": [
      ],
      "transactions": [
      ]
    }
  ],
  "partlist": [
    {
      "partListNumber": "string",
      "orderTypeID": 1,
      "lines": [
      ]
    }
  ]
}

Order State

It is possible to get a post on a webhook when an order change it state.

Possible Inbound Order States:

Possible Outbound Order States:

Reference Documentation

The API reference documentation is found here:

Reference documentation

The documentation is made using Swagger. It support generation of example codes and source code generations for some languages.

Reference documentation at Swagger

Note that most of the parameters in the REST calls are optional and you should skip them if not needed. If they are included either with default content or empty, they will be used and is and sometimes with unexpected results.

Client source code can also be generated by tools from the OpenAPIproject. Download the json OpenAPI specification for the SHARK API and use the tools for making code templates.

Tools for Testing

You can test the REST API with different tools.

For Windows and Mac postman is a great tool. You can download it from [https://www.getpostman.com]

From the command line curl can be used. Download curl from [https://curl.haxx.se].

To make a GET request using curl:

curl curl https://localhost/api/1.0/article -k -H "Accept: application/json" -H "Authorization: Bearer <token>"

localhost must be replaced by the url to the serer.

-k is used if the certificate is not generated by an certicate provider known to curl.