You are on page 1of 17

Web Services for Remote Rating Developer’s Guide V1.

11

Remote Rating for Integration


into Customer’s websites
April 3, 2015 ~ Version 1.11
Web Services for Remote Rating Developer’s Guide V1.11

Document Revision History

Version Date Details of Revision

1.0 November 23, 2007 Initial release

1.1 February 19, 2008 Inclusion of multiple items in ship-


ment.

1.2 February 26, 2008 Inclusion of Accessorial information

1.3 June 12, 2008 Added inclusion of SGIShipmetnId


and creation of shipment file

1.4 June 23, 2008 Added processShipmentXML.jsp


page to handle Shipment information
sent via XML webservice.

1.5 November 4, 2008 Added ability to send quantities for


each item. Added ability to send
package type for each item. Added
Hazardous Material service level.

1.6 November 25, 2008 Added ability to send Origin Lift


Gate and Origin Residence through
as accessorials (see section 7.0)

1.7 March 1, 2011 Inclusion of new name, address, and


dimension shipment attributes and
accessorial types. Removal of con-
straint to only five items per ship-
ment. Shipments can now have n
number of items. Clarification of
when it is preferred to receive ma-
nual volume quote.

1.8 December 12, 2012 Changed URL used to post rating


requests.

1.9 November 18, 2014 Updated Xml request format.

1.10 February 16, 2015 Updated so all error messages return


the same format.

1.11 April 3, 2015 Added Rating Response Options


Web Services for Remote Rating Developer’s Guide V1.11

Table of Contents

Remote Rating for Integration into Customer’s websites

Document Revision History ........................................................................................ 2


Table of Contents ......................................................................................................... 3
1. Purpose ..................................................................................................................... 4
2. Overview ................................................................................................................... 4
3. Application Overview ............................................................................................... 5
Overview .................................................................................................................... 5
Name/Value Pairs vs. Pop-Up Windows .................................................................. 5
Obtaining a User ID for Remote Rating .................................................................... 5
4. Transaction for Name/Value Pair Response ....................................................... 6
HTTP Name/Value Pair Using Post Method ........................................................ 6
5. Transaction for Pop-Up Window Response ........................................................ 9
HTTP Pop-Up Display Using Post Method .......................................................... 9
6. Transaction of Multiple Items ............................................................................... 13
7. Accessorials............................................................................................................ 13
8. Package Types ...................................................................................................... 15
9. Shipments ............................................................................................................... 15
10. Rate Response ......................................................................................... 17
Web Services for Remote Rating Developer’s Guide V1.11

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.

This application contains inherent flexibility to return results in a variety of fashions,


provided they have been previously established with our support personnel. It will not
only return name/value pairs as a response, but also formatted HTML code designed to
compliment the look and feel of your existing website.

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 vs. Pop-Up Windows


Remote Rating offers two main ways to retrieve information: return of name/value pairs
and information via pop-up window.

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.

Obtaining a User ID for Remote Rating


The easiest way to get started with Remote Rating is to call a Support Technician at
(509) 783-8178 with the following information:
• Domain name where information will be requested
• Freight Manager username
• Freight Manager password
• Requested information format (name/value pair; formatted HTML)
• URL of website with similar look/feel to requested HTML response
Web Services for Remote Rating Developer’s Guide V1.11

4. Transaction for Name/Value Pair Response


Transactions are submitted through an HTTP Post of name/value pairs. The post must be
performed by the server, not from your customer’s web browser. The following code ex-
ample (in Java) shows how to send a transaction request to Story Group for a single item
within a shipment and how to receive the response. Shipments containing multiple items
are discussed in Section 6. Transaction of Multiple Items. Information to include acces-
sorial fees is detailed in Section 7. Accessorials. Section 8. Package Types describes the
allowable package types to be sent for each line item. The example below details the min-
imum needed to successfully rate.

HTTP Name/Value Pair Using Post Method


import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;

