e-commerce CastorRetail API

e-commerce CastorRetail API

Introduction

This document describes the RESTFul interface for the CástorRetail software and all its functionality. The URI and HTTPS methods will be described, as well as the JSON data structures used for the data exchange.

Global architecture

The CástorRetail interface includes two different technologies:

  1. RESTful services accessed by HTTPS operations.
  2. JSON for the data exchange.

The interface supports the following entities:

  • Customers: allows two types of operations:
    • Login: for customer authentication with an user name and password.
    • Management: customer creation and modification.
  • Orders: allows to insert new customer orders in CástorRetail, and to check the state of the order.
  • Stock: it is allowed the check the stock of an article or all the articles available.
  • Articles: allows the get the information of an article and the list of all the article references available for the web application.
  • Images: allows the get the information of the images for an article.

There is also an export system for sending new information about articles, prices, images and stocks to the web system in real time. The information is sent in JSON format, and it is required for the web system to implement a RESTful server to receive this information.

For all the RESTful services and export systems it is included an identifier of the web system. CástorRetail supports more than one web system in the same services, and the information it returns and export depends on that identifier.

For the RESTful services it is also included information about the services version. If the JSON information of the services is changed in the future the version will be incremented, keeping the previous version for the currently integrated web systems which do not want to update their services.

Customers

Authentication

The authentication is a two steps process. First of all a POST method has to be sent for creating a new session.

POST https://www.web.com/rest/{version}/{client}/login/

These are the field in the form to send:

Field Type Required Description Example
session Text Yes The session id to create. It has to be a timestamp generated in the client and it has to be unique for this client. 1435683090941
login Text Yes The user name. johndoe
password Text Yes The password of the user. mypassword

The second step is to get the session created in the first step.

GET https://www.web.com/rest/{version}/{client}/login/{session}

A JSON object will be returned with the session information:

Field Type Required Description Example
ok Boolean Yes Indicates if the session exists and is ok. true
message Text No If the session is not ok the error message will be shown in this field. There is no user with the given login and password.

Management

It is possible to create, or modify customers, and to get all the information about a customer.

The customer creation can be done with a POST method:

POST https://www.web.com/rest/{version}/{client}/customers/

A Customer object has to be sent with the following fields:

Field Type Required Description Example
login Text Yes The customer reference, which has to be unique. It has to be the customer login. johndoe@mail.com
firstName Text Yes The customer first name. John
surname1 Text No The customer family name. Doe
surname2 Text No The second surname, if available.
email Text Yes The email of the customer. johndoe@mail.com
phone Text Yes The customer phone. 912223344
mobile Text No The customer mobile phone. 666555444
document Text No The customer identification number. For example the NIF in Spain. EX-121212
gender Text Yes The customer gender, it can be MALE, FEMALE or COMPANY MALE
privacyStatus Number Yes The selected privacy policy for the customer:

  • 0: customer accepts marketing information from the company.

  • 1: customer does not accept marketing information from the company.

  • 2: customer accepts marketing information from the company and third companies.

0
address Address[] No The customer addresses. At least one is required.
country Text No The code Iso3166Alpha2 of the customer’s country FR
webPassword Text No The customer web password 12345
fidelityCardNumber Text No The customer fidelity card number 1234567890
properties Property[] No Additional customer properties

Address objects structure.

Field Type Required Description Example
reference Text Yes The address reference, unique for the customer. WA
name Text Yes Name for this address. Work address
street Text Yes The customer address street. Other fields are not mandatory if they are included here (number, floor, door and stair). Gran Via.
number Text No The customer address number. 27
floor Text No The customer address floor.
door Text No The customer address door. A-B-C-D
stair Text No The customer address stair. None
city Text Yes The customer address city. Madrid
region Text Yes The customer address region. Madrid
country Text Yes The customer address country. Spain
zipCode Text Yes The customer zip code. 28014
phone Text No The phone number for this address. 666555444

