The main functionalities in the API are:
- Download orders from Fruugo (HTTP/XML)
- Confirm, ship, cancel and return items (HTTP)
- Download packing slips for printing (HTTP/PDF)
The normal process flow for receiving an order and shipping is quite simple:
Each section of the Order API is permitted to be used independently of all other sections. It provides the option of using the XML interface to only download orders, and then use the Fruugo Retailer Portal to carry out order status updates and the printing of packing slips. Authentication is handled with HTTP Basic - method.
The retailer’s system sends a HTTP request to Fruugo to request order information. The request parameters specify the time of the earliest and latest orders to retrieve as well as the authentication credentials of the retailer. The response from Fruugo contains the requested orders in XML format.
The API is stateless, i.e. it doesn’t track which orders the retailer system has already downloaded.
Depending on the payment method, order value and other additional factors, Fruugo checks the payment status with the payment service provider (PSP) and evaluates the fraud risk of each order. These checks are done before Fruugo releases the order to the retailer through the API (or in the Retailer Portal).
Some payment methods (PSPs) have occasional delays in their processing and that, combined with the stateless nature of the service, has an effect on how Fruugo can process and forward the orders. Therefore the start date and end date of the Order Data Feed used to select orders is based upon the time the order successfully passes the Fraud Checks, not the time that the customer places the order.
Benefits of the chosen approach are:
- The API gives only “checked and paid” complete orders. Once an order has been release no extra lines will appear in a later download.
- The API provides full view to the current order data including the status of each order and each of it’s lines. For example Monday morning orders can be retrieved on Monday as well as on Thursday. The XML that is generated on Monday contains new unprocessed lines (status pending). If the same orders are retrieved on Thursday the same line items probably have status “confirmed” or “shipped”.
- If the retailer system succeeds in downloading the XML but then fails to process it, the API can be called again as many times as needed.
The downside is:
- The API doesn't provide a service to "get only the new orders that have not been transferred before".
For example:
- Customer places order 108 at 1:30pm.
- API is called at 3 pm to get orders between 1 pm and 2 pm -> the result is orders 100, 105 and 110.
- At 3:30 pm Fruugo releases order 108 to the retailer.
- API is called at 4 pm with the same time parameters -> the result is orders 100, 105 and 110.
- API is called at 5 pm to get orders between 3 pm and 5pm -> the result is orders 108.
Here is an example logic for a simple integration. First some assumed business rules:
Every four hours the retailer system runs a batch job that downloads the orders for the previous 4 hour period.
The retailer's system processes the orders in the XML data and:
- Skips all orders that have a status other than ‘PENDING’ (the other ones have already been processed fully or partially and thus they must already exist in the retailer system)
- Checks if an order with ‘PENDING' status in the XML already exists in the retailer system. If it doesn’t then it is stored in the retailer system. Otherwise it can be skipped.
Common data formats used in the API