publicclass sendInfo {

publicstaticvoid main( String[] args) {

try {
String response = postHTTP("Los Angeles", "CA", "90210", "1", "BOX", "50", "1200");
System.out.println("Response = " + response);
} catch (Exception e) {
e.printStackTrace();
}

publicstatic String postHTTP(String destinationCity, String destinationState, String des-


tinationZip, String quantity0, String package0, String freightClass0, String weight0 ) {
/*
* Method expects:
* destinationCity = String containing destination's city name
* destinationState = String containing destinations' state name
* destinationZip = String containing destination's Postal or ZIP code
* quantity0 = String containing number of items for this line
* package0 = String describing package type for this line (see section 8 for allow-
able types)
* freightClass0 = String containing shipment's overall class
* weight0 = String declaring weight in pounds
*/

URL url = null;


HttpURLConnection urlConn = null;
DataOutputStream printout = null;
BufferedReader input = null;

// URL of application server


String thisURL = "http://www.sgiapps.com/api/integration/customerRate.cfc";

String errorOut = ""; // Used to capture error data


String toReturn = ""; // Used to capture response data
String dataToSend = ""; // Used to accumulate data to send to thisURL

//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

//Provided by Story Group Support Technician


String SGICN = "ASDLKJ23423GLF546K45JIWJLKA123";

try {
url = new URL(thisURL);
urlConn = (HttpURLConnection)url.openConnection();
urlConn.setDoOutput(true);
urlConn.setUseCaches(false);
urlConn.setRequestMethod("POST");

dataToSend = "destinationCity=" + URLEncoder.encode(destinationCity, "UTF-8") +


"&";
dataToSend += "destinationState=" + URLEncoder.encode(destinationState, "UTF-8") +
"&";
dataToSend += "destinationZip=" + URLEncoder.encode(destinationZip, "UTF-8") + "&";
dataToSend += "quantity0=" + URLEncoder.encode(quantity0, "UTF-8") + "&";
dataToSend += "package0=" + URLEncoder.encode(package0, "UTF-8") + "&";
dataToSend += "freightClass0=" + URLEncoder.encode(freightClass0, "UTF-8") + "&";
dataToSend += "weight0=" + URLEncoder.encode(weight0, "UTF-8") + "&";
dataToSend += "originCity=" + URLEncoder.encode(originCity, "UTF-8") + "&";
dataToSend += "originState=" + URLEncoder.encode(originState, "UTF-8") + "&";
dataToSend += "originZip=" + URLEncoder.encode(originZip, "UTF-8") + "&";
dataToSend += "SGICN=" + URLEncoder.encode(SGICN, "UTF-8");

urlConn.setRequestProperty("Content-length", dataToSend.length()+ "" );


printout = new DataOutputStream(urlConn.getOutputStream());

// Sends the data via POST


printout.writeBytes(dataToSend);
printout.flush();
printout.close();

// Receive response
input = new BufferedReader(new InputStreamReader(urlConn.getInputStream()));

// Write response to toReturn


String str;
while( null != ((str = input.readLine())))
toReturn += str;
input.close ();

}
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

Name Field Type Value

error Binary 0 = no error (false); 1 = error (true)

msg Text Contains text describing what the


error was. This text is useful to help
diagnose the problem.

rate Float The rate returned by the carrier to


move the shipment from origin to
destination

numDays Float The number of days the carrier esti-


mates the shipment will take to move
from the origin to destination.

carierSCAC Text The SCAC (Standard Carrier Alpha


Code) of the carrier who is returning
this rate.

sgiShipmentID Text Unique identifier for this shipment


and rate returned. If this shipment
rate is accepted, this identifier can be
used to book the shipment automati-
cally (see Section 8: Shipment)

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

5. Transaction for Pop-Up Window Response


Transactions are submitted through an HTTP Post of name/value pairs. In contrast to the
method described above, this post will be performed by your customer’s web browser
and they will receive the response directly from our application gateway. The following
code example (in HTML) shows how to send a request for shipment of a single item
within a shipment and how the response is formatted. Information for multiple items
within a shipment is detailed in Section 6. Transaction of Multiple Items. Information to
include accessorial fees is detailed in Section 7. Accessorials. Each item can have a pack-
age type associated to it. Package types are definied in Section 8. Package Types.

HTTP Pop-Up Display Using Post Method


The Pop-Up display will simply require you to place the following HTML form on your
website’s product pages. The dimensional values should be modified to account for the
product to be shipped. By placing the ‘target=”_blank”’into the <form> tag, the response
from the Remote Rating gateway will be placed into a new window.
<h1>Find the Shipping Cost</h1>
<p>Enter your City, State and Zipcode in the form below to get an approximate cost to
ship this product to you</p>
<form me-
thod="post"action="http://www.sgiapps.com/api/integration/customerRate.cfc"target="_blank
">
City: <input type="text"size="30"name="destinationCity"/><br />
State: <input type="text"size="10"name="destinationState"/><br />
Zip : <input type="text"size="10"name="destinationZip"/>
<input type="submit"name="submit"value="Get Rate!"/>
<input type="hidden"name="originCity"value="Seattle"/>
<input type="hidden"name="originState"value="WA"/>
<input type="hidden"name="originZip"value="98225"/>
<input type="hidden"name="quantity0"value="1"/>
<input type="hidden"name="package0"value="BOX"/>
<input type="hidden"name="freightClass0"value="50"/>
<input type="hidden"name="weight0"value="1200"/>
<input type="hidden"name="SGICN"value="ASDLKJ23423GLF546K45JIWJLKA123"/>
</form>

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.

Name Field Type Value Required?

destinationName Text Contains text describing the false


name of the person or com-
pany where the shipment
will be delivered.

destinationContactPhone Text Contains text describing false


the contact phone num-
ber.
Web Services for Remote Rating Developer’s Guide V1.11

destinationContactEmail Text Contains text describing false


the contact email

destinationAddr1 Text Contains text describing the false


address (line 1) where the
shipment will be delivered.

destinationAddr2 Text Contains text describing the false


address (line 2) where the
shipment will be delivered.

destinationCity Text Contains text describing the true


city where the shipment will
be delivered.

destinationState Text Contains text describing the true


state where the shipment
will be delivered.

destinationZip Text Contains text describing the true


postal or ZIP code where the
shipment will be delivered.

originName Text Contains text describing the false


name of the owner where the
shipment will originate. If
you have multiple ware-
houses, this should reflect
where the product currently
resides.

originContactPhone Text Contains text describing the false


contact phone number.

originContactEmail Text Contains text describing the false


contact email address.

originAddr1 Text Contains text describing the false


address (line 1) where the
shipment will originate. If
you have multiple ware-
houses, this should reflect
where the product currently
resides.
Web Services for Remote Rating Developer’s Guide V1.11

originAddr2 Text Contains text describing the false


address (line 2) where the
shipment will originate. If
you have multiple ware-
houses, this should reflect
where the product currently
resides.

originCity Text Contains text describing the true


city where the shipment will
originate. If you have mul-
tiple warehouses, this should
reflect where the product
currently resides.

originState Text Contains text describing the true


state where the shipment
will originate. If you have
multiple warehouses, this
should reflect where the
product currently resides.

originZip Text Contains text describing the true


postal or ZIP code where the
shipment will originate. If
you have multiple ware-
houses, this should reflect
where the product currently
resides.

itemDescription[0-n] Text Describes the item to be false


shipped.

quantity[0-n] Numeric Numerical data detailing the true


quantity of the package type
provided for this line item.

package[0-n] Text Packaging type for this line true


item. Possible values are
detailed in Section 8. Pack-
age Types

freightClass[0-n] Numeric Numerical data detailing the true


freight class of the product
to be shipped. This informa-
tion is specific to the item.

length [0-n] Numeric Numerical data detailing the false


length of the product to be
shipped. This information is
specific to the item.

width [0-n] Numeric Numerical data detailing the false


width of the product to be
shipped. This information is
specific to the item.

height [0-n] Numeric Numerical data detailing the false


height of the product to be
shipped. This information is
specific to the item.
Web Services for Remote Rating Developer’s Guide V1.11

nmfc [0-n] Text Defining number of the false


freight as determined by the
National Motor Freight
Classification. This informa-
tion is specific to this item

weight[0-n] Numeric Numerical data detailing the true


weight of the product to be
shipped. This information is
specific to the shipment.

SGICN Text Story Group Customer true


Number as provided by a
Story Group Support Tech-
nician. This information
ensures your customers re-
ceive the most accurate
rates.

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

6. Transaction of Multiple Items


By including multiple freightClass and weight variables in your request, you can process
a shipment that contains more than one item.

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.

Name Field Type Value

res2 Boolean (true/false) Residential Delivery. If this value is


true, the remote rating engine will
include the accessorial fee from the
carrier to have the shipment deli-
vered at a residence.

lg2 Boolean (true/false) Destination Lift Gate. If this value is


true, the remote rating engine will
include the accessorial fee from the
carrier to have a lift gate available at
the shipment’s destination.

not1 Boolean (true/false) Notify Prior to Delivery. If this value


is true, the remote rating engine will
include the accessorial fee from the
carrier to provide the destination
notification prior to delivery.

haz Boolean (true/false) Hazardous Materials. If this value is


true, the remote rating engine will
include the accessorial fee from the
carrier to transport hazardous mate-
rials.
Web Services for Remote Rating Developer’s Guide V1.11

res1 Boolean (true/false) Residential Origin. If this value is


true, the remote rating engine will
include the accessorial fee from the
carrier to have the shipment picked
up at a residence.

lg1 Boolean (true/false) Origin Lift Gate. If this value is true,


the remote rating engine will include
the accessorial fee from the carrier to
have a lift gate available at the ship-
ment’s origin.

cod1 Boolean (true/false) Charge on Delivery. If this value is


true, the remote rating engine will
include the accessorial feel from the
carrier to charge the consignee prior
to the freight being delivered. NOTE:
this can limit the number of carriers
returned as not all offer this service.

const Boolean (true/false) Construction / Non-Commercial


Delivery. If this value is true, the
remote rating engine will include the
accessorial feel from the carrier to
charge for delivering to a construc-
tion site/non-commercial address.

conv Boolean (true/false) Convention Site / Non-Commercial


Delivery. If this value is true, the
remote rating engine will include the
accessorial feel from the carrier to
charge for delivering to a convention
site/non-commercial address.

id2 Boolean (true/false) Inside Delivery. If this value is true,


the remote rating engine will include
the accessorial fee from the carrier to
deliver the shipment inside the con-
signee’s location. This is often tied to
residential delivery (res2)

ipu1 Boolean (true/false) Inside Pickup. If this value is true,


the remote rating engine will include
the accessorial fee from the carrier to
pickup the shipment inside the ship-
per’s location. This is usually tied to
residential origin (res1)

trp Boolean (true/false) Tarping. If this value is true, the


remote rating engine will include the
accessorial fee from the carrier to
tarp the shipment.
Web Services for Remote Rating Developer’s Guide V1.11

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.

The available options for packaging types are:

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.

Name Field Type Value

sgiShipmentId UUID Unique identifier about this ship-


ment. A quote within Freight Manag-
er will be created when this identifier
is submitted.

SGICN UUID Unique identifier used to authenticate


request

carrierContractId text Identifier used to load the correct


carrier contract on the shipment. This
field should be sent back the same
way it was received. For example:
(7695227666,3023,0)will be sent
thru an XML request. For a HTTP
post which is returned as CSV:
(7695227666|3023|0)

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.

If you requested xml in response, the response format will be xml.


Web Services for Remote Rating Developer’s Guide V1.11

10. Rate Response

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.

Below are example responses for XML and Json.


For XML if you request all rates the pricesheet node will occur multiple times:

<?xml version="1.0" encoding="utf-8"?>


<RateResults>
<StatusCode>0</StatusCode>
<StatusMessage>Rating process completed without errors.</StatusMessage>
<PriceSheets>
<SGIShipmentID/>
<PriceSheet>
<CarrierName>R L Carriers</CarrierName>
<SCAC>RLCA</SCAC>
<Distance>1231.7</Distance>
<Mode>LTL</Mode>
<ServiceDays>3.0</ServiceDays>
<ContractId>(6837227277,3023,0)</ContractId>
<Total>153.24</Total>
</PriceSheet>
</PriceSheets>
</RateResults>

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"
}
}

You might also like