Property objects structure.

Field Type Required Description Example
reference Text Yes Property reference BIRTHDAY
name Text Yes Property name Birth date
value Text Yes Property value 01-jun-16

A JSON response will be returned with the following fields:

Field Type Required Description Example
ok Boolean Yes Indicates if the customer has been created successfully. true
message Text No If the cold not be created the error message will be shown in this field. There is already a customer with the given login.

A customer can also be modified with a PUT method:

PUT https://www.web.com/rest/{version}/{client}/customers/{login}

The form to send is the same of the creation method, and the JSON response has also the same fields.

You can also get the customer information given its login.

GET https://www.web.com/rest/{version}/{client}/customers/{login}

The JSON response will be a Customer object.

Orders

New customer orders can be injected in CástorRetail with a POST method

POST https://www.web.com/rest/{version}/{client}/orders/

A JSON Order object has to be sent with the order information:

Field Type Required Description Example
reference Text Yes The identification of the order. 1
customer Customer Yes The order’s customer. It will be created if there is no customer for the given customer login, or updated with the given fields if it exists.
address Address Yes The address where the order will be served. It will be created if there is no address for the customer with the given address reference or updated with the given fields if it exists.
observations Text No Observations for the order. Please, it is urgent!
payment Payment No Information about the order paymeny.
lines OrderLine[] Yes List of lines for the order.

The Customer and Address objects are defined in the customers Management section.

Payment objects structure:

Field Type Required Description Example
method Text Yes Payment method used. PayPal
transaction Text Yes ID of the transaction, usually related to the payment method used. 223123123
amount Text Yes Amount paid. 99.90

OrderLine objects structure:

Field Type Required Description Example
reference Text Yes Article reference 001010101001
quantity Decimal Yes Quantity of articles in this line. 10.0
discount Decimal No Discount percent applied in the line, from 0 to 100. 0.0
price Decimal Yes Unit price of the article, including taxes. 9.99
amount Decimal Yes Line total amount, including taxes and discounts. 99.90

The state of an order can be checked with a GET method:

GET https://www.web.com/rest/{version}/{client}/orders/{reference}

A JSON OrderState object is returned with the information of the order state:

Field Type Required Description Example
reference Text Yes The order reference. CO_001
state Text Yes Description of the order state. Sent to the customer
date Datetime Yes Date when the order changed to this state. 2015-12-03T09:00:00

Stock

It is possible to get the stock of an article giving its reference with a GET method:

GET https://www.web.com/rest/{version}/{client}/stocks/{reference}

A JSON Stock object will be returned with the following fields:

Field Type Required Description Example
reference Text Yes Article reference 0010010101
stock Decimal Yes Available stock (in total) quantity for the article. 160
enabled Boolean Yes Indicates if it is allowed to sell the article with the available stock quantity. True
store Store[] No List of stores which stock is informed.

Store object structure

Field Type Required Description Example
reference Text Yes Store reference. S01
name Text Yes Store name. MADRID VAGUADA
stock Decimal Yes Available stock quantity in this store.
warehouses Warehouse[] No List of store warehouses which stock is informed.

Warehouse object structure

Field Type Required Description Example
reference Text Yes Warehouse reference. AVAILABLE
name Text Yes Warehouse name Available warehouse
stock Decimal Yes Available stock quantity in this warehouse. 12.0

Articles

It is possible to get a list of all the articles IDs available for the web system with a GET method, without specify any article id:

GET https://www.web.com/rest/{version}/{client}/articles

A JSON object will be returned with the following fields:

Field Type Required Description Example
articles Text[] Yes List of article reference.

It is also possible to get all the information about an article providing its ID.

GET https://www.web.com/rest/{version}/{client}/articles/{reference}

A JSON Article object will be returned with the following fields:

