AuctionInc Shipping API 

Getting Started

INTRODUCTION

What is the Shipping API?
The AuctionInc Shipping API is a web service providing an XML interface to our shipping engine technology. By integrating our API, your customers can utilize the shipping rate technology we have developed without ever leaving your web site. With one call to our API, you can offer your customers accurate comparative rates for multiple shipping options across multiple carriers and services for one or more items for both domestic and international destinations.

Is the Shipping API the best choice for you?
AuctionInc provides a variety of products which access our shipping rate technology. Using the API requires the most effort to implement, but offers significant advantages:

• You can utilize the shipping rates returned from the API in the manner and presentation most appropriate for your particuar site
• Web Service Providers who offer products such as shopping carts can integrate our shipping rates directly into their product
• If you are an ecommerce vendor currently using a shopping cart or ecommerce storefront which you wish to continue using, utlilizing our API will allow you to offer accurate,
  configurable shipping rates to your customers without having to switch to our own ShopCart product

TECHNICAL REQUIREMENTS

Programmng Skills are necessary in order to implement this API, in particular experience with programming for the Internet and with web site development tools and techniques. You must be able to gather the necessary data for the XML request, construct and parse XML, send a POST request, and probably most importantly, utilize the results of your API appropriately in your web site or product.

Any Programming Language can be used to utilize the Shipping API, including Visual Basic, Perl, ASP, java, PHP, C++, etc. The only requirement is the ability to construct, send and parse the XML which comprises the data which is exchanged between you and us. 

XML and HTTP are the two essential protocols which are required to utilize the Shipping API. XML is a simple, platform independent, very flexible text format protocol for exchanging information. HTTP is the standard protocol for transferring World Wide Web documents, including XML documents.

BEFORE YOU START

Establish an AuctionInc Account
All Shipping API users must first establish an account with AuctionInc at www.auctioninc.com. On the registration page, select the Shipping API under Ecommerce Tools as your product type. Please familiarize yourself with our pricing policies for the Shipping API before you register. If you already have an AuctionInc account, you can add a subscription to the Shipping API from My Account => Product Subscriptions. The AuctionInc Shipping API includes rating availability for supported international carrier services at no additional charge.

Record your Access Key
After you complete registration or subscription sign-up, you are given an Account ID. This Account ID must be included in all API calls to the AuctionInc Shipping API. This access key will always appear on your Product Subscription page.

OVERVIEW OF THE API PROCESS

Four Step Process
The process of utilizing the Shipping API breaks down into four general steps:

1. Build the XML Request
Each request is composed of XML elements that specify the request parameters (e.g., the properties of one or more items to be rated). The specific elements required for each of the two call types (configured and non-configured) is provided in detail in API Methods, and the details on each element are specified in the API Schema.

2. Create an HTTP POST Connection
To initiate a Shipping API call, you will make an HTTP request. This request will consist of a standard HTTP “POST” request, made up of the request, request header fields, and the message body. The message body of this request will be the Shipping API Request XML.

3. Send the XML Request
The URL to post your request to is http://api.auctioninc.com/websvc/shire.

4 . Parse the XML Response
For every successful POST initiated by you, we will transmit back a HTTP response. The Shipping API response XML will be returned in the message body of this HTTP response. You will then need to parse this response, using the techniques available to you in the language you are using. The elements returned in the response for both call types (Saved Settings and XML settings) are specified in API Methods document. The details on these elements is specified in the API Schema document. After you parse the response, you will then of course want to manage the data returned in whatever way is appropriate for your particular web site or application or, if an error is returned, to take the appropriate action.


Data Transaction Summary

The table below illustrates a generic example of the flow of information to and from the AuctionInc API server:

Saved Settings (SS) vs XML Settings (XS) Calls
Saved Settings-based (SS) calls require pre-configuration of shipping preferences prior to making calls, but in exchange for this additional step, a variety of features are offered which are not available when making XML Settings (XS) calls.

These include:

• Promotional Rates Discounts
• Packaging Weight Factors
• Third Party Insurance
• Insurance Thresholds
• Handling Fees
• Custom Codes for Handling Fees
• Custom Codes for Fixed Fees
  
  

MAKING THE CALLS

Construction of XML Calls
The Request XML is made up of two main elements: the RequestHeader and the RequestBody. Both of these elements are contained within an Envelope root element. The RequestHeader contains the AccountID element, which is used to identify the caller, reference any saved preferences, and provide for accounting data. The RequestBody will contain an element for the method call (along with a version number), and inside that element additional nodes or elements will supply any necessary arguments to support the method invoked.

