Device registration APIs

Consumers use the Device Manager API to register a device with TraceLink and authorize communication with TraceLink applications.

Smart Inventory Tracker registers devices by capturing information related to one or more devices through the REST API and responds with an environment URL that must be installed on each device to enable secure connections to the TraceLink Track & Trace Services. Devices must be registered with TraceLink before Smart Inventory Tracker can be installed on them.

This process is only required for Consumers who choose to use Smart Inventory Tracker to verify product.

Device Manager (REST)

Administrators for the company that owns Smart Inventory Tracker use this message to provide information for devices that need authentication. Administrators can also update data attributes and configuration details for previously authenticated devices or delete device information.

The response returns the list of devices successfully registered or updated, or errors indicating why the device could not be authenticated. The authentication certificates must then be installed on each device. Download the Smart Inventory Tracker Installation Qualification Document for more information.

Use a POST request to the URL for the desired environment:

  • itest: itestmsapi.us1.tracelink.com/etapi/basic/itest/devmgr/device-management/manage

  • prod: msapi.us1.tracelink.com/etapi/basic/prod/devmgr/device-management/manage

Guidelines

Element Type

Update

 Description
deviceInformationList List Begin – Required. The list of devices that require authentication certificates.
The request must contain a maximum of 40 devices.
  deviceInformation Section Begin – Required. The information about each device.
    deviceName String Yes Required. The name of the device. Must be unique across all names defined for a single locationId.
    deviceUniqueIdentifier String No Required. The Machine (e.g. MAC) address for the device. Must be 6 sets of 2 characters separated by colons or hyphens (e.g. 00:23:68:CF:A4:D8 or 00-23-68-CF-A4-D8). Acceptable characters are numbers 0-9 and letters A-F.
    deviceType Enum No Required. The type of device. Valid values:
  • Handheld
  • SmartPhone
    deviceMake Enum No Required. The brand of the device. Valid values:
  • Zebra (Only allowed if the deviceType is Handheld.)
  • Honeywell (Only allowed if the deviceType is Handheld.)
  • Google (Only allowed if the deviceType is SmartPhone.)
  • Samsung (Only allowed if the deviceType is SmartPhone.)
    deviceModel Enum No Required. The model of the device. Valid values:
  • MC3300 (Only allowed if the deviceMake is Zebra.)
  • TC70x (Only allowed if the deviceMake is Zebra.)
  • TC51 (Only allowed if the deviceMake is Zebra.)
  • TC52 (Only allowed if the deviceMake is Zebra.)
  • CN80L1N (Only allowed if the deviceMake is Honeywell.)
  • Pixel2 (Only allowed if the deviceMake is Google.)
  • GalaxyS9 (Only allowed if the deviceMake is Samsung.)
    action Enum – Required. The action that the Device Manager must take with the specified deviceUniqueIdentifier. Valid values: :
  • add – Register a new device, and add the new device information.
  • update – Update the device information for an existing device.
  • delete – Delete all information stored for an existing device.
    companyExternalId String Yes Required. The External ID for the company registering the device. Must match a valid company in the Track & Trace Services. Contact TraceLink Support or the company's TraceLink Technical Consultant for the External ID.
    locationId String Yes Required. The identifier value for the device's specific location. Must match a valid location in the Track & Trace Services.
    locationType Enum Yes

Required. The identifier type for the device's specific location.

  • COMPANYID
  • COMPANYSITEID
  • DEA
  • DUNS
  • DUNSPLUS4
  • GCP
  • GLN
  • HIN
  • SGLN
    countryCode String Yes Conditionally required if the serialNumberEventManager is SEM, defaultSOM, or defaultSEM.

The default market for reporting serial numbers to. Must be an ISO Alpha 2-digit code.
    environment Enum Yes Required. The US Saleable Returns environment that the device must be authenticated within.Valid values:
  • beta
  • itest
  • production
If a device updates to a different environment, the authentication certificates must be retrieved from the response and installed on the device again.
    port Enum Yes The firewall port that the individual device uses to communicate with the TraceLink Track & Trace Services. Valid values:
  • 8883 – The standard port that the device uses to communicate with the TraceLink .
  • 443 – Devices can use this port to communicate with the TraceLink Track & Trace Services if the company blocks port 8883.

If a device is currently registered with 8883 as the port element, the company must keep their 8883 firewall port open until the device is successfully updated to the 443 port.

If the port element is not present, the device defaults to 8883.
    serialNumberEventManager Enum Yes Required. The serial number event manager that Smart Inventory Tracker integrates with. Valid values:
  • SOM – The device can integrate with Serialized Operations Manager only.
  • SEM – The device can integrate with Smart Event Manager only.
  • defaultSOM – The device can integrate with Serialized Operations Manager or Smart Event Manager, and Serialized Operations Manager is the default integration when logging in.
  • defaultSEM – The device can integrate with Serialized Operations Manager or Smart Event Manager, and Smart Event Manager is the default integration when logging in.
    active Boolean Yes Required. Indicates whether the device can be used. Valid values:
  • true – Users can log in to Smart Inventory Tracker on the device.
  • false – Users cannot log in to Smart Inventory Tracker on the device. Users that attempt to log in will receive an error.

Body Example

{"deviceInformationList":
[{"deviceName": "HH_QE_OMICRON-C5",
	"deviceType": "Handheld",
	"deviceMake": "Zebra",
	"deviceModel": "MC3300",
	"action": "add",
	"deviceUniqueIdentifier": "94:FB:29:29:0C:C5",
	"companyExternalId": "kendallpharm",
	"locationId": "WOBURN-326",
	"locationType": "COMPANYSITEID",
	"countryCode": "US,
	"environment": "itest",
	"port": "8883",
	"serialNumberEventManager": "defaultSEM",
	"active": "true"
}]}

Errors

Errors display in the Device Manager response. Only the specified device fails authentication, not the entire list.

Element Error Description
username User is not authorized to access this resource with an explicit deny The username is not present, or the username and password pairing cannot be authenticated.
user [username] does not have the Devices permission The username can be authenticated, but the user is not an Administrator for the company where the device is being registered, or the user is not assigned a role with the Devices permission enabled.
password User is not authorized to access this resource with an explicit deny The password is not present or the username and password pairing cannot be authenticated.
deviceInformationList More than 40 devices defined within the request. Limit request to 40 devices. The request must contain a maximum of 40 devices. Separate the request into multiple messages to add, update, or remove more than 40 devices.

deviceName

 The device [deviceName] is not unique within the associated location [locationId] At least one other device at that locationId exists with the same deviceName.
