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:
- RESTful services accessed by HTTPS operations.
- 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. | |
| 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 |
| 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. | 4º |
| 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:
