Skip to content

OrderFlow API Documentation

OrderFlow Ltd.

Document Version: 4.2.4

Document Built: 2024-02-16

This document and its content is copyright of OrderFlow Ltd. All rights reserved.
You may not, except with our express written permission, distribute, publish or commercially exploit the content.
Any reproduction of part or all of the contents in any form is prohibited.

HTTP Example

HTTP Example

An example HTTP request response pair shows how HTTP is used in the Product Import operation, described in in the next section.

Note that in this example, the XML is passed in the body of the HTTP POST. In other POST operations, such as the Order Cancellation operation, the body will consist of request parameters as URL encoded name value pairs.


POST /rtd2-host/remoteorder/imports/importitems.xml HTTP/1.1
channel: MYCHANNEL
user: philz
password: cGhpbHo=
User-Agent: Jakarta Commons-HttpClient/3.1
Content-Length: 967

<?xml version="1.0" encoding="UTF8"?>
  <import type="product" operation="insert" externalReference="TEST_fullproduct">
    description=A description for the test product
    userDefined1=User defined field value 1
  <import type="product" operation="insert" externalReference="TEST_min_product">
    description=A description for the min product
  <import type="product" operation="insert" externalReference="TEST_global_product">
    description=A description for the global product

Note how the channel external reference is passed in using the channel header.

In the example above the user name and password (in this case philz) are passed as headers, with the password being Base64 encoded. The other authentication method uses HTTP Basic Authentication (as described on Wikipedia). In this case, the user name and password headers would be replaced by the following:

Authorization: Basic cGhpbHo6cGhpbHo=

where cGhpbHo6cGhpbHo= is the base Base64 encoding of philz:philz.

Below we show both the normal and the error response to a this request.


Normal Response

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(6.1.14)

<?xml version="1.0" encoding="UTF-8"?>
    <import type="product" operation="insert" externalReference="TEST_fullproduct"
      entity="rtd.domain.database.Product" item="TEST_fullproduct"
      queryTime="2014-09-28 20:32:34.620" />
    <import type="product" operation="insert" externalReference="TEST_min_product"
      entity="rtd.domain.database.Product" item="TEST_min_product"
      queryTime="2014-09-28 20:32:34.636" />
    <import type="product" operation="insert" externalReference="TEST_global_product"
      entity="rtd.domain.database.Product" item="TEST_global_product"
      queryTime="2014-09-28 20:32:34.658" />

Notice how the result is returned in the body of the HTTP request, normally in XML format.

Error Response

HTTP/1.1 500 Internal Server Error
Content-Language: en-US
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(6.1.14)

<?xml version="1.0" encoding="UTF-8"?>
     <![CDATA[Cannot authenticate &apos;MYCHANNEL&apos;. 
        Does not match list of authenticated channel]]></message>
       <![CDATA[Cannot authenticate &apos;MYCHANNEL&apos;. 
        Does not match list of authenticated channel(rtd ...]]>

For most of the operations, an error which prevents successful completion of the operation results in a HTTP response with a non-200 response code. In this case, more details can be extracted from the message and detail elements.

Error Responses

When an error occurs in one of the XML operations, OrderFlow will respond in a standard way. Typically, it will return a non 200 HTTP return code. For example, if the user is not authenticated then a 401 return code will be returned. If the server is unable to complete the request due to some other application error, a 500 return code will be returned.

OrderFlow will return error text in the following format:

<?xml version="1.0" encoding="UTF-8"?>
  <message>high level error message</message>
  <detail>stack trace of error message</detail>

Error text is generated dynamically, with the intention being to return meaningful text that will help diagnose and correct problems. This approach means that it is not possible to provide an exhaustive list of errors that may be returned by the API.

Examples of the most common errors found in the element of are API response are given below.

HTTP Code Error Text Explanation
HTTP 500 Internal Server Error Unable to load XML document from resource The message structure or XML content cannot be parsed, check the XML formatting.
HTTP 500 Internal Server Error Expecting value for 'channel' request header or parameter The channel value was not found in the HTTP request header
HTTP 500 Internal Server Error Cannot authenticate 'channelexample' Does not match list of authenticated channel The channel contained in the HTTP request header is not valid
HTTP 412 Precondition failed No user for supplied user name and password combination Username / password combination is invalid
HTTP 200 Duplicate entity in import of order with reference: 03340002 Rejected instance rtd.domain.database.OrderItem with reference '03340002'. The order '03340002' already exists for the channel
HTTP 200 No product found for external reference: WRONGPRODUCT. If this product is present, make sure that it has been activated. A product code contained within the order is unrecognized
HTTP 200 Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Double' for property 'totalPriceGross' nested exception is java.lang.NumberFormatException For input string: '19t6.99' The value 'totalPriceGross' could not be stored as a numeric value
HTTP 200 Unable to find any entity associated with identifier:ref:courier:worldship The courier identifier “worldship” does not exist or is inactive