OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

Get Close Retailers

If using Ship to Store fulfillment processes for an in-store pickup program, the user can obtain information about fulfillment partners who are nearest to an order using the Get Close Retailers API. This API is usually used on a product detail page, allowing the consumer to view and select from a list of close stocking retailers.

This API allows information about a specific order request to be sent to the OMS system. The following order information is sent:

  • Manufacturer ID
  • Catalog ID
  • Currency ID
  • Consumer’s Postal Code
  • Country Code
  • Shipment Type (optional: use ‘sts’ or ‘ispu’)
  • Part Numbers
  • Distance (optional: used for the radius calculation: default value is 50, maximum is 150)

In return, the API will return information about the closest retailers, who may be able to fill the order, including the:

  • Name
  • Location
  • Address
  • Phone
  • Distance
  • Maximum Lead Time (in days).

Max Lead Time is a result of the products passed in, and is the same for every retailer record.

When a shopper requests Ship to Store at checkout, the Get Close Retailers API can retrieve information about retail fulfillment locations near the customer.

Getting Started

System Requirements

To use this API, there needs to be a server with Internet access that runs the client’s own shopping cart software to gather the order data

Writing the Application

The client needs to write the Get Close Retailers application. This application assembles an XML package with information about an order from the customer’s shopping cart or from a product detail page. It then uses a Remote Procedure Call (RPC) to pass the package to the information to OMS. This creates a request for the Kibo server to respond to.

The application can be written in any programming or scripting language that can handle a Remote Procedure Call (RPC), including PHP, ASP, Cold Fusion, JSP, JAVA, C, and so on.

Process Flow

The process for the Get Close Retailer API XML-RPC is summarized here:

  1. When the customer requests ship to store or in-store pickup from their shopping cart or a product detail page, make a request to the OMS XML-RPC server.
  2. The request includes the currency ID, the customer’s Zip Code, and part numbers of the items in the cart.
  3. The RPC authenticates the username and password and verifies the server and RPC name information.
  4. The server immediately responds with an XML package that contains information about available retailers close to the customer’s Zip Code. The package provides the retailer’s name, location, address, phone, and distance from the customer’s Zip Code, and specified Maximum Lead Time.
  5. Create an XML-RPC message that calls immediate.get_close_retailer and passes an array of the parameters listed in the table below that defines the data elements.
  6. Create an XML-RPC client that connects to the following server:

Programming the Cannot Ship Order API

Server and RPC Information

  1. Create an XML-RPC message that calls immediate.get_close_retailer and passes an array of the parameters listed in the table below that defines the data elements.
  2. Create an XML-RPC client that connects to the following server:
    • Server file name: /xmlAdvServer.php
    • Server address: xml.shopatron.com
    • Server port: 443

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
UserNameYesNonestring1OMS username (must be a valid and active user account with System Admin or Order Admin permission.
PasswordYesNonestring1Password for OMS user account.
ManufacturerIDYesNoneint1The OMS-assigned Manufacturer ID that order data is being requested from; find this in the OMS account.
CatalogIDYesNoneint1The OMS-assigned Catalog ID that order data is being requested from; find this in the OMS account.
CurrencyIDYesNoneint1The Currency Type for the order. These Currency Types are supported: 1 (US Dollar), 2 (Canadian Dollar), 3 (British Pound), 5 (German Euro), 6 (French Euro), 7 (Italian Euro), 8 (Spanish Euro), 9 (British Euro), and 10 (Dutch Euro).
Zip/Postal CodeYesNonestring1Zip or postal code for the shipping address.
CountryCodeYesNonestring12-character Country Code of the ship-to address for the order.
ShipTypeYesfiltersstring1The shipping type for the order. Acceptable values are sts (for ship to store) or ispu (for in-store pickup).
PartnumberBlockYesNonestruct1The part number portion of the package. Acts only as a container for a list of part numbers; indexed from 0.
DistanceOptionalNoneInt1Distance used in the radius calculation. The default value is “50”. The maximum value is “150”. Any Integer sent outside the range will be set to the default value.

Example Request

This example is a minimum XML-RPC message, with a single order of one item.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.get_close_retailer</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>138</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <int>1</int>
         </value>
      </param>
      <param>
         <value>
            <string>93401</string>
         </value>
      </param>
      <param>
         <value>
            <string>US</string>
         </value>
      </param>
      <param>
         <value>
            <string>sts</string>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <string>112233</string>
                  </value>
               </member>
               <member>
                  <name>1</name>
                  <value>
                     <string>SATDS5588d44dd789ffdd2B1</string>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

Example Responses

Unlike REST APIs, the XML-RPC APIs do not return HTTP status codes to indicate success or failure. On success, the RPC returns the OMS Order ID. On an error, the RPC returns a response message with the faultCode and faultString.

A full list of faultCode and faultString options can be found below:

CodeDescription
2Missing Part Numbers
3Invalid ShipType Parameter
4Missing Zip Code
5Missing Country Code
98Invalid Zip Code
99Invalid Authorization

Successful responses may look like the below sample:

<?xml version="1.0" encoding="UTF-8"?>
<methodresponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>RetailerID</name>
                           <value>
                              <int>42</int>
                           </value>
                        </member>
                        <member>
                           <name>LocationID</name>
                           <value>
                              <int>8003</int>
                           </value>
                        </member>
                        <member>
                           <name>Name</name>
                           <value>
                              <string>SLO Store</string>
                           </value>
                        </member>
                        <member>
                           <name>Address1</name>
                           <value>
                              <string>2074 Parker St</string>
                           </value>
                        </member>
                        <member>
                           <name>Address2</name>
                           <value>
                              <string>#100</string>
                           </value>
                        </member>
                        <member>
                           <name>Address3</name>
                           <value>
                              <string />
                           </value>
                        </member>
                        <member>
                           <name>City</name>
                           <value>
                              <string>San Luis Obispo</string>
                           </value>
                        </member>
                        <member>
                           <name>State</name>
                           <value>
                              <string>CA</string>
                           </value>
                        </member>
                        <member>
                           <name>Zip</name>
                           <value>
                              <string>93401</string>
                           </value>
                        </member>
                        <member>
                           <name>CountryCode</name>
                           <value>
                              <string>US</string>
                           </value>
                        </member>
                        <member>
                           <name>Latitude</name>
                           <value>
                              <double>35.2545</double>
                           </value>
                        </member>
                        <member>
                           <name>Longitude</name>
                           <value>
                              <double>-120.646</double>
                           </value>
                        </member>
                        <member>
                           <name>Phone</name>
                           <value>
                              <string>805-547-8368</string>
                           </value>
                        </member>
                        <member>
                           <name>Distance</name>
                           <value>
                              <double>0.523715</double>
                           </value>
                        </member>
                        <member>
                           <name>MaxLeadTime</name>
                           <value>
                              <double>30</double>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodresponse>

An error response includes an error code and reason:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value>
                  <int>2</int>
               </value>
            </member>
            <member>
               <name>faultString</name>
               <value>
                  <string>invalid username or password, or insufficient permissions</string>
               </value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Handling Errors

If an error response fault code is received after sending the order information to OMS, follow these steps:

  1. Record the outgoing package and the associated fault code response from OMS.
  2. Test for connectivity to the server.
  3. Hold the XML package for future transmission to OMs’s servers.
  4. Send an email to OMS Merchant Support; include the time and date of the failed transmission.
  5. When Kibo support staff responds, resend the failed attempts.