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

Move RMA

Process product returns when items are received by using the Move RMA API. Use this API to:

  • Accept a return
  • Reject a return
  • Accept some returned items but reject others
  • Reopen a closed return

Clients who use the Move RMA API to process returned products often use the Create RMA API to initiate or accept return requests.

Getting Started

System Requirements

To use the Move 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 Move RMA, which assembles the XML package that initiates return processing on OMS servers. They will also need to write the Order Data Receive application, the XML-RPC server application used to receive the data. This is an XML-RPC server that OMS can call to send order data 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 Move RMA XML-RPC is summarized here:

  1. The Move RMA API makes a request for return request processing to the OMS XML-RPC Server. The request includes a username and password for authentication, and a requested action for the entire return or detailed information about all items included in the return request and a requested action for each of them.
  2. The RPC authenticates the username and password and verifies the server and RPC name information.
  3. Upon authentication, the server responds with a Return (RMA) Number and a success response or an error message and a fault code for the error.

Programming the Move RMA API

Server and RPC Information

  1. Create an XML RPC message that calls immediate.move_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: 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.
NumOrdersYesNoneint1The number of orders (returns) included in the package.
RMA BlockYesNonestruct1/RMAA container for information about an individual return. 0-indexed array that increments for each order. There is one Order Block for each order in the package.
RMAIDOptionalRMA Blockstring1/RMAThe RMA number issued by OMS for this return.
ActionOptionalRMA Blockstring0 or 1/RMAThe action to apply to the entire RMA: accept, reject, or reopen. If the RMA is reopened, any existing accepted or rejected status is cleared. Include this value if the same action is to be applied to all items in the return. If an action is specified, it will override any action specified for individual items.
ReturnLocationOptionalRMA Blockstring0 or 1/RMAExternal Store ID
ItemsOptionalRMA Blockstruct1/RMAA container for all item information in this return. 0-indexed array that increments for each item in the return. If the same action applies to all items in the return, item-level information does not have to be included.
Item BlockOptionalItemsstruct1/itemInformation on individual items in the return.
ItemIDOptionalItem Blockint1/itemThe internal OMS ID for this item.
QuantityOptionalItem Blockint1/itemThe number of items in the return to which the action is being applied. If the Quantity specified here is less than the number of items with this ItemID in the return, the opposite status is assigned to remaining items with this ItemID.
ActionOptionalItem Blockstring1/itemThe action to apply to these items: accept or reject. An individual item cannot be reopened; the user must reopen the RMA itself. Note that if an action is applied to the entire RMA, this value is ignored.

Example Requests

The same action (reopen) applies to all items in the RMA. Note that item-level information is not included.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immmediate.move_rma</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>ABC123DEF456</string>
         </value>
      </param>
      <param>
         <value>
            <int>1</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>RMAID</name>
                           <value>
                              <string>2444</string>
                           </value>
                        </member>
                        <member>
                           <name>Action</name>
                           <value>
                              <string>reopen</string>
                           </value>
                        </member>
                        <member>
                           <name>ReturnLocation</name>
                           <value>
                              <string>4445365852</string> 
                           </value>   
                        </member>  
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

In this sample, one item in a return is accepted, and the other is rejected.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immmediate.move_rma</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>ABC123DEF456</string>
         </value>
      </param>
      <param>
         <value>
            <int>1</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>0</name>
                  <value>
                     <struct>
                        <member>
                           <name>RMAID</name>
                           <value>
                              <string>2444</string>
                           </value>
                        </member>
                        <member>
                           <name>Items</name>
                           <member>
                              <name>0</name>
                              <value>
                                 <struct>
                                    <member>
                                       <name>ItemID</name>
                                       <value>
                                          <int>1585677</int>
                                       </value>
                                    </member>
                                    <member>
                                       <name>Quantity</name>
                                       <value>
                                          <int>2</int>
                                       </value>
                                    </member>
                                    <member>
                                       <name>Action</name>
                                       <value>
                                          <string>accept</string>
                                       </value>
                                    </member>
                                 </struct>
                              </value>
                           </member>
                           <member>
                              <name>1</name>
                              <value>
                                 <struct>
                                    <member>
                                       <name>ItemID</name>
                                       <value>
                                          <string>1585678</string>
                                       </value>
                                    </member>
                                    <member>
                                       <name>Quantity</name>
                                       <value>
                                          <int>1</int>
                                       </value>
                                    </member>
                                    <member>
                                       <name>Action</name>
                                       <value>
                                          <string>reject</string>
                                       </value>
                                    </member>
                                 </struct>
                              </value>
                           </member>
                        </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 matching the order struct passed in, but lists the next step for each order or an error message for each order. 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 number of parameters.
2Invalid username or password.
3Invalid type of parameters.
4Invalid username or password.

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>RMAID</name>
                           <value>
                              <int>2197725</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 insuffucient 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.