Skip to content

REST API#

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 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#

REST API Version End Point
1.1 https://restapi.sharkwms.com/1.1
1.2 https://restapi.sharkwms.com/1.2

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 for the HTTP request.

Key Value
Authorization Bearer
Content-Type application/json

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.

Implement Notes
post/article Article Master Data is sendt from the ERP system to SHARK.
It includes article number, description and perhaps EAN code. The inbound order can also include article description and new articles are automatically created in SHARK when an inbound order is received with a new article and the Article Master Data telegram could be skipped if very little master data is required.
post/order To create an outbound order from the systemm (picking).

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.

Implement Notes
get/confirm Get confirmation back about processed orders and
transactions that effect the warehouse stock.
The simplest way is to use polling.

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#

The formatting follows the JSON standard.

Date-Time#

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

Float Numbers#

Float numbers are formatted as a string with a dot as the decimal separator, for example 123.45.

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
    }
  ]
}

OrderTypeID 2 indicates an inbound order.

sequenceDiagram
    participant HOST
    participant SHARK
    actor Operator
    HOST ->> SHARK: Inbound Order (1)
    HOST -->> SHARK: Possible order updates
    Operator ->> SHARK: Open the order
    Operator ->> SHARK: Receive one order line
    Note right of Operator: The goods are registers for put-away.<br>It is not any longer allowed to update the order line.
    Operator ->> SHARK: Store the received goods on a location
    SHARK -->> HOST: Confirm put-away on the specified orderline

Flow of goods reception with acknowledgment 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.

Parameter Value Note
AutoCreateItem True If true, unknown articles will be created when needed.
CancelOrderLinesWithoutStock True If true the stock must be present else the orderline will be deleted.
ItemNumberUnique True The same article number must only appear once per order.
ConfirmPickPerLine True Acknowledge generated immediately for each pick line.
ConfirmPutPerLine True Acknowledge is generated immediately for each put-away line.
LinkDeleteZeroLines True If a line is received with a 0 count, it will be deleted. Used to cancel lines existing orders.
ReleaseOrderMode Auto Orders must be released before they can be picked. Auto mode will release the order immediately when received.
ReplaceOrders True If the same order is received 2 or more times, the order will replace the previous one. If false the lines will be appended.

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!

Order State    Result
Not released/not started  The old order will be deleted and a new created.
Not released/partly picked The old order will be deleted and a new created.
Released The order update will fail and rejected. Recall the order first.
OK (finished) The old order will be deleted and a new created.

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!

Order State    Result
Not released/not started  The old order will be deleted and a new created.
Not released/partly picked The old order will be deleted and a new created.
Released The order update will fail and rejected. Recall the order first.
OK (finished) The old order will be deleted and a new created.

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:

Field Type Description
QtyOrdered Float This is the expected stock quantity.
Qty Float Actually counted quantity. If the article is not on stock, it cannot be counted and Qty will be 0

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:

State Can be modified Notes
DONE No The order is received and stored completely.
ERROR Yes Something went wrong.
PARTLY No The order has been received partly and stored.
READY Yes The inbound order is created, no goods have have been received. The order can be modified by the host.
WORKING No Some goods have been received, but not yet stored on a storage location.

Possible Outbound Order States:

State Can be modified Notes
BACKORDER Yes The order cannot been picked, because not all stock is available.
CONSOLIDATED No The order is consolidated (packed) and shipped.
DONE No The order is picked, not yet consolidated/shipped.
ERROR Yes Something went wrong.
READY Yes The outbound order is created, the order is idle and nothing has been done yet. The order can be modified by the host.
RECALLED Yes The order has been released, but is recalled (unrelased). It can now be modified by the Host System.
RELEASED No The order is released and has allocated stock. Ready for picking to start.
WORKING No The order is being picked.

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.