<?xml version="1.0 encoding=iso-8859-1" utf-8 ?>
<Envelope>
   <Header>
      <AccountId>your account id</AccountId>
   </Header>
   <Body>
      <GetTime version="2.0">
      </GetTime>
   </Body>
</Envelope>

POST /websvc/shire HTTP/1.0
HOST: api.auctioninc.com
Connection: Close
Content-Type: text/xml
Content-Length: 262

Your XML String

<?xml version="1.0" encoding="utf-8" ?>
<Envelope>
 <Header>
      <AccountId>your account id</AccountId>
 </Header>
 <Body>
      <GetItemShipRateSS version="2.1">
      <DetailLevel>1</DetailLevel>
      <Currency>USD</Currency>      
      <DestinationAddress>
            <ResidentialDelivery>true</ResidentialDelivery>
            <CountryCode>US</CountryCode>
            <PostalCode>90210</PostalCode>
            <StateOrProvinceCode>CA</StateOrProvinceCode >
      </DestinationAddress>
    <ItemList>
       <Item>
             <RefCode>keyboard-101</RefCode>
             <Quantity>2</Quantity>
             <CalcMethod code="C">
                   <CarrierCalcProps>   
                         <OriginCode>your defined origin code, if any</OriginCode>                                 
                         <Weight>4</Weight>
                         <WeightUOM>LBS</WeightUOM>
                         <DeclaredValue>59.95</DeclaredValue>
                         <PackMethod>T</PackMethod>
                   </CarrierCalcProps>
             </CalcMethod>
       </Item>
    </ItemList>
 </GetItemShipRateSS>
 </Body>
</Envelope>

 
<?xml version="1.0" encoding="utf-8" ?>
<Envelope>
<Header>
  <AccountId>your account id</AccountId>
 </Header>
 <Body>
  <GetItemShipRateXS version="2.1">
  <DetailLevel>1</DetailLevel>
    <Currency>USD</Currency>
    <CarrierList>
         <Carrier code="UPS">
              <EntryPoint>P</EntryPoint>
              <ServiceList>
                   <Service code="UPSGND">
                      <PkgWeightMax>50</PkgWeightMax>
                   </Service>
                   <Service code="UPSNDA" />
             </ServiceList>
         </Carrier>
         <Carrier code="DHL">
              <EntryPoint>D</EntryPoint>
              <AccessKey>your DHL access key</AccessKey>
              <PostalCode>01610</PostalCode>
              <ServiceList>
                   <Service code="DHLGND" />
                   <Service code="DHLNDA" />
              </ServiceList>
         </Carrier>
         <Carrier code="USPS">
              <FlatRatePackaging>ENV</FlatRatePackaging>

              <ServiceList>
                   <Service code="USPEXP" />
                   <Service code="USPMM">
                      <OnDemand>true</OnDemand>
                   </Service>
              </ServiceList>
         </Carrier>
    </CarrierList>
    <OriginAddressList>
         <OriginAddress>
              <OriginCode>MA-RTS</OriginCode>
              <CountryCode>US</CountryCode>
              <PostalCode>01610</PostalCode>
              <StateOrProvinceCode>MA</StateOrProvinceCode>
         </OriginAddress>
         <OriginAddress>
             <OriginCode>CA-WHS</OriginCode>      
             <CountryCode>US</CountryCode>
             <PostalCode>90210</PostalCode>
             <StateOrProvinceCode>CA</StateOrProvinceCode>
         </OriginAddress>
    </OriginAddressList>
    <DestinationAddress>
         <ResidentialDelivery>true</ResidentialDelivery>
         <CountryCode>US</CountryCode>
         <PostalCode>90210</PostalCode>
         <StateOrProvinceCode>CA</StateOrProvinceCode >
    </DestinationAddress>
    <ItemList>
         <Item>
              <RefCode>Compact Disk</RefCode>
              <Quantity>2</Quantity>
              <CalcMethod  code="C">
                   <CarrierCalcProps>
                        <Length>2</Length>
                        <Width>10</Width>
                        <Height>2.5</Height>
                        <DimUOM>IN</DimUOM>
                        <Weight>4</Weight>
                        <WeightUOM>LBS</WeightUOM>
                        <DeclaredValue>59.95</DeclaredValue>
                        <PackMethod>T</PackMethod>
                        <OriginCode>MA-RTS</OriginCode>
                        <OnDemandServices>
                           <ODService>USPMM</ODService>
                        </OnDemandServices>
                   </CarrierCalcProps>
              </CalcMethod>
         </Item>
         <Item>
              <RefCode>Instruction Book</RefCode>
              <Quantity>1</Quantity>
              <CalcMethod code="C">
                   <CarrierCalcProps>
                        <Length>6</Length>
                        <Width>1</Width>
                        <Height>8</Height>
                        <DimUOM>IN</DimUOM>
                        <Weight>1.5</Weight>
                        <WeightUOM>LBS</WeightUOM>
                        <DeclaredValue>29.95</DeclaredValue>
                        <PackMethod>S</PackMethod>
                        <OriginCode>CA-WHS</OriginCode>
                        <OnDemandServices>
                           <ODService>USPMM</ODService>
                        </OnDemandServices>
                   </CarrierCalcProps>
              </CalcMethod>
         </Item>
    </ItemList>
  </GetItemShipRateXS>