Field Type Required Description Example
reference Text Yes The article reference. 0010100102
dim1 Text No Dimension 1 value. Red
dim2 Text No Dimension 2 value XL
dim3 Text No Dimension 3 value
dim4 Text No Dimension 4 value
dim5 Text No Dimension 5 value
style Text No The article style, common for all its dimensions 001010
groupReference Text No The common reference for the articles to be grouped. For example it can be the style plus the color code. 00101001
enabled Boolean Yes Indicates if the article is available for the web application. If the value is “false” then the article is removed from the web application, and only the reference needs to be filled in this data. true
sku Text Yes The article barcode number. 5013042902042
description Text Yes Article description. Maxon Jacket
genericDescription Text No Generic article description. Maxon Jacket
longDescription Text No Article long description. Maxon Jacket in the new style.
technologicObservations Text No Information about the article composition and other technical information. 10% cotton
familyRef Text Yes Reference for the article first level classification. TAI
familyName Text Yes Name for the article first level classification. >TAILORING
subfamilyRef Text Yes Reference for the article second level classification. JAC
subfamilyName Text Yes Name for the article second level classification. >JACKETS
categoryRef Text No Reference for the article third level classification. 001
categoryName Text No Name for the article third level classification. >SLIM
width Decimal No Article width. 0.0
height Decimal No Article height. 0.0
length Decimal No Article length. 0.0
capacity Decimal No Article capacity. 0.0
weight Decimal No Article weight. 0.0
price Decimal Yes Article sale price. 49.95
previousPrice Decimal No Article price before sale, if available. 69.95
classifications Classification[] No Article special classifications in web.
properties Property[] No Article additional properties.
images Image[] No Article images.

The Image object structure is defined in the Article images section.

Classification objects structure:

Field Type Required Description Example
level1 Text Yes Level 1 classification name. Jackets
level1Order Integer Yes Level 1 classification order for this element. 3
level2 Text No Level 2 classification name. Slim
level2Order Integer No Level 2 classification order for this element. 1

Property objects structure:

Field Type Required Description Example
reference Text Yes Property reference OS
name Text Yes Property name Outstanding
value Text Yes Property value true

Article images

It is possible to get the images information of an article images giving its reference. If an image is removed from an article, then this method will not return this image. The web application must assume that all the article images must be overwriting with the new information.

GET https://www.web.com/rest/{version}/{client}/images/{reference}

A JSON object is returned with the following fields:

Field Type Required Description Example
images Image[] Yes List of articles images.

Image objects structure:

Field Type Required Description Example
type Text Yes Image type. Images can be grouped in types. main
url Text Yes The URL of the image. The web application has to download the image from this URL and put it in the correct location for its use. http://www.web.com /images/image1.jpg
position Integer Yes The position of this image relative to the images in the same type. 1

Voucher query

This service allows to query the system for a voucher, related to a customer

GET https://web.com/rest/{version}/{client}/vouchers/{customer}/{voucher}

The parameters are the following:

  • customer: the customer login.
  • voucher: the voucher reference. It can be the short reference (like “PROMO15”) or de EAN13 barcode (like “9930000005440”).

A JSON Voucher object is returned with the following information:

Field Type Required Description Example
ok Boolean Yes Indicates if operation is executed successfully. true
message Text No If the operation is not ok here is the message with the error description. The voucher is not found.
customer Text Yes The customer reference, usually the login. johndoe@mail.com
reference Text Yes The voucher short reference. PROMO15
barcode Text Yes The voucher barcode. 9930000005440
expiration Text No The voucher expiration date, if available, in format yyyy/MM/dd. 2016/12/25
percent Boolean Yes Indicates if the voucher is a percent voucher or an amount voucher. true
initial Decimal Yes The initial amount for the voucher. If this number is an amount or a percent is relative to the “percent” field. 15 (meaning a 15% discount in the example).
amount Decimal Yes The current amount for the voucher. If this number is an amount or a percent is relative to the “percent” field.. It can be 0 if it is totally consumed. 15
available Boolean Yes Indicates if the voucher is available. It could be unavailable if it is totally consumed or expired for example. true

