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

Create RMA

Use the Create RMA API to automate the return initiation process. The user can also accept returns with this API. Most of Kibo’s clients who use the Create RMA API to initiate returns use the Move RMA API to process product returns when they receive them.

Getting Started

System Requirements

To use the Create RMA API, there should be a server with Internet access that runs the client’s shopping cart software to gather the order data.

Writing the Application

The client needs to write the Immediate Create RMA application. This application assembles an XML package to request merchant Return (RMA) Numbers from OMS servers.

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 OMS Create RMA API XML-RPC is summarized here:

  1. The Create RMA API issues a return request to the OMS XML-RPC Server. The request includes a user name and password for authentication, detailed information about all items included in the RMA, and, optionally, a requested action.
  2. The RPC authenticates the user name and password and verifies the server and RPC name information.
  3. Upon authentication, the server responds with a return number for the order.

Programming the Create RMA API

Server and RPC Information

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

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
UserNameYesNonestring1A valid and active OMS user name with correct permissions.
PasswordYesNonestring1The password for the user account.
NumOrdersYesNoneint1The number of orders being submitted for return requests.
Request BlockYesNonestruct1A container for all order information. 0-indexed array that increments for each order.
Order BlockYesRequest Blockstruct1/orderUnnamed holder for individual order information. There is one Order Block for each order in the package.
OrderIDYesOrder Blockint1/orderThe Order ID that was provided by the OMS system when the order was placed.
ShipmentIDYesOrder Blockint1/orderThe Shipment ID that was provided by the OMS system when the order was placed.
ActionOptionalOrder Blockstring1/orderThe initial action to be applied to all items in the returned order. Acceptable values are: Open and Accept. If no action is specified, the default is Open. Include an action of Accept to automatically accept the items in the returned order.
ReturnLocationOptionalOrder Blockstring1/orderExternal Store ID
ItemsYesOrder Blockstruct1/orderA container for all item information in this return.
Item BlockYesItemsstruct1/itemA container for information about an individual item in the return. 0-indexed array that increments for each order. There is one Item Block for each item in the returned order.
ItemIDYesItem Blockint1/itemThe internal OMS ID for this item.
QuantityYesItem Blockint1/itemThe quantity of this specific item in the return.

Example Requests

The first example is a minimal XML-RPC message.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.create_rma</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>1</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>OrderID</name>
                           <value>
                              <int>1234567</int>
                           </value>
                        </member>
                        <member>
                           <name>ShipmentID</name>
                           <value>
                              <int>585677</int>
                           </value>
                        </member>
                        <member>
                           <name>Items</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>0</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>ItemID</name>
                                             <value>
                                                <string>7654321</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>Quantity</name>
                                             <value>
                                                <int>1</int>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

This request contains all of the elements.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.create_rma</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>2</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>OrderID</name>
                           <value>
                              <int>1585677</int>
                           </value>
                        </member>
                        <member>
                           <name>ShipmentID</name>
                           <value>
                              <int>585677</int>
                           </value>
                        </member>
                        <member>
                           <name>Action</name>
                           <value>
                              <string>accept</string>
                           </value>
                        </member>
                        <member>
                           <name>ReturnLocation</name>
                           <value>
                             <string>44325648</string> 
                           </value> 
                        </member>  
                        <member>
                           <name>Items</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>0</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>ItemID</name>
                                             <value>
                                                <string>1585677</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>Quantity</name>
                                             <value>
                                                <int>2</int>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>1</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>ItemID</name>
                                             <value>
                                                <int>1585678</int>
                                             </value>
                                          </member>
                                          <member>
                                             <name>Quantity</name>
                                             <value>
                                                <int>1</int>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
               <member>
                  <name>1</name>
                  <value>
                     <struct>
                        <member>
                           <name>OrderID</name>
                           <value>
                              <string>2197491</string>
                           </value>
                        </member>
                        <member>
                           <name>ShipmentID</name>
                           <value>
                              <string>975587</string>
                           </value>
                        </member>
                        <member>
                           <name>Items</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>0</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>ItemID</name>
                                             <value>
                                                <string>2076115</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>Quantity</name>
                                             <value>
                                                <int>0</int>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>1</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>ItemID</name>
                                             <value>
                                                <string>2076116</string>
                                             </value>
                                          </member>
                                          <member>
                                             <name>Quantity</name>
                                             <value>
                                                <int>2</int>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </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 a struct containing return request information for each order package passed. 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
1Invalid type of parameters.
2Invalid username or password.
3No orders to process.

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>OrderID</name>
                           <value>
                              <int>2197725</int>
                           </value>
                        </member>
                        <member>
                           <name>ShipmentID</name>
                           <value>
                              <int>975644</int>
                           </value>
                        </member>
                        <member>
                           <name>RMAID</name>
                           <value>
                              <int>23763</int>
                           </value>
                        </member>
                        <member>
                           <name>Response</name>
                           <value>
                              <int>0</int>
                           </value>
                        </member>
                        <member>
                           <name>ErrorMessage</name>
                           <value>
                              <string />
                           </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.