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:

FieldTypeRequiredDescriptionExample
sessionTextYesThe session id to create. It has to be a timestamp generated in the client and it has to be unique for this client.1435683090941
loginTextYesThe user name.johndoe
passwordTextYesThe 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:

FieldTypeRequiredDescriptionExample
okBooleanYesIndicates if the session exists and is ok.true
messageTextNoIf 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:

FieldTypeRequiredDescriptionExample
loginTextYesThe customer reference, which has to be unique. It has to be the customer login.johndoe@mail.com
firstNameTextYesThe customer first name.John
surname1TextNoThe customer family name.Doe
surname2TextNoThe second surname, if available.
emailTextYesThe email of the customer.johndoe@mail.com
phoneTextYesThe customer phone.912223344
mobileTextNoThe customer mobile phone.666555444
documentTextNoThe customer identification number. For example the NIF in Spain.EX-121212
genderTextYesThe customer gender, it can be MALE, FEMALE or COMPANYMALE
privacyStatusNumberYesThe 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
addressAddress[]NoThe customer addresses. At least one is required.
countryTextNoThe code Iso3166Alpha2 of the customer’s countryFR
webPasswordTextNoThe customer web password12345
fidelityCardNumberTextNoThe customer fidelity card number1234567890
propertiesProperty[] NoAdditional customer properties

Address objects structure.

FieldTypeRequiredDescriptionExample
referenceTextYesThe address reference, unique for the customer.WA
nameTextYesName for this address.Work address
streetTextYesThe customer address street. Other fields are not mandatory if they are included here (number, floor, door and stair).Gran Via.
numberTextNoThe customer address number.27
floorTextNoThe customer address floor.
doorTextNoThe customer address door.A-B-C-D
stairTextNoThe customer address stair.None
cityTextYesThe customer address city.Madrid
regionTextYesThe customer address region.Madrid
countryTextYesThe customer address country.Spain
zipCodeTextYesThe customer zip code.28014
phoneTextNoThe phone number for this address.666555444

Property objects structure.

FieldTypeRequiredDescriptionExample
referenceTextYesProperty referenceBIRTHDAY
nameTextYesProperty nameBirth date
valueTextYesProperty value01-jun-16

A JSON response will be returned with the following fields:

FieldTypeRequiredDescriptionExample
okBooleanYesIndicates if the customer has been created successfully.true
messageTextNoIf 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:

FieldTypeRequiredDescriptionExample
referenceTextYesThe identification of the order.1
customerCustomerYesThe 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.
addressAddressYesThe 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.
observationsTextNoObservations for the order.Please, it is urgent!
paymentPaymentNoInformation about the order paymeny.
linesOrderLine[]YesList of lines for the order.

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

Payment objects structure:

FieldTypeRequiredDescriptionExample
methodTextYesPayment method used.PayPal
transactionTextYesID of the transaction, usually related to the payment method used.223123123
amountTextYesAmount paid.99.90

OrderLine objects structure:

FieldTypeRequiredDescriptionExample
referenceTextYesArticle reference001010101001
quantityDecimalYesQuantity of articles in this line.10.0
discountDecimalNoDiscount percent applied in the line, from 0 to 100.0.0
priceDecimalYesUnit price of the article, including taxes.9.99
amountDecimalYesLine 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:

FieldTypeRequiredDescriptionExample
referenceTextYesThe order reference.CO_001
stateTextYesDescription of the order state.Sent to the customer
dateDatetimeYesDate 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:

FieldTypeRequiredDescriptionExample
referenceTextYesArticle reference0010010101
stockDecimalYesAvailable stock (in total) quantity for the article.160
enabledBooleanYesIndicates if it is allowed to sell the article with the available stock quantity.True
storeStore[]NoList of stores which stock is informed.

Store object structure

FieldTypeRequiredDescriptionExample
referenceTextYesStore reference.S01
nameTextYesStore name.MADRID VAGUADA
stockDecimalYesAvailable stock quantity in this store.
warehousesWarehouse[]NoList of store warehouses which stock is informed.

Warehouse object structure

FieldTypeRequiredDescriptionExample
referenceTextYesWarehouse reference.AVAILABLE
nameTextYesWarehouse nameAvailable warehouse
stockDecimalYesAvailable 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:

FieldTypeRequiredDescriptionExample
articlesText[]YesList 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:

