# External API access

# Introduction

For external access to your TrackOnline data you can use the external REST Api. Access/authentication is done with an API key. The REST API is accessible via the following website.

This production site stores the data that it receives.

# Generate an API Key

Before you can get access to the external api you will have to generate an API key in your TrackOnline environment.

1. Open the cogwheel menu, and navigate to administration settings.
2. Navigate to API setting option.
3. Give your API key a name and press create.

This generated API key can be used in the header of the request, or in the querystring.

# Example with curl and a query string:

curl -X GET "https://api.trackonline.com/api/v1/iot/item?includeDeleted=false&page=1&apikey=xxx.xxxx.xxx" -H "accept: application/json"

# Example with curl and a header:

curl -X GET "https://api.trackonline.com/api/v1/iot/item?includeDeleted=false&page=1" -H "accept: application/json" -H "X-ApiKey: xxxx.xxxx.xxx"

# API rate limits

The rate limits below will limit the number of requests that your app is permitted to send during a time window. These limits are depending on your license type.

1. START and PRO
   • Minutely limit: your app can make 60 API calls, per administration, per minute.
   • Daily limit: your app can make 1000 API calls, per administration, per day.
2. PRO PLUS
   • Minutely limit: your app can make 60 API calls, per administration, per minute.
   • Daily limit: your app can make 5000 API calls, per administration, per day.
3. ENTERPRISE
   • Minutely limit: your app can make 1000 API calls, per administration, per minute.
   • Daily limit: your app can make 10000 API calls, per administration, per day.

If your app exceeds this limit, you will receive a response with HTTP status code 429 for every request. This response will also include the Retry-After header, which indicates how long your app should wait before making a follow-up request.

# Available API calls

For GET among others the following calls are available per category in the API:

1. Status
   • GET API status
2. IoT
   • GET IoT item(s)
   • GET IoT item measurement(s)
3. Item definition
   • GET item definition(s)
   • GET result of saved item definition(s)
4. Item configuration
   • GET item configuration(s)
   • GET result of saved item configuration(s)
5. Unique item
   • GET unique item(s)
   • GET result of saved unique item(s)
6. Location
   • GET location(s)
   • GET result of savedlLocation(s)
7. Transaction
   • GET transaction(s)
   • GET result of saved transaction(s)
8. Balance
   • GET balance(s)
   • GET counterpart balance(s)
9. Batch calculation
   • GET batch calculation(s)
   • GET a download file of the batch calculation result
   • GET document(s) for batch calculation(s)
   • GET a download file of a batch calculation result document

For POST among others the following calls are available per category in the API:

1. Item definition
   • POST item definition(s)
2. Item configuration
   • POST item configuration(s)
3. Unique item
   • POST unique item(s)
4. Location
   • POST location(s)
5. Transaction
   • POST transaction(s)

# Item definition

The data model for the item definition GET or POST calls consists of the following (marked with * are required fields):

# GET parameters

The GET parameters are the parameters you can pass in to filter the item definitions when fetching item definitions. An example is available in the next section.

# Example calls

In this example we are going to make a POST of an item definition for the CC TAG5 load carrier with only the mandatory info.

[
  {
    "number": "CC TAG5",
    "name": "CC TAG 5",
    "code": "TAG5",
    "type": "LoadCarrier"
  }
]

In this example we are going to make a POST of an item definition for the CC TAG5 load carrier including measurements and the weight.

[
  {
    "number": "CC TAG5",
    "name": "CC TAG 5",
    "code": "TAG5",
    "type": "LoadCarrier",
    "basePrice": 250,
    "length": 1.4,
    "width": 0.6,
    "height": 2.0,
    "weight": 50
  }
]

When fetching your item definitions, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the item definitions with "box" in their name:

https://api.trackonline.com/api/v1/itemdefinition?Name=box&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on. Now if you want to filter item definitions with "box" in their name AND with the number 10, this is what the URL looks like:

https://api.trackonline.com/api/v1/itemdefinition?Number=10&Name=box&page=1&apikey=xxx

# Item configuration

The data model for the item configuration GET or POST calls consists of the following (marked with * are required fields):

itemDefinitionId* - See item definition data model for reference.

name - Gets the name of an item definition

