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

Shipment Data Upload

Use the Shipment Data Upload Tool API to enter the shipment information for orders. This API transfers all pertinent shipment data, including carrier and tracking numbers for each order.  With it, the user can:

  • Upload shipment data any time, 24 hours a day, 7 days a week.
  • Upload modified shipment data multiple times in a day if needed.

Fulfillment partners can use this API to enter their shipment data when they fulfill orders (with permission).

Getting Started

System Requirements

To use the Shipment Data Upload Tool API, the user needs a valid, active OMS user account with Admin All Access or Order Admin permission. If the user account is ever deactivated, the Shipment Data Upload Tool API will cease to function correctly.

Other requirements are:

  • A server with Internet access that can communicate with OMS’s server.
  • The ability to send the shipment data via a Remote Procedure Call (RPC). This may be via a script run by a scheduling service, via a button on a page, and so on.

Writing the Application

The client needs to write the Shipment Data Upload Tool application. This application gathers the shipment data from the client’s system and generates an XML package. It uses an RPC to pass the package to the OMS server.

If authentication is successful, the shipment data is processed and entered into the OMS system and returns a success response code for each shipment. If authentication is not successful, then a response code with an error message is returned for each shipment.

The Shipment Data Upload Tool application can be written in any programming or scripting language that can handle an RPC, including: PHP, ASP, Cold Fusion, JSP, JAVA, C, and so on.

Process Flow

The process for the Shipment Data Upload Tool XML-RPC occurs as summarized here and as depicted in Figure 1, below:

  1. Send an XML package with the shipment data to the OMS XML-RPC server.
  2. The RPC authenticates the username, password, and permissions, and verifies the contents of the XML package.
    • If authentication is successful, the shipment data and all tracking numbers are validated, and the data is processed and entered into the OMS system.
  3. Receive a response code for every shipment.
    • If the upload was successful, the response code is 0.
    • If it was not, the response code is one of those defined in the table, below, showing request response codes. The response also includes an error message that describes the error.
    • When data is sent for multiple shipments, the response is an array of responses and a response code is included for every shipment.

About Tracking Number Validation

If a package is split into multiple shipments, provide a tracking number for each shipment. Up to five tracking numbers can be entered for a package.

The OMS system validates the tracking numbers using rules provided by the various carriers (such as UPS or FedEx).

If a tracking number is entered that does not validate with our system, OMS tries to validate it on the carrier’s system.

If OMS cannot validate the number, it will send an invalid tracking number response code for the shipment and the shipment data is not entered in OMS. If this happens, try to verify the tracking number with the tracking tool on the carrier’s website. If this does not work, enter the shipment and tracking numbers using the OMS user interface.

See the chart in the OMS Standards guide for details about formatting tracking numbers.

Programming the Request Orders API

Server and RPC Information

  1. Create an XML-RPC message that calls examples.xml_upload_shipment_data and passes an array of the parameters that follow (refer to the sample below).
  2. Create an XML-RPC client that connects to the following server (refer to the sample below):
    • Server file name: xmlServer.php
    • Server address: xml.shopatron.com
    • Server port: 443 (HTTPS; default is 80)

Required and Optional Parameters

There are a number of possible XML package elements:

ElementRequiredParent ElementTypeOccursDescription
usernameYesNonestirng1OMS username. Must be a valid and active user account with System Admin or Order Admin permissions. The maximum length is 50.
passwordYesNonestring1OMS user account password. The maximum length is 50.
num_shipmentsYesNoneint1Number of shipments included.
shipment_xOptionalNonestructnData for one shipment. Include one shipment_x struct for each shipment. Number them shipment_1, shipment_2, etc.
order_idYesshipment_xint1/shipmentOMS-assigned Order ID (also called the “Order Number”).
shipment_idYesshipment_xint1/shipmentShipment_id for the shipment. This value was passed in the XML order data that was received using the Ready Order Download API.
extra_idOptionalshipment_xstring1/shipmentExtra field that can be passed as an internal reference number. The maximum length is 20.
num_boxesYesshipment_xintnNumber of boxes in the shipment.
boxesOptionalshipment_xstruct0/1Boxes container. Include only for multiple boxes. Data for each package is in a box_x struct, where x is replaced by a number (box_1, box_2, etc.).
box_xOptionalboxesstructnContainer for one of the boxes. Include only for multiple boxes.
carrierYesshipment_x (for single- box shipments) or box_x (for multi-box shipments)string1/boxCarrier. Value must be one of the following: DHL, FedEx, UPS, USPS, or Other (please specify).
tracking_numYesshipment_x (for single- box shipments) or box_x (for multi-box shipments)string1/boxTracking number.
transit_timeYesshipment_x (for single- box shipments) or box_x (for multi-box shipments)string1/boxEstimated transit time. Value must be one of the following: 1-2 days, 3-5 days, 5-7 days, 7-10 days, or 11+ days.
test_modeOptionalNoneint0/1Only included for testing; value may be any defined response code.
disable_emailsOptionalNoneint0/1This disables the shipment confirmation emails from being sent by OMS.

Example Request

This request is a sample of a single shipment.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>examples.xml_upload_shipment_data</methodName>
   <params>
      <param>
         <value>
            <string>joeuser</string>
         </value>
      </param>
      <param>
         <value>
            <string>Joe123</string>
         </value>
      </param>
      <param>
         <value>
            <int>1</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>shipment_1</name>
                  <value>
                     <struct>
                        <member>
                           <name>order_id</name>
                           <value>
                              <int>1234567</int>
                           </value>
                        </member>
                        <member>
                           <name>shipment_id</name>
                           <value>
                              <int>100001</int>
                           </value>
                        </member>
                        <member>
                           <name>num_boxes</name>
                           <value>
                              <int>1</int>
                           </value>
                        </member>
                        <member>
                           <name>carrier</name>
                           <value>
                              <string>UPS</string>
                           </value>
                        </member>
                        <member>
                           <name>tracking_num</name>
                           <value>
                              <string>1Z1234567890123456</string>
                           </value>
                        </member>
                        <member>
                           <name>transit_time</name>
                           <value>
                              <string>1-2 days</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
   </params>
</methodCall>

In this example, multiple shipments are being processed.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>examples.xml_upload_shipment_data</methodName>
   <params>
      <param>
         <value>
            <string>juser</string>
         </value>
      </param>
      <param>
         <value>
            <string>juser1</string>
         </value>
      </param>
      <param>
         <value>
            <int>2</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>shipment_1</name>
                  <value>
                     <struct>
                        <member>
                           <name>order_id</name>
                           <value>
                              <int>1234567</int>
                           </value>
                        </member>
                        <member>
                           <name>shipment_id</name>
                           <value>
                              <int>100001</int>
                           </value>
                        </member>
                        <member>
                           <name>num_boxes</name>
                           <value>
                              <int>1</int>
                           </value>
                        </member>
                        <member>
                           <name>carrier</name>
                           <value>
                              <string>UPS</string>
                           </value>
                        </member>
                        <member>
                           <name>tracking_num</name>
                           <value>
                              <string>1Z1234567890123456</string>
                           </value>
                        </member>
                        <member>
                           <name>transit_time</name>
                           <value>
                              <string>1-2 days</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
               <member>
                  <name>shipment_2</name>
                  <value>
                     <struct>
                        <member>
                           <name>order_id</name>
                           <value>
                              <int>1234568</int>
                           </value>
                        </member>
                        <member>
                           <name>shipment_id</name>
                           <value>
                              <int>100002</int>
                           </value>
                        </member>
                        <member>
                           <name>extra_id</name>
                           <value>
                              <string>102938</string>
                           </value>
                        </member>
                        <member>
                           <name>num_boxes</name>
                           <value>
                              <int>2</int>
                           </value>
                        </member>
                        <member>
                           <name>boxes</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>box_1</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>carrier</name>
                                             <value>
                                                <string>FedEx</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>tracking_num</name>
                                             <value>
                                                <string>12345678</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>transit_time</name>
                                             <value>
                                                <string>1-2 days</string>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>box_2</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>carrier</name>
                                             <value>
                                                <string>USPS</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>tracking_num</name>
                                             <value>
                                                <string>12345678901234567890</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>transit_time</name>
                                             <value>
                                                <string>6-8 weeks</string>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
   </params>
</methodCall>

Example Responses

Unlike REST APIs, the XML-RPC APIs do not return HTTP status codes to indicate success or failure. If no shipments are passed, the RPC returns 0. If any shipments are passed in a batch, the response returns an array with response codes for each shipment. A full list of faultCode and faultString options can be found below:

CodeDescription
0Success. Shipment info for all orders received.
1Blank or invalid XML message.
2Invalid username or password, or insufficient permissions.
3Data uploaded does not match a valid OMS order.
4Shipment Data is missing.
5Invalid tracking number.
6Unspecified error.

An example response for a single-shipment upload:

<?xml version="1.0" encoding="UTF-8"?>
<!--
This response is for a Single shipment upload that is successful.
-->
<methodResponse>
   <params>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
   </params>
</methodResponse>

This example response for a multi-shipment upload includes a successful response and an error:

<?xml version="1.0" encoding="UTF-8"?>
<!--
This response is for a multiple shipment upload that has one success and one failure.
-->
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>shipment_id</name>
                           <value>
                              <int>100001</int>
                           </value>
                        </member>
                        <member>
                           <name>response</name>
                           <value>
                              <int>0</int>
                           </value>
                        </member>
                        <member>
                           <name>message</name>
                           <value>
                              <string>Success</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
               <member>
                  <name>1</name>
                  <value>
                     <struct>
                        <member>
                           <name>shipment_id</name>
                           <value>
                              <int>100002</int>
                           </value>
                        </member>
                        <member>
                           <name>response</name>
                           <value>
                              <int>5</int>
                           </value>
                        </member>
                        <member>
                           <name>error_message</name>
                           <value>
                              <string>Invalid tracking number. UPS server: UPS Tracking#1Q Error 150022 Invalid tracking number length</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</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.

PHP Code Sample

This example shows how a XML-RPC for PHP call would be done with Shipment Upload.

<?php
// these includes are shown as examples.
// The two xmlrpc include files are part of XML-RPC for PHP
include_once("../include/xmlrpc.inc");
include_once("../include/xmlrpcs.inc");
$username      = "joeuser";
// put in your Kibo username
$password      = "Joe123";
// put in your password
$num_shipments = 0;
// variable for counting shipments
// the request message
$xml_request   = new xmlrpcmsg('examples.xml_upload_shipment_data', array(
    new xmlrpcval($username, 'string'),
    new xmlrpcval($password, 'string'),
    new xmlrpcval($test_mode, 'int')
), 'array');
// set up client and connect with the OMS XML RPC server
$server        = new_xmlrpc_client('/xmlServer.php', 'www.shopatron.com', 443);
// $server->setDebug(1);
// get data and send either single shipment or batch of shipments
$xml_request   = get_shipment_data();
// start page or method
echo "<html><body>
Requesting Shipment Data Upload...<br>";
// this is the code that sends the request and gets the response
$result = $server->send($xml_request, 20, 'https');
// process the result
if (!$result) {
    // the result has not been returned
    $err_msg = "No response returned from RPC.";
} else if ($result->faultCode()) {
    // the result has been returned but there is an error
    $err_msg = "<p>XML-RPC Fault #" . $result->faultCode() . ": " . $result->faultString();
} else {
    // the result has been returned
    if ($value->kindOf() == 'struct') {
        // multiple responses
        $response_ary = Array();
        // for each shipment
        while (list($key, $shipment) = $value->structeach()) {
            $xml_response_ary = $shipment->scalarval();
            foreach ($xml_response_ary as $key2 => $value2) {
                // get shipment_id
                if ($key2 == "shipment_id") {
                    $response_ary[$key]['shipment_id'] = $value2->scalarval();
                } else if ($key2 == "response") {
                    $shipment_ary[$key]['response_code'] = $value2->scalarval();
                } else if ($key2 == "message" || $key2 == "error_message") {
                    $shipment_ary[$key]['message'] = $value2->scalarval();
                }
            }
            // end for
        }
        // end while
    } else {
        // single response
        $value    = $result->value();
        $response = $value->scalarval();
    }
}
// check response codes and take appropriate action
print_r($response);
print_r($response_ary);
echo '
</body>
</html>';
?>