FieldTypeRequiredDescriptionExample
referenceTextYesThe article reference.0010100102
dim1TextNoDimension 1 value.Red
dim2TextNoDimension 2 valueXL
dim3TextNoDimension 3 value
dim4TextNoDimension 4 value
dim5TextNoDimension 5 value
styleTextNoThe article style, common for all its dimensions001010
groupReferenceTextNoThe common reference for the articles to be grouped. For example it can be the style plus the color code.00101001
enabledBooleanYesIndicates 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
skuTextYesThe article barcode number.5013042902042
descriptionTextYesArticle description.Maxon Jacket
genericDescriptionTextNoGeneric article description.Maxon Jacket
longDescriptionTextNoArticle long description.Maxon Jacket in the new style.
technologicObservationsTextNoInformation about the article composition and other technical information.10% cotton
familyRefTextYesReference for the article first level classification.TAI
familyNameTextYesName for the article first level classification.>TAILORING
subfamilyRefTextYesReference for the article second level classification.JAC
subfamilyNameTextYesName for the article second level classification.>JACKETS
categoryRefTextNoReference for the article third level classification.001
categoryNameTextNoName for the article third level classification.>SLIM
widthDecimalNoArticle width.0.0
heightDecimalNoArticle height.0.0
lengthDecimalNoArticle length.0.0
capacityDecimalNoArticle capacity.0.0
weightDecimalNoArticle weight.0.0
priceDecimalYesArticle sale price.49.95
previousPriceDecimalNoArticle price before sale, if available.69.95
classificationsClassification[]NoArticle special classifications in web.
propertiesProperty[]NoArticle additional properties.
imagesImage[]NoArticle images.

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

Classification objects structure:

FieldTypeRequiredDescriptionExample
level1TextYesLevel 1 classification name.Jackets
level1OrderIntegerYesLevel 1 classification order for this element.3
level2TextNoLevel 2 classification name.Slim
level2OrderIntegerNoLevel 2 classification order for this element.1

Property objects structure:

FieldTypeRequiredDescriptionExample
referenceTextYesProperty referenceOS
nameTextYesProperty nameOutstanding
valueTextYesProperty valuetrue

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:

FieldTypeRequiredDescriptionExample
imagesImage[]YesList of articles images.

Image objects structure:

FieldTypeRequiredDescriptionExample
typeTextYesImage type. Images can be grouped in types.main
urlTextYesThe 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
positionIntegerYesThe 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:

FieldTypeRequiredDescriptionExample
okBooleanYesIndicates if operation is executed successfully.true
messageTextNoIf the operation is not ok here is the message with the error description.The voucher is not found.
customerTextYesThe customer reference, usually the login.johndoe@mail.com
referenceTextYesThe voucher short reference.PROMO15
barcodeTextYesThe voucher barcode.9930000005440
expirationTextNoThe voucher expiration date, if available, in format yyyy/MM/dd.2016/12/25
percentBooleanYesIndicates if the voucher is a percent voucher or an amount voucher.true
initialDecimalYesThe 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).
amountDecimalYesThe 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
availableBooleanYesIndicates 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:

FieldTypeRequiredDescriptionExample
customerTextYesThe customer reference, usually the login.johndoe@mail.com
voucherTextYesThe voucher reference. It can be the short reference or the EAN13 barcode.PROMO15
amountDecimalYesThe 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
saleTextYesThe reference for the sale where the voucher has been applied1123123

A JSON object will be returned with the operation information:

FieldTypeRequiredDescriptionExample
okBooleanYesIndicates if operation is successful.true
messageTextNoIf 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:

FieldTypeRequiredDescriptionExample
userNameTextYesName of the user.John Doe
loginTextYesLoginmyAlias
passwordTextYesPasswordsecretPassword

A JSON object will be returned with the operation information:

FieldTypeRequiredDescriptionExample
okBooleanYesIndicates if operation is successful.true
messageTextYes>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:

FieldTypeRequiredDescriptionExample
articlesArticle[]YesList 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.

FieldTypeRequiredDescriptionExample
articlesArticleImages[]YesList of articles with its images.

ArticleImages object structure:

FieldTypeRequiredDescriptionExample
referenceTextYesArticle reference.00101001
imagesImage[]YesList 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.

FieldTypeRequiredDescriptionExample
stocksStock[]YesList 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: