Professional Documents
Culture Documents
11
Table of Contents
1. Purpose
The purpose of this document is to provide technical guidelines for integrating to and using
the Remote Rating gateway for purposes of receiving remote rating and have it integrated
into acustomer’s website. This documentation is intended to be used by software developers
comfortable with the use of HTTP posting of name/value pair data.
While all examples shown in this document are written in the Java language, any language
capable of submitting data via HTTP posting of name/value pairs can be used to communi-
cate with the Remote Rating gateway.
2. Overview
The Remote Rating gateway supports the transmission of transactions through the use of
a simple interface to integrate API based on the HTTP Post of name/value pairs.
Additionally, should you want to add a customer markup percentage to the returned rates,
the Remote Rating gateway can add that constant percentage for you. Similarly, should
you want to charge a series of tiered rates, this ability can also be programmed in.
The required information submitted to the Remote Rating gateway, such as freight class,
weight, and origin and destination, ensures that the rates you receive are as completely
accurate as the carriers can provide.
To get started, your account representative will provide you with a username and pass-
word to access the Freight Manager system. Supplying this information to your Remote
Rating Support Technician (support@storygroup.net) will ensure that your customers re-
ceive the most accurate rates based on your shipping contracts.
We will continually be adding new features to our web services, and welcome comments
and suggestions from all our users.
Web Services for Remote Rating Developer’s Guide V1.11
3. Application Overview
Overview
The Remote Rating gateway allows transactions to be submitted through a simple to im-
plement HTTP Post Name/Value pair. This allows for rapid integration of Remote Rating
into your website. Any programming language that supports the submission of data
through a HTTP Post of name/value pair data can be used to interface to the gateway.
Dedicated support staff is on hand to help you during your integration via email at sup-
port@storygroup.net and telephone at (509) 783-8178.
Name/Value pairs will allow the shipment cost to be added to an existing payment flow.
After your customer inputs their address, your server will query our gateway server and
receive relevant information about shipping the purchased goods. Below, you will find
Java code to handle the send and receipt of this information.
Pop-up Windows can be used to provide your customer a “sense”of what the cost to de-
liver the goods would be. The same information is supplied to the gateway, but the in-
formation returned is displayed within a web browser window that pops-up and is format-
ted to compliment your website. This information is more difficult to implement into an
existing payment workflow.
publicclass sendInfo {
try {
String response = postHTTP("Los Angeles", "CA", "90210", "1", "BOX", "50", "1200");
System.out.println("Response = " + response);
} catch (Exception e) {
e.printStackTrace();
}
//Constant information. Can also be made into parameter data and passed in
String originCity = "Seattle";
String originState = "WA";
String originZip = "98225";
Web Services for Remote Rating Developer’s Guide V1.11
try {
url = new URL(thisURL);
urlConn = (HttpURLConnection)url.openConnection();
urlConn.setDoOutput(true);
urlConn.setUseCaches(false);
urlConn.setRequestMethod("POST");
// Receive response
input = new BufferedReader(new InputStreamReader(urlConn.getInputStream()));
}
catch (MalformedURLException me){
errorOut += "MalformedURLException; " + me;
}
catch (IOException ioe){
errorOut +="IOException; " + ioe.getMessage();
}
return toReturn;
}
}
This code will post a transaction request to the server and then receive the result. A typi-
cal result is shown below:
error=0,msg=,rate=149.35,numDays=3.0,carrierSCAC=SAIA,sgiShipmentId=8b01911b-a23f-4123-
a2df-2eb07dae9534
If an error were to occur, please take note of the error code returned. Our Support Tech-
nicians will be able to troubleshoot the cause of the failure with this code. The error re-
sponse would be as follows:
error=1,msg=Fatal%20Error.%20Invalid%20DZ
Web Services for Remote Rating Developer’s Guide V1.11
You can then use your web server to parse the information, integrate into your current
payment system and/or display to your customer.
Web Services for Remote Rating Developer’s Guide V1.11
This web form contains the following fields. As noted below, some of the fields are in-
dexed so as to allow for multiple items to be shipped. Remote rating can handle an infi-
nite number of items per shipment, however for large volume shipments, it is still rec-
ommended you call your representative for a volume quote.
This code will post a transaction request to the server and then receive the result in the
pop-up window. A typical result is shown below:
Your shipment will take approximately 3.0 day(s) to ship for a cost of $106.45
If an error were to occur, please take note of the error code returned. Our Support Tech-
nicians will be able to troubleshoot the cause of the failure with this code. The generic
error response would be as follows and would be populated with error information:
There was an error receiving information about your shipment. The error returned was:
An error has occurred. Invalid OZ code. Please contact support@storygroup.net for fur-
ther assistance.
Web Services for Remote Rating Developer’s Guide V1.11
For example:
Item 1: 2 Boxes; Frieght Class: 60; Weight: 1,400 pounds
Item 2: 1 Drum; Freight Class: 100; Weight: 450 pounds
The contents portion that you would send to the remote rating engine would be:
…quantity0=2&package0=BOX&freightClass0=60&weight0=1400&quantity1=1&package1=DRUMS&freigh
tClass1=100&weight1=450 …
Each item is represented with an integer (from 0 to n) appended to the freightClass and
corresponding weight field. The rating engine can accept an infinite number of items per
proposed shipment. It is recommended, however, that if your shipment pushes the limits
of LTL volume parameters, that you contact your representative so as to secure a volume
quote in advance.
7. Accessorials
The remote rate gateway will accept values for three accessorial values: Residential Deli-
very, Destination Lift Gate, and Notify Prior to Delivery.
These are simple true/false values and could be simply implemented through the use of
HTML checkboxes for the customer to select.
8. Package Types
We encourage users of the Remote Rating application to use a drop-down select box, or
hard-coded list of package types for each line. This will limit the possibility of incorrect
information being passed to the rating engine, returning invalid rates.
Value Description
BG Bag
BOX Box
BUNDLES Bundle
CARTONS Carton
CASES Case
CRATES Crate
DRUMS Drum
PALLETS Pallet
PIECES Piece
ROLL Roll
TRAILER Trailer
9. Shipments
One of the values returned by the remote rate gateway is sgiShipmentID. This is a unique
identifier that retains information about this proposed shipment and the rates that are re-
turned.
When this identifier is submitted through an HTTP Post passing name/value pairs to
http://www.sgiapps.com/api/integration/customerRate.cfc.
XML example:
<request>
<SGICN>SGICN provided by support</SGICN>
<sgiShipmentId>12345-543231-qwert-asdfa-12345</sgiShipmentId>
<carrierContractId>(7695227666,3023,0)</carrierContractId>
</request>
A quote will be created within Freight Manager complete with all of the shipment’s ori-
gin and destination attributes as well as the selected carrier and rate.
Web Services for Remote Rating Developer’s Guide V1.11
This is useful for customers who use a shopping cart type of system with their customers.
By keeping track of this identifier through the shopping cart, the shipment’s information
will not need to be posted to the Freight Manager gateway a second time; just this iden-
tifier.
The methods and/or forms used to create the initial rate request as described above can be
used to send this information.
The sgiShipmentID identifiers will be valid for a period of seven days. After that time,
your customer will need to rerate the shipment.
The carrierContractId is used to identify which carrier contract was chosen during the
rating process. This is only necessary if the rating process is returning all rates. Custom-
ers who choose to return only lowest cost will not need to return the carrierContractId as
it is stored on initial rating process.
Upon successful transmission of a sgiShipmentID, you will receive the following mes-
sage: error=0,msg=File received and processed successfully.
Should an error occur, your application would receive the following:error=1,msg=There was
a problem processing file, check data and re-send file.
We have added the ability to return responses in multiple formats. You can receive your
response as a CSV, XML or Json response depending on your needs. You can request to
receive lowest cost carrier or return all rates. When you are being setup for using the re-
mote rating system you can specify what response you require. This can also be changed
at any time by contacting the support department.
For CSV multiple rate the response will contain a carrierContractID that is pipe deli-
mited. Return the carrier contract id as you receive it. Each rate will have a qualifier de-
picting what rate it is in the response. Here is an example:
eror=0,msg=,rate1=149.35,numDays1=3.0,carrierSCAC1=SAIA,carrierContractId1=(7695227666|30
23|0),sgiShipmentId=8b01911b-a23f-4123-a2df-2eb07dae9534
Json:
{
"Data": {
"Error":"0",
"SCAC": "SAIA",
"Rate": “149.35",
"ContractId": “(7695227666,3023,0)”,
"Distance": "300",
"Mode": "LTL",
"ServiceDays" : “3.0",
"sgiShipmentID" : "8b01911b-a23f-4123-a2df-2eb07dae9534"
}
}