ecomplus-sdk-js
JS library for E-Com Plus storefront with methods to access public resources from Store API, Graphs API and Search API.
This library implements only GET requests to public resources, so there aren't authentication.
You can include minified script from URL:
https://ecom.nyc3.digitaloceanspaces.com/plus/js/sdk.min.js
<script src="https://ecom.nyc3.digitaloceanspaces.com/plus/js/sdk.min.js"></script>
Or install npm package:
npm install --save ecomplus-sdk-js
Getting Started
The library declares an object called EcomIo
,
with methods (object properties) to read public resources from the APIs.
Callback
All the methods are functions with callback as his first argument,
it's the function that you should pass to treat the request response.
callback
function must have two arguments:
Name | Type | Description |
---|---|---|
err | Null or Object | Error Object |
body | Object | Response body object (JSON parsed) |
Initialize
init(StoreId, Logger)
Before you call the other methods you need to initialize the library with the store ID.
The Logger
argument is not required, but you can pass a Console object,
with properties log and error, if you want to save output on file.
Arguments
Name | Type |
---|---|
StoreId | Number |
Logger | Console object |
Example
EcomIo
Methods
The object returned from almost all methods is the response body of Store API endpoints, so if you want to see more examples, you should access the API documentation.
getProduct(callback, id)
It is a method to get a product by the ID.
Arguments
Name | Type |
---|---|
callback | Function |
id | String |
Example
EcomIo
Return
Example of returned body object:
"_id": "123a5432109876543210cdef" "store_id": 100 "sku": "s-MP_2B4" "name": "Mens Pique Polo Shirt" "keywords": "tshirt" "t-shirt" "man" "price": 429 "base_price": 60 "quantity": 100 "dimensions": "width": "value": 10 "unit": "cm" "height": "value": 8 "unit": "cm" "length": "value": 8 "unit": "cm" "weight": "value": 400 "unit": "g" "brands": "_id": "a10000000000000000000001" "name": "Shirts Example" "slug": "shirts-example" "logo": "url": "https://mycdn.com/shirts-example.jpg" "size": "100x50" "categories": "_id": "f10000000000000000000001" "name": "Polo Shirts" "slug": "polo"
getProductBySku(callback, sku)
Similar to getProduct
but here you pass the product SKU instead of ID.
Arguments
Name | Type |
---|---|
callback | Function |
sku | String |
Example
EcomIo
Return
Different from the store API,
in that case the return is the same of getProduct
.
getOrder(callback, id)
It is a method to get order by the ID.
Arguments
Name | Type |
---|---|
callback | Function |
id | String |
Example
EcomIo
getBrands(callback, filter)
It is a method to list store brands. The filter argument is a URL query string, it is not required but you can use for filtering and pagination purposes.
Filter | Type | Usage |
---|---|---|
offset | number | Max number of objects to return |
limit | number | First entry to return |
sort | string | Rules to order resultant objects |
fields | string | Object properties to return |
Arguments
Name | Type |
---|---|
callback | Function |
filter | String |
Example
With no filter:
EcomIo
With limit filter:
EcomIo
getCategories(callback, filter)
Similar to getBrands
but here the returned body is the list of store categories.
Arguments
Name | Type |
---|---|
callback | Function |
filter | String |
Example
With no filter:
EcomIo
With limit and offset:
EcomIo
searchProduts(callback, term, sort, filter)
This method calls E-Com Plus Search API, that proxy pass all requests to Elasticsearch Search APIs with XGET method (read only). Responses are the same as returned from Eslasticsearch REST API, so you can read their documentation to get more info and examples.
You must follow Request Body Search specifications.
Arguments
Name | Type | Description |
---|---|---|
callback | Function | Callback function |
term | String | It is the term that you are searching for |
sort | Number or Object | Sort products, default for views |
filter | Object | It is a object to filter results |
Example
Search by term only:
EcomIo
Order by sales:
EcomIo
Custom order:
EcomIo
Custom order and filter:
EcomIo
Term
We use a multi match query because we will query in two fields, the name and the keywords of each product.
Sort
The sort argument is based on sort from Elasticsearch documentation.
The order that the resultant products will be sort is:
- The available products;
- Search score;
- The products with more ad relevance;
- Sort object.
Sort Object
To make your work easier, we have created three default sort options, by views, price and sales:
Number | Name | Usage |
---|---|---|
0 | views | Sort by views, products with more views will appear first |
1 | sales | Sort by sales, products that sells more will appear first |
2 | price | Sort by price ascending, products with lowest price will appear first |
3 | price | Sort by price descending, products with highest price will appear first |
If sort
argument is undefined or null, default is to sort by views.
If you don't want to sort by views, sales or prices, you can pass a sort object but you have to follow the Elasticsearch documentation.
Example of sort object
sort = 'sales' : 'desc'
Filter
The filter argument is based on post filter from Elasticsearch documentation.
First we use a filter that shows only visible products. Second, we use the filter argument that you pass, if defined. So if you want to filter by brands, categories or any other property, you have to pass a filter object.
Example of filter object
filter = 'specifications': 'color': 'rgb': '#fff' '#fefefe' 'size': 'value': 'G' 'brands': 'name': 'brandName' 'categories': 'name': 'categoryName'
getRecommendedProducts(callback, id)
Returns up to 12 recommended products, selecting the products that was more times bought together with the reference product. You should use it to do something like "who bought it, bought too".
Arguments
Name | Type |
---|---|
callback | Function |
id | String |
Example
EcomIo
getRelatedProducts(callback, id)
Returns up to 12 related products, selecting the products that have more categories in common with the reference product. You should use it to do something like "you can also be interested by".
Arguments
Name | Type |
---|---|
callback | Function |
id | String |
Example
EcomIo