ecomplus-storefront

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.init(100)

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.getProduct(callback, '123a5432109876543210cdef')

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": 42.9,
  "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.getProductBySku(callback, 'COD1')

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.getOrder(callback, 'fe1000000000000000000005')

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.getBrands(callback)

With limit filter:

EcomIo.getBrands(callback, 'limit=40')

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.getCategories(callback)

With limit and offset:

EcomIo.getCategories(callback, 'limit=20&offset=10')

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.

Type mapping reference.

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.searchProduts(callback, 'tshirt')

Order by sales:

EcomIo.searchProduts(callback, 'tshirt', 1)

Custom order:

EcomIo.searchProduts(callback, 'tshirt', {
  'base_price': 'desc'
})

Custom order and filter:

EcomIo.searchProduts(callback, 'tshirt', {
  'base_price': 'desc'
}, 'specifications' : {
  'color': {
    'rgb': [ '#fff', '#fefefe' ]
  }
})

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:

1. The available products;
2. Search score;
3. The products with more ad relevance;
4. 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.getRecommendedProducts(callback, 'a00000000000000000000000')

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.getRelatedProducts(callback, 'a00000000000000000000000')