Voucher consumption

A voucher can be consumed using this method. Depending on the voucher type it can be partially consumed or not. Usually, percent voucher cannot be partially consumed and amount vouchers can.

POST https://www.web.com/rest/{version}/{client}/vouchers/movements

A JSON VoucherConsumption object must be sent with the following information:

Field Type Required Description Example
customer Text Yes The customer reference, usually the login. johndoe@mail.com
voucher Text Yes The voucher reference. It can be the short reference or the EAN13 barcode. PROMO15
amount Decimal Yes The voucher consumption amount. It must be and amount and not a percent. If the voucher is a percent voucher this amount is the discount in the sale after the percent is applied. 9.95
sale Text Yes The reference for the sale where the voucher has been applied 1123123

A JSON object will be returned with the operation information:

Field Type Required Description Example
ok Boolean Yes Indicates if operation is successful. true
message Text No If the operation is not ok this is the error message. There voucher is not found.

Client login

>If the security system is configured in order to access any service of the above, you must first request the token that will be sent in each request header.

>The token can be retrieved with a POST method:

POST https://www.web.com/rest/{version} /{client}/security/login

A JSON object must be sent with the client information:

A JSON object must be sent with the client information:

Field Type Required Description Example
userName Text Yes Name of the user. John Doe
login Text Yes Login myAlias
password Text Yes Password secretPassword

A JSON object will be returned with the operation information:

Field Type Required Description Example
ok Boolean Yes Indicates if operation is successful. true
message Text Yes >The token if the authentication has gone correctly. Otherwise the error description.

See Security aspects section for more details.

There are some export systems available in CástorRetail to send information to the web applications in real time.

Articles

CástorRetail can export information about the articles which information has been changed. It can also export the articles that are new for the web applications or have been removed from the web application:

The export system sends a JSON object with the following fields:

Field Type Required Description Example
articles Article[] Yes List of article information.

The Article object is defined in the Articles section.

Article images

CástorRetail can also export information about the article images that has been added, modified or removed. Actually it exports all the information about an article images if at least one of them has been modified.

The export system sends a JSON object with the following fields.

Field Type Required Description Example
articles ArticleImages[] Yes List of articles with its images.

ArticleImages object structure:

Field Type Required Description Example
reference Text Yes Article reference. 00101001
images Image[] Yes List of images.

The Image object structure is defined in the previous section.

Stocks

>CástorRetail can export information about the stocks in the system that were modified after the last export process, allowing CástorRetail to keep the remote system up to date. It also exports stocks for articles that have been modified since the last export date

>CástorRetail export the stocks for a set of stores that have been configured as web service stores. If these stores set changes then CástorRetail will export the stocks for all the web articles.

>The export system sends a JSON object with the following fields.

Field Type Required Description Example
stocks Stock[] Yes List of stocks information.

The Stock object is defined in the Stock section.

For ensuring the privacy of the information transmission between the web application and CástorRetail all the RESTful services can be accessed via HTTPS connections. It is possible but not recommended to use HTTP connections is the client is not able to use HTTPS.

Security

Additionally, as of version 2 of RESTful services it is mandatory to include a token which ensures that the client of the communication is authorized, and the services cannot be accessed by not authorized clients.

HTTPS

>All the RESTful services can be accessed via HTTPS methods, which uses SSL / TLS-based encryption and ensures that the information sent and received can’t be read by third entities.

>The client must ensure that they get the correct SSL certificate from the server, and use it to access the services in a secure way.

JWT

>The standard JWT has been used for implementing the authorization layer.

>Before accessing any service, it is necessary for the customer to authenticate himself using the Client login service for retrieving the security token. This token gives the client permission to access the services and has to be attached in all the requests.

>The token must be sent in the header of each request in the following format:

>Authorization: Bearer <token>

Further information about the JWT system can be checked out in this URL: