Integration Guide
Required URL Whitelisting
Cargo Spectre uses localhost (port 7100 by default) for all API calls, but does need access to certain external addresses for the following services:
| URL | SERVICE |
|---|---|
https://*.spectre-licensing.com
| Licensing and optional cloud storage of cargo data
|
|
|
| Updates |
https://cargospectre.blob.core.windows.net/releases/ | Client version updates and support |
| Remote support |
To test whether your network settings are compatible, you can visit our Network Test Page and check whether the images from all of the above services have been loaded correctly by your browser.
Integration Options
Some customers need to integrate their Cargo Spectre machines with proprietary software. We offer three different ways to transfer API calls to individual Spectre machines - choose the one that works best for your business! For information on our API, please visit our API documentation.
Note
Local Connections
Pros - Information stays local, does not depend on internet bandwidth, and is generally the most responsive.
Cons - Using the API requires someone familiar with RESTful APIs to integrate with your WMS or tablet apps. Clients must be on the same network as Spectres, Spectre local IP addresses must be known, and intranet traffic must be enabled on the network. The spectre machines respond to HTTP commands on their local IP address. For example, let’s say a Spectre's local IP address is 127.0.0.1 and the software port is the default 7100. A computer on the same network can use a simple browser to request a dimension by going to the URL “http://127.0.0.1:7100/dimension”.
The only complication is knowing what the Spectre local IP addresses are. Some clients statically assign the IP address on their network and build a list locally.
Alternatively, you can query our licensing server. When the Spectre checks out a license, it registers the following information:
- Local IP address
- Port
- Machine Name with the server
This information can be queried by API to get a directory list of Spectres for a set of license credentials. Using the license server API, the process would look like this:
- User wants a Spectre to dimension.
- Client software queries our server for Spectres under their license.
For additional information on integrating with this method, use the API Documentation.
Local Network via Cargo Spectre Cloud
Pros - Fastest way to get up and running. Options for exporting to FTP servers, endpoint URLs, etc. via various different formats. Requires zero to minimal coding/IT setup.
Cons - Requires some communication over HTTP which can be insecure. Can only be used on local networks. Requires internet connection.
Via the Cargo Spectre cloud, you can remotely control machines and export data with each scan, or batch-export data via our interface to email, CSV, or a server that accepts JSON, XML, or other proprietary data setups. We are always adding new formats!
For additional information on specific topics, see below:
Global Connections
Warning
(NOT RECOMMENDED DUE TO COMMON IT COMPLICATIONS)
Pros - API can be accessed from anywhere, not just the local network
Cons - Requires an individual port forward on routers for each Spectre machine
While the data path is very different, the access is incredibly similar. First, the network router must have a port forwarded to the machine. Then, to access that machine, you can use the global IP address and port combination just like in the Local Connections section. The only catch is that the registered global IP address on our licensing server is generally not accurate due to most client's network configurations. This should be done only on very simple networks, or when using mobile data.
Proxy
Pros - API can be accessed from anywhere, requires minimal IT setup
Cons - Using the API requires someone familiar with RESTful APIs to integrate with your WMS or tablet apps. Uses a middle-man to route API calls and responses through the internet
In the Spectre settings, there is an option to enable our proxy support. On startup, this opens a 2-way socket with our proxy server and awaits commands. All clients can direct their API calls to this singular endpoint. API calls additionally require licensing credentials and target Spectre information (i.e. Machine Name) to route the request to the correct machine. All traffic is encrypted with HTTPS or secure sockets. Using the Gateway Proxy looks like this:
- User wants a Spectre to dimension.
- Client software sends API request to Gateway Proxy. Included in the headers of the request are licensing credentials and Machine Name.
- Proxy server looks at machines associated with that license, and looks for a socket associated with that Machine Name. If found, API is forwarded through that socket.
- Spectre fulfills API request and responds to the Proxy.
- Proxy forwards response to client.
For examples on how to send API requests to the Proxy Server, please visit our API Reference page.
Testing the Device API Online
Cargo Spectre has set up an endpoint where integrations can go and test their API calls without requiring a live machine to test on. This endpoint is called "Virtual Spectre". Nearly all the API Commands detailed in API Reference page are operational on Virtual Spectre.
General Instructions
To use the Virtual Spectre, first you must determine what mode of integration is needed - local IP or proxy. Once that is decided, construct your calls as normal but subtitute the appropriate Virtual Spectre endpoint in place of the ip address:port or proxy.spectre-licensing.com endpoints.
Note that accessing the endpoint without providing a command (in the case of GET requests) will simply return the default page of the service provider.
Virtual Spectre is Stateless!
Please note that the Virtual Spectre endpoint is completely stateless. Many API calls that require preservation of state, particularly SetSetting, may not function as intended aside from providing feedback that they have completed correctly.
However, for setting barcodes and scanning, the machine will preserve any barcode sent to it but only for the duration of the API call. This means if the API call is split into two parts, the machine will not remember. If the API call is combined into one, the machine will reflected the correct barcode in the Dimension response.
For Local API
Endpoint
For local API, the correct endpoint is:
https://spectre-virtual.azurewebsites.net/localapiPlease use the endpoint exactly as you would the original <ip address>:<port> endpoint. This means you will just need to add <api_command>.
| Local Spectre Virtual Example | Local API Example |
|---|---|
https://spectre-virtual.azurewebsites.net/localapi/Dimension+Snapshot | 10.1.1.1:7100/Dimension+Snapshot |
Other Required Info
None.
Local API Example
Navigate to the below URL: https://spectre-virtual.azurewebsites.net/localapi/Dimension+Snapshot
For Proxy API
Endpoint
For proxy API, the correct endpoint is:
https://spectre-virtual.azurewebsites.net/proxyapiOther Required Info
Please use the endpoint exactly as you would the original proxy.spectre-licensing.com endpoint, meaning you will need to append /api/<url-encoded-machinename> after it.
Additionally, you will still need to encode the username:password according to the standard Basic Authorization format and send a Basic Authorization header with your request. To encode your Basic Authorization header you can use the tool provided in "Basic Auth"-Encoded Authentication Info (the link points to a page about Exporting from the Web GUI but the encoding is the same).
Below is all the required info to send commands to the proxy endpoint:
| Machine Name | Password | |
|---|---|---|
| TestComputer-1 | dockManager@fakeLogistics.com | yourPasswordHere |