number - Gets the number of an item definition

type - Gets the type of an item definition

position - Gets or sets the position of a members

maximumBalance - Gets or sets the maximum balance of a member

minimumBalance - Gets or sets the minimum balance of a member

minimumStockCollection - Gets or sets the minimum stock collection of a member

maximumFlowIn - Gets or sets the maximum flow in of a member

minimumFlowIn"- Gets or sets the minimum flow in of a member

maximumFlowOut - Gets or sets the maximum flow out of a member

minimumFlowOut - Gets or sets the minimum flow out of a member

contractCycleTime - Gets or sets the contractCycleTime of a member

leadTime - Gets or sets the leadTime of a member

activeFrom - Gets or sets the activeFrom date(Default: Today)

activeTo - Gets or sets the activeTo date (always )

Note: name, number and type are not used for saving

# GET parameters

The GET parameters are the parameters you can pass in to filter the item configurations while fetching item configurations. An example is available in the next section.

# Example calls

In this example we are going to make a POST of an item configuration using item definition "ID123" with only the mandatory info.

[
  {
    "name": "Config123",
    "members": [
        {
          "itemDefinitionId": "A7B8AF3F-4C16-492E-A3B7-451E8E096D30",
          "number": "ID123"
        }
      ]
  }
]

In this example we are going to make a POST of an item configuration for the Config123 including members information.

[
  {
    "name": "Config123",
    "members": [
      {
        "itemDefinitionId": "A7B8AF3F-4C16-492E-A3B7-451E8E096D30",
        "name": "ID_123",
        "number": "ID123",
        "type": 0,
        "position": 1,
        "maximumBalance": 60,
        "minimumBalance": 15,
        "minimumStockCollection": 10,
        "maximumFlowIn": 30,
        "minimumFlowIn": 1,
        "maximumFlowOut": 50,
        "minimumFlowOut": 2,
        "contractCycleTime": 3,
        "leadTime": 2,
        "activeFrom":"2022-01-01T00:00:00.0000000+00:00",
        "activeTo":"2022-02-01T00:00:00.0000000+00:00"
      }
    ]
  }
]

When fetching your item configurations, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the item configuration with "Config123" in their name:

https://api.trackonline.com/api/v1/itemconfiguration?Name=Config123&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on. Now if you want to filter item configuration with "Config123" in their name AND with the Id "B7B8AF3F-5C16-492E-A3B9-452E8E096D31", this is what the URL looks like:

https://api.trackonline.com/api/v1/itemconfiguration?Number=B7B8AF3F-5C16-492E-A3B9-452E8E096D31&Name=Config123&page=1&apikey=xxx

# Unique item

The data model for the unique item GET or POST calls consists of the following (marked with * are required fields):

# GET parameters

The GET parameters are the parameters you can pass in to filter the unique items when fetching unique items. An example is available in the next section.

# Example calls

In this example we are going to make a POST of an unique item for item definition CC TAG5.

[
  {
    "number": "123",
    "barcode": "bc123",
    "itemDefinition": {
      "number": "CC TAG5"
    },
    "deviceIds": {
      "deviceId": "d123"
    }
  }
]

When fetching your unique items, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the unique item with number "123":

https://api.trackonline.com/api/v1/uniqueitem?ItemNumber=123&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on.

# Location

The data model for the location GET or POST calls consists of the following (marked with * are required fields):

# GET parameters

The GET parameters are the parameters you can pass in to filter the locations when fetching them. An example is available in the next section.

# Example calls

In this example we are going to make a POST of a new location called From Location with only the mandatory info.

[
  {
    "number": "123",
    "name": "From Location",
    "type": "CompanyLocation"
  }
]

In this example we are going to make a POST of a new location called From Location with some additional info.

[
  {
    "number": "456",
    "name": "To Location",
    "nameShort": "ToLoc",
    "type": "Customer",
    "addressLine": "123 Customer street",
    "postalCode": "12345",
    "city": "Customerville",
    "stateOrProvince": "CUS",
    "country": "Customerland",
    "emailAddress": "info@customer.com",
    "languageId": "English",
    "balanceOperationMode": "NoRestriction",
    "tags": ["Customer", "CUS", "Customerville"]
  }
]

When fetching your locations, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the locations with hierarchy level 1 AND a name or shortname containing "customer"0:

https://api.trackonline.com/api/v1/location?HierarchyLevels=1&Name=customer&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on.

# Packaging Label

The data model for the packaging label GET or POST calls consists of the following (marked with * are required fields):

# GET parameters

The GET parameters are the parameters you can pass in to filter the packaging labels when fetching them. An example is available in the next section.

# Example calls

In this example we are going to make a POST of a packaging label with number PL0123456789 for type Sscc and expiration on 25-01-2028 with only the mandatory info. This packaging label DOESN'T have any non-serialized and serialized items.

[
  {
    "number": "PL0123456789",
    "expirationOn": "2028-01-25T00:00:00.000Z",
    "type": "Sscc"
  }
]

In this example we are going to make a POST of a packaging label with number PL9876543210 for type Sscc and expiration on 26-03-2028, including non-serialized and serialized items. This packaging label includes 25 items of item definition 'CC Tag5' (non-serialized items) AND 2 unique items 'UI01' and 'UI02' (serialized items).

[
  {
    "number": "PL9876543210",
    "expirationOn": "2028-03-26T00:00:00.000Z",
    "type": "Sscc",
    "packagingNonSerializedItems": [
      {
        "itemDefinition": {
          "number": "CC TAG5",
          "name": "CC TAG5",
          "code": "TAG5",
          "type": "LoadCarrier"
        },
        "quantity": "25"
      }
    ],
    "packagingSerializedItems": [
      {
        "item": {
          "number": "UI01",
          "barcode": "123456",
          "itemDefinition": {
            "number": "CC TAG5",
            "name": "CC TAG5",
            "code": "TAG5",
            "type": "LoadCarrier"
          }
        },
        "item": {
          "number": "UI02",
          "barcode": "789012",
          "itemDefinition": {
            "number": "CC TAG5",
            "name": "CC TAG5",
            "code": "TAG5",
            "type": "LoadCarrier"
          }
        }
      }
    ]
  }
]

When fetching your packaging labels, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the packaging labels with the letters "PL" in the number:

https://api.trackonline.com/api/v1/packaginglabel?Number=PL&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on. Now if you want to filter packaging labels with the letters "PL" in the number AND of type "SScc" (typecode = 1) AND include the inactive (disabled) packaging labels, this is what the URL looks like:

https://api.trackonline.com/api/v1/packaginglabel?Number=PL&TypeCodes=1&IncludeInactive=true&page=1&apikey=xxx

# Transaction

The data model for the transaction GET or POST calls consists of the following:

# GET parameters

The GET parameters are the parameters you can pass in to filter the transactions when fetching them. An example is available in the next section.

# Example calls

In this example we are going to make a POST of a transaction from “From Location” to “To Location” containing 25 pieces of the CC TAG5 load carrier. This is an example without unique items.

[
  {
    "statusCode": 0,
    "typeCode": 60,
    "transactionNumber": "1234567890",
    "fromLocation": {
      "number": "123",
      "name": "From Location",
      "type": "Customer"
    },
    "toLocation": {
      "number": "456",
      "name": "To Location",
      "type": "Customer",
      "tags": []
    },
    "dateTransaction": "2020-01-01T00:00:00.000Z",
    "dateTransactionCounterpart": "2020-01-01T00:00:00.000Z",
    "transactionItems": [
      {
        "itemDefinition": {
          "number": "CC TAG5",
          "name": "CC TAG5",
          "code": "TAG5",
          "type": "LoadCarrier"
        },
        "quantity": "25"
      }
    ]
  }
]

In this example we are going to make a POST of a transaction from “From Location” to “To Location” containing 3 unique items that are containing a barcode.

[
  {
    "statusCode": 35,
    "typeCode": 15,
    "transactionNumber": "1234567890",
    "fromLocation": {
      "number": "123",
      "name": "From Location"
    },
    "toLocation": {
      "number": "456",
      "name": "To Location"
    },
    "dateTransaction": "2020-01-01T00:00:00.0000000+00:00",
    "scannedItems": [
      {
        "type": "BarCode",
        "code": "0000001"
      },
      {
        "type": "BarCode",
        "code": "0000002"
      },
      {
        "type": "BarCode",
        "code": "0000003"
      }
    ]
  }
]

When fetching your transactions, you can also use the parameters explained in the section GET parameters to filter. For example, this is the URL for fetching the first page of results corresponding to the transactions created between the 1st and the 31st of May with the carriers 001 or 002:

https://api.trackonline.com/api/v1/transaction?CreatedDateFrom=2020-05-01T00%3A00%3A00.000Z&CreatedDateTo=2020-05-31T23%3A59%3A59.000Z&Carriers=001&Carriers=002&page=1&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on.

# Transaction Trip

You can set a trip to the next status. Therefor you need to send the entityguid of the trip you would like to set to the next status. A trip in the status new is set to the status in progress. A trip in the status in progress is set to the status processed.

Below an example call is shown.

# Example call

In this example we are going to set the status of trip with guid (id) A7B8AF3F-4C16-492E-A3B7-451E8E096D30 to the next status.

[
  {
    "id": "A7B8AF3F-4C16-492E-A3B7-451E8E096D30"
  }
]

# IoT device

# GET IoT Device

The data model for the IoT GET call consists of the following:

# GET IoT Device history

Furthermore, it is possible to fetch the history of locations for an IoT device as explained below. The GET parameters are the parameters you can pass in to filter the transactions when fetching them. An example is available in the next section.

# Example calls

Let's say you need to find the IoT devices attached to items with item definition ID b2ccd1e4-e30f-4473-862f-28eb69238f65. This is how the URL looks like.

https://api.trackonline.com/api/v1/iot/item?itemDefinitionId=b2ccd1e4-e30f-4473-862f-28eb69238f65&page=1&apikey=xxx

Now, if you want to views the history of one specific IoT device, let's say 00EDBED7, you can do the following:

https://api.trackonline.com/api/v1/iot/item/measurement?deviceId=00EDBED7&apikey=xxx

Of course, you can add as many parameters as you want in the URL. Therefor, add &filter=value in the URL where filter is the name of the filter and value is the value you want to filter on.

# Balance

You can either get the regular balance of a location or the balance by counterpart whether you specify a counterpart or not. The data model for the balance GET calls consists of the following:

# Example calls

This first example is for fetching the balance for locations A and B, excluding ongoing transactions and empty balances:

https://api.trackonline.com/api/v1/balance?locations=A&locations=B&onlyProcessed=true&excludeZeroBalance=true&apikey=xxx

Now let's imagine you don't want the balance that you have with A and B but rather the balance that A has with B. Therefor, you need to use the URL /api/v1/balance/counterpart like this:

https://api.trackonline.com/api/v1/balance/counterpart?location=A&counterparts=B&onlyProcessed=true&excludeZeroBalance=true&apikey=xxx

# Batch calculation

# GET Batch calculation(s)

To get a filtered list of batch calculations, the following parameters can be used:

# GET Download batch calculation result

Furthermore, it is possible to download the complete batch calculation result.

# GET Document(s) for batch calculation(s)

To get a filtered list of batch calculation documents, the following parameters can be used:

# GET Download batch calculation result document

Furthermore, it is possible to download a single batch calculation result document.

# API responses

Below are the possible responses for the calls above.

If you need further data such as specific models that are not explained above, please refer to the following section.

# Online API documentation

For online documentation of the different methods that can be used visit the following link: Online API documentationopen in new window

In the online API documentation you can use your API key to authorize your request by pressing the authorize button and enter your API key string.

Extra information about the parameters and models of the methods can also be found on this page. In the example below we explain where you can find this information.

# Information about methods and parameters

First click on one of the methods. In this example we click on the POST Method of the 'item definition' controller. See the image below.

# POST method of the item definition controller

This opens the POST method. Now you can see the name and description of the parameters and the responses.

Second, to see the description of each parameter, click on Model (next to 'Example value') as shown in the image below.

# Model of the item defintion controller

Third click on one of the model links. In this case only one link is shown, the ItemDefinitionDto link. See the image below.

# Model link

The link unfolds and all the parameters of the model are now shown. In the column 'The item definition', you can find a description of each parameter. Also the type, maximum and minimum and more details are described here.

# Parameter names and descriptions