Ecommerce API

Introduction

Ecommerce API provides a programmatic way to communicate with AspireSoft E-commerce system. At this moment following features are supported:

• Orders download

Communication with API is done via the HTTP protocol, using the standard HTTP POST method.

Gaining access

Creating an API user

We recommend you create a separate access group and the user to access your API. Grant Ecommerce API access right to this user in Access Rights / Ecommerce / API access section of administration.

Gateway URL

Ecommerce API gateway is located under http://www.example.com/scripts/ecs/api/gate.php

We highly recommend using HTTPS access schema under the production environment.

Understanding a Protocol

Request

These are the common fields that should be included in all requests. Each API call then have additional parameters.

• login - login of the API user you have created
• password - password of the API user you have created
• op - API operation

For example:

POST /scripts/ecs/api/gate.php HTTP/1.1 

Host: www.example.com 

login=ecs.api&password=k3ff3RT&op=fetchOrders

Response

Response is delivered in the XML format. Response has the following format:

<response schema-version="1.0" status="success|error" code="200|4xx|5xx"> 
<!-- response body --> 
</response>

Code of the successful response is always 200. Unsuccessful responses may have codes from 400 to 599, similar to the HTTP response codes.

In case of the errorneous response, response body has an element called <message> that includes explanation of the error. For example:

<response schema-version="1.0" status="error" code="404">
message>Operation unknown</message> 
</response>

Alternatively you may check the HTTP status code of the response, which copies the response status.

API Calls

Fetch Orders

This API call is to be used to download orders from the ecommerce.

Request

Following request variables are available:

fromID - gets you all orders from the given ID forward
toID - gets all orders from the given ID backwards
fromDate - gets you all orders from the given date forward
toDate - gets you all orders from the given date backwards
page - page number in case of the chunked response (see below).

Preferred date format for the requests is YYYY-MM-DD HH:MM:SS.

Example 1: Gets you a first chunk of all orders

POST /scripts/ecs/api/gate.php HTTP/1.1 
Host: www.example.com 

login=ecs.api&password=k3ff3RT&op=fetchOrders

Example 2: Gets third chunk of the orders that were made after 1/1/2011

POST /scripts/ecs/api/gate.php HTTP/1.1 
Host: www.example.com 

login=ecs.api&password=k3ff3RT&op=fetchOrders&fromDate=2011-1-1&page=3

Example 3: Gets order with ID=12345678

POST /scripts/ecs/api/gate.php HTTP/1.1 
Host: www.example.com 

login=ecs.api&password=k3ff3RT&op=fetchOrders&fromID=12345678&toID=12345678

Response

Response contains <orders> element, which includes multiple <order> elements.

<response schema-version="1.0" status="success" code="200">
<orders> 
<order id="629145605"> 
<!-- ORDER XML DATA --> 
</order> 
<order id="629145606"> 
<!-- ORDER XML DATA --> 
</order> 
<!-- etc --> 
</orders> 
</response>

If you are requesting for too many orders, response is getting chunked, asking you to repeat a request with the page variable. In this case, <orders> element gets 2 additional attributes @pages (total number of chunks) and the @current-page (a current chunk number, starting from 1)

<response schema-version="1.0" status="success" code="200"> 
<orders pages="5" current-page="1"> 
<order id="629145605"> 
<!-- ORDER XML DATA --> 
</order> 
<order id="629145606"> 
<!-- ORDER XML DATA --> 
</order> 
<!-- etc --> 
</orders> 
</response>

There can be an exceptional situation when order failes to be xmlized. In this case order element has a @status=error. Such orders should be skipped from import and to be resolved individually (caused by DB inconsistencies or errors).

<response schema-version="1.0" status="success" code="200"> 
<orders pages="5" current-page="1"> 
<order id="629145605"> 
<!-- ORDER XML DATA --> 
</order> <order id="629145606"> 
<!-- ORDER XML DATA --> 
</order> <order id="629145607" status="error"> 
<message>Invalid or non existing entity ID</message> 
</order> 
</orders> 
</response>