</Body>
</Envelope>

Debugging Your API Calls
Here is an article in our knowledgebase detailing some debugging strategies, along with a form you can use to directly test the API:

Troubleshooting the Shipping Calculator API


Managing the Response XML

Testing for Success
The HTTP response code should first be tested for "200 OK" to ensure that your API call was successfully invoked.

Sample Rating Response XML (Detail Level = 1):

<?xml version="1.0" encoding="utf-8" ?>
<Envelope>
   <Header>
      <Date>2008-10-28 19:53:14 GMT</Date>
   </Header>
   <Body>
      <ItemShipRate>
        <Currency>USD</Currency>
        <ShipRateList>
           <ShipRate>
              <Valid>1</Valid>
              <CarrierCode>USPS</CarrierCode>
              <ServiceCode>USPSPM</ServiceCode>
              <ServiceName>PriorityMail</ServiceName>
              <CalcMethod>C</CalcMethod>
              <Rate>48.26</Rate>
           </ShipRate>
           <ShipRate>
              <Valid>1</Valid>
              <CarrierCode>UPS</CarrierCode>
              <ServiceCode>UPSGND</ServiceCode>
              <ServiceName>Ground</ServiceName>
              <CalcMethod>C</CalcMethod>
              <Rate>31.21</Rate>
            </ShipRate>
        </ShipRateList>
     </ItemShipRate>
   </Body>
</Envelope>

• Handling Errors
  There are two general types of errors that could occur.
  
  - Type 1 Errors indicate invalid or improperly formatted xml to make the Shipping API call. The error node will appear at the root Envelope level.
    These errors need to be handled by correcting the problem and resending the XML request.
  
    Here is a sample Type 1 Error:
  

   <?xml version="1.0 encoding=iso-8859-1" utf-8 ?> 
   <Envelope> 
      <Header> 
         <AccountId>your access key</AccountId> 
      </Header> 
      <Body> 
         <Error> 
            <Code>560</Code>
            <Message>Invalid Account Id</Message>
            <Severity>CRITICAL</Severity>
         </Error> 
      </Body> 
   </Envelope> 
      

  -Type 2 Errors are for a particular carrier service which for some reason is unable to provide rates for a given item/destination. The error node will appear inside the Carrier node.  These errors can be handled by you according to your preference.
  
   Here is a sample Type 2 Error:
  

   <?xml version="1.0 encoding=iso-8859-1" utf-8 ?> 
   <Envelope> 
      <Header> 
         <AccountId>your access key</AccountId> 
      </Header> 
      <Body> 
         <ItemShipRate>
            ...   
            <ShipRate>
               <Valid>False</Valid>
               <CarrierCode>USPS</CarrierCode>
               <ServiceCode>USPSPP</ServiceCode>
               <ServiceName>Parcel Post</ServiceName>
               <CalcMethod>CARRIER></Carrier>
               <Rate></Rate>
               <ErrorList>
                  <Error>
                     <Code>710</Code>
                     <Message>Item exceeds maximum weight</Message>
                     <Severity>NOTICE</Severity>
                  </Error>
               </ErrorList>
            </ShipRate>
            ...      
         </ItemShipRate>
      </Body> 
   </Envelope>
  

 XS Integration Tasks