Shipments v3 (BETA)

Sitoo Shipments API is used for tracking shipments and moving inventory to and from stores. It is recommended to read the Sitoo API introduction before reading this document.

What's new in version 3

• Enforces shipment state flows to allow for a more defined way of working with shipments. Also gives a more precise use of event callbacks
• Allows receiving items in batches, which helps to partially move items into stock in the stores while the shipment is open
• Handles serial- and batch numbers for shipment items
• Integration with Sitoo Warehouse, performing warehouse transactions for specific actions
• Changes to shipments are always done using actions. The list of actions that have been performed can be retrieved for each shipment
• Monetary values are handled using the integer data type, representing 1/100th of the value. E.g. $123.50 = 12350

API Base URL

The shipment service is available at the base URL https://shipments.sitooapis.com/v3. To access the API you combine the base URL and the endpoint URL. Example for adding a new shipment:

POST https://shipments.sitooapis.com/v3/shipments

Authentication

Authentication is done with the HTTP basic authentication mechanism over a secure connection. The API ID and password can be found in the Backoffice under settings/Sitoo REST API (Requires administrator privileges).

Using the API ID and password, add an extra header to the request for authentication:

"Authorization: Basic " + base64_encode("{API ID}" + ":" + "{password}");

Example header (API ID "10020-140" and password "buNxoOx2o5kM2JMc3VhBX20k4Gik4qKXyKfg332A"):

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)

Data Types

Boolean

Boolean values are represented as either true or false, all other values are not considered boolean values.

Example for query parameter

https://shipments.sitooapis.com/v3/shipments?include_packages=true

Terms

• A shipment is the base object that contains one or more packages
• A package contains in itself one or more items
• An item is an entity with a quantity, name and sku.
• A parameter that is read-only is only part of the response of the API. If it is required and read-only then it is always part of the response.

Shipment States & Actions

A shipment is always in one of the states listed below. To progress the state of a shipment, you use actions. Each time an action is applied to a shipment the version of the shipment is incremented. Each action tracks to which version of the shipment it was applied to. All the actions are stored for the shipment object and can be retrieved and used as a log for the shipment history. All actions that are applied to a shipment must send in the last seen version of the shipment to assure that the client has the latest version. If attempting to perform an action on an outdated version of the shipment, an HTTP response code of 412 will be returned.

Shipment States

Shipment Actions

Sitoo Warehouse Integration

If either the warehouse origin or destination IDs are set, then the following types of actions will integrate with the warehouse.

• Remove stock - When shipment is in state new, the action remove-stock will result in transition to state packed and a warehouse transaction if a warehouse ID is specified in the action object.
• Add Received Items - Adding received items will result in a warehouse transaction where the items are transferred into a warehouse if the warehouse_id property of the ShipmentReceivedItems object is set.
• Add Received Items Undeclared - Adding undeclared received items will result in a warehouse transaction where the items are transferred into a warehouse if the warehouse_id property of the ShipmentReceivedItemsNotDelivered object is set.
• Set State Cancelled - When cancelling a shipment, any previous warehouse transactions performed by this shipment will be reverted.

Events

To use events for integration with the shipment service see the SPI Events documentation. Register the shipment-v3 event type to receive the events for a shipment. The object sent for a shipment event is the ShipmentV3Data object type that is described in the SPI Events documentation.

Errors

When receiving a response code that is not in the 200 range, most shipment endpoints will return an error message. It contains an error code, a request ID and an error data object with one or more key-values that describes the error. The object returned will look like this:

{
  "error_code": "version-invalid",
  "error_data": {
    "message": "Wrong shipment version, current version is 1 but got 2"
  },
  "request_id": "1e42b374-67d6-49b9-af19-48116aa36363"
}

{
  "error_code": "field-type",
  "error_data": {
    "field": "info.origin_warehouse_id",
    "message": "Wrong type string for value '1' on field 'info.origin_warehouse_id' expected type int64"
  },
  "request_id": "1f238fde-a4a1-411a-8d9a-825038b5e6f4"
}

Use cases

Update package with barcode

Update barcode on a package with package_id 0ba7de5f-a109-450a-9106-a056317a7be8 in shipment with shipment_id 123

POST https://shipment.sitooapis.com/v3/shipments/123/actions

{
  "created_by": "john",
  "version": 1,
  "action": "update-package",
  "package_id": "0ba7de5f-a109-450a-9106-a056317a7be8",
  "package": {
    "barcode": "111"
  }
}