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.

Introduction

Introduction

This document describes the standard XML interfaces used by OrderFlow to support realtime data exchanges with external systems.

The authoritative version of this document is held in the Realtime Despatch version control system. The document is subject to continual change; please check the current version with OrderFlow before relying on the contents.

OrderFlow provides a sophisticated XML interface with third party systems, the interface provides the following functionality:

  • Searchable logs of all incoming and outgoing XML transactions
  • Event driven triggers and CRON type schedules for XML data exports
  • Configurable parsing of third party responses to identify application level errors
  • Automated retrying of failed transactions

OrderFlow also supports the import and export of information in CSV data files, either manually or as part of automated scheduled processes. The import and export of CSV files is not covered by this document.

Guidelines for API Implementation

The OrderFlow API has been designed around a number of basic assumptions about the way in which data will be exchanged with external systems. The purpose of these assumptions is to ensure that the interfaces are resilient in the event of system downtime and network failure. All integrators that use the OrderFlow API should design their implementations with these assumptions in mind.

System Availability

OrderFlow does not assume that external systems with which it communicates will always be available.

Similarly, implementation of the operations described in this document should make allowance for the possibility that OrderFlow will have short periods of downtime.

Receipt of Message Retries

For outgoing messages to third party systems OrderFlow has a retry mechanism to handle the situation in which message delivery cannot be confirmed within a specified time.

Messages that exceed the maximum number of retries are brought to the attention of an administrator who is responsible for assessing the business impact of the repeated failure and taking appropriate action.

The number of retries and the delay between each retry is designed to ensure that when an external system is slow to respond, OrderFlow does not immediately increase the load placed upon the external system by retrying too rapidly or too frequently.

Sending of Message Retries

Similarly, in order to ensure business continuity in the event of system downtime, third party systems interfacing with OrderFlow should include a mechanism for retrying messages which could not be delivered following the period of inavailability.

The recommended strategy is to retry delivery of messages at specified intervals. As with delivery from OrderFlow, if the message cannot be delivered after a configured number of retries, a mechanism should be in place which allows the third party system to alert the system administrator of this situation.

Order of Message Delivery

OrderFlow does not assume that incoming messages will always be received in the same order in which they were sent. Similarly, the use of message retries from OrderFlow means that the order of message delivery to third party systems cannot be guaranteed in every case.

Where the API contains information that allows the receiving system to identify that the data contained within a message has been made obsolete by a subsequent message, this obsolete message should be ignored. The OrderFlow to external system messages described in the section Operations FROM OrderFlow (PUSH) include a message id in each outgoing message, which can be used to determine the sequencing order of messages.

Idempotency

Third party systems which receive and trigger actions on the basis of notifications received from OrderFlow should be idempotent, in the sense that a second request to trigger an action that has already been completed should be ignored when appropriate.

The necessity for idempotent messages arises as a result of the retry mechanism. If a retry is triggered because a previous attempt to deliver a message timed out, the receiving system should be able to detect whether the retry message had in fact been received on the first attempt. It should not attempt to retry the action without taking into account the possibility that the action may have already been completed.

HTTP Authentication

The XML interface is password protected using HTTP BASIC authentication and/or custom authentication.

HTTP Basic Authentication

Implemented as described in RFC 2617 and on Wikipedia. Note that the security realm is "RTD", if this is required by the HTTP client. Custom Authentication is supported through the user and password which should be transferred using the HTTP request headers (user and password, respectively). The password should be base64 encoded. In both cases, communication is assumed to be via HTTPS, without which the security of these authentication schemes would be inadequate.

Channel and Organisation Authentication

In most environments it is necessary to authenticate a user by channel. For example, one channel might represent orders associated with a particular retailer from a shopping cart backed web site, and another might represent orders coming from that retailer's Amazon site. In order to facilitate channel authentication, the channel code needs to be passed to OrderFlow in all requests.

On OrderFlow, a channel will belong to an organisation. For this reason for some operations it is necessary to be authenticated at the organisation level.

For HTTP POST operations which involve posting a request body rather than a www-urlencoded form, the recommended usage is to pass the channel using a HTTP header named channel, and to pass in the organisation using a header named organisation.

For HTTP GET operations, the same mechanism is available, although it is also possible to pass the channel and organisation via HTTP request parameters in the query string itself. Note that if the channel or organisation is supplied both as request parameters and as headers, then the values will be taken from the respective request parameters.

Message Conventions

URL: The form of a URL used to connect to OrderFlow is shown below:

https://[host]/[instanceName]/[moduleName]/[messageName].xml

The host is the HTTPS URL associated with the server on which the OrderFlow application is running.

The instancename is simply the particular instance of OrderFlow on the host, and will be environment-specific.

The moduleName is the qualifier which points to the part of the application in which the functionality lies.

The messageName is the name of the particular message, and may consist of more than one segment (e.g. for imports, all URLs end with .xml).

From this point onwards only the last part of the URL is shown, from the module name onwards: /remoteorder/imports/importitems.xml

The first part of the URL will be specific to the instance of OrderFlow being addressed.

Capitalization: applies to both URLs as well as the contents of the messages themselves, that is, both elements and attributes.

  • First letter always begins with lower case.
  • After this, camel case is used. Each new word which is part of the same identifier starts with an upper case letter.
  • Hyphens and underscores are not used in XML elements or attributes. For example, and element containing the last modified date would be named lastModifiedDate rather than last-modified-date.

HTTP Operation types

PULL

PULL operations are invoked by the third party application (the client) on service interfaces published by OrderFlow.

These can be invoked by remote clients to OrderFlow. OrderFlow provides the endpoints to PULL operations.

See the Operations TO OrderFlow (PULL).

PUSH

PUSH operations are invoked by OrderFlow to push data to the third party application (the client), typically an e-commerce shopping cart application or accounts system.

For PUSH operations OrderFlow functions as the client in the interaction.

Push notifications can either be realtime or scheduled, or can be triggered by events on OrderFlow. For scheduled notifications, URLs and invocation schedule are configured per organisation or per channel for operation type.

The operations will involve notifications over a given period. The receiver is expected to either accept or reject the notification. If rejected, or if the notification target server is not available, then the same notifications will be attempted at the next notification schedule time. Push operation which involve posting of data are considered to have succeeded if the target server returns an error code of 200 or if the content of the acknowledgement returned by the client matches the rules defined in the remote message definition.

A note on existing third party APIs

As OrderFlow is not responsible for defining and hosting PUSH operations, the API operations as described below will only be applicable in certain circumstances. Specifically, developers can use this guide as a basis for implementing extensions to third party systems that interface with OrderFlow.

OrderFlow is also able to integrate using pre-existing APIs defined by other third party applications through a configurable integration framework. The details for this kind of integration are not described here. The current document covers only the 'generic integration' for PUSH operations.