deviceName for [deviceUniqueIdentifier] is required The deviceUniqueIdentifier is present, but the deviceName is not.
deviceName is required Neither the deviceName nor the deviceUniqueIdentifier are present.
deviceName must not contain spaces The deviceName contains a space, which is an invalid character.
deviceName contains invalid characters The deviceName contains a character that is not alphanurmeric or one of the following special characters: _ . , @ / : # -
deviceUniqueIdentifier Device [deviceUniqueIdentifier] must be 6 sets of two characters, separated by a colon ":" or a hyphen "-" and containing numbers 0-9 and letters A-F The deviceUniqueIdentifer does not follow the format requirements.
Device [deviceUniqueIdentifier] already exists Another device registered with the Device Manager uses the same deviceUniqueIdentifier, and the action specified in the request is add.
deviceUniqueIdentifier is a required field The deviceUniqueIdentifier is not present.
Device [deviceUniqueIdentifier] does not exist in your company The specified device exists at another company on the TraceLink network and cannot be added to, updated, or removed from the company of the user that sent the request.
deviceType deviceType must be one of the supported values The deviceType is not present, or is not Handheld or SmartPhone.
deviceMake deviceMake must be one of the supported values The deviceMake is not specified, or is not Zebra, Google, or Samsung.
Invalid deviceMake based on deviceType, deviceMake must be Zebra or Honeywell when deviceType is Handheld The device Type is Handheld, but the deviceMake is not Zebra or Honeywell.
Invalid deviceMake based on deviceType, deviceMake must either be Google or Samsung when deviceType is SmartPhone The deviceType is SmartPhone, but the deviceMake is not Google or Samsung.
deviceModel deviceModel must be one of the supported values The deviceModel is not specified, or is not MC3300, TC50x, TC51, TC52, CN80L1N, Pixel2, or GalaxyS9.
Invalid deviceModel based on deviceMake, deviceModel must be MC3300, TC70x, TC51, or TC52 when deviceMake is Zebra The deviceMake is Zebra, but the deviceModel is not MC3300, TC50x, TC51, or TC52.
Invalid deviceModel based on deviceMake, deviceModel must be CN80L1N when deviceMake is Honeywell The deviceMake is Honeywell, but the deviceModel is not CN80L1N.
Invalid deviceModel based on deviceMake, deviceModel must be Pixel 2 when deviceMake is Google The deviceMake is Google, but the deviceModel is not Pixel2.
Invalid deviceModel based on deviceMake, deviceModel must be GalaxyS9 when deviceMake is Samsung The deviceMake is Samsung, but the deviceModel is not GalaxyS9.
action Device [deviceUniqueIdentifier] does not exist and cannot be deleted The Device Manager does not have record of the device specified and cannot delete it.
action is a required field An action is not present.
[action] failed The Device Manager did not successfully store the device information.
companyExternalId companyExternalId is a required field The companyExternalId is not present.
locationId lnvalid locationId [locationId] The locationId does not exist in the Track & Trace Services.
locationId is a required field The locationId is not present.
locationType locationType is a required field The locationType is not present.
Invalid locationType [locationType] The locationType is not one of the supported values (see Guidelines above).
locationType does not match expected locationType for locationID [locationID] The locationId is found in the Track & Trace Services, but the locationType value does not match the locationType associated with that locationId.
countryCode countryCode is a required field when serialNumberEventManager is SEM The serialNumberEventManager is SEM, but the countryCode is not present.
countryCode must be a valid ISO 3166 Alpha 2-Code The countryCode is not a valid ISO 3166 Alpha 2-Code.
environment environment is a required field The environment is not present or is not Beta, Test, or Production.
port port must be one of the supported values, '8883' or '443' The port is entered, but is not 8883 or 443.
serialNumberEventManager serialNumberEventManager is a required field The serialNumberEventManager is not present.
serialNumberEventManager must be one of the supported values, 'SOM', 'SEM', 'defaultSOM', or 'defaultSEM The serialNumberEventManager is not SOM, SEM, defaultSOM, or defaultSEM.
active active is a required field The active value is not present.
active value must be true or false The active value is not true or false.

Guidelines

Element Type Description
errorInfoList List Begin The list of errors returned by the request. Only present if the request returned at least one error.
  errorInformation Section Begin The error information.
    deviceName String Required. The name of the device that failed authentication.
    deviceUniqueIdentifier String Required. The Machine (e.g. MAC) address of the device that failed authentication.
    errorMessage String Required. The errors returned by the request.
deviceConfigurationFileInformation Section Begin The list of environment URLs for each device added in the request. Present only if at least one device is added successfully.
  environment String Required. The environment URL that the device is registered on.
deviceSuccessList List Begin The list of devices that were successfully added, updated, or deleted with the request message. Present only if at least one device was successfully added, updated, or deleted.
  deviceSuccessInformation Section Begin The success information.
    deviceName String Required. The name of the device that was successfully added, updated, or deleted.
    deviceUniqueIdentifier String Required. The Machine (e.g. MAC) address of the device that was successfully added, updated, or deleted.
    successMessage String Required. A message indicating the success of the request. Possible options:
  • For add action requests: Device <deviceName> has been pre-registered successfully
  • For update action requests: Device <deviceName> has been updated successfully
  • For delete action requests: Device <deviceName> has been deleted successfully

Example

{"deviceConfigurationFileInformation":
		{
			"environment": "https://ki53q5hjo0.execute-api.us-east-1.amazonaws.com/etapi/basic/qetauvir/devmgr"
		}
	"deviceSuccessList": 
		[{"deviceSuccessInformation": 
			[{"deviceName": "HH_1",
			"deviceUniqueIdentifier": "94:FB:29:29:0C:C5",
			"successMessage": "Device HH_1 has been pre-registered successfully"
			}]
		}]
}

Errors

The response includes errors returned by the original Device Administration request, but does not return errors of its own.