DEPRECATION WARNING

Deprecated in favor of Client

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.

Include minified script via CDN:

<script src="https://cdn.jsdelivr.net/npm/ecomplus-sdk@1/dist/sdk.min.js"></script>

Or install npm package:

npm install --save ecomplus-sdk

Summary

1. Getting Started
   • Callback
   • Initialize
2. Methods
   • Get Store
   • Get Product
   • Get Product By Sku
   • Get Order
   • Get Cart
   • Get Customer
   • Get Application
   • Get Brand
   • Find Brand By Slug
   • List Brands
   • Get Category
   • Find Category By Slug
   • List Categories
   • Get Collections
   • Find Collection By Slug
   • List Collections
   • Search Products
     • Term
     • Sort
     • Specs
     • IDs
     • Brands
     • Categories
     • Prices
     • Custom DSL
   • List Recommended Products
   • List Related Products
   • Map By Slug
   • Map By Window URI
   • Get Any By ID
   • Modules
     • Calculate Shipping
     • List Payments
     • Create Transaction
     • Checkout

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:

Arguments	Type	Required
err	Error object or null	✔️
body	Object or null	✔️

If the method runs correctly, err will be null, otherwise, it will be an Error object.

The response object from the APIs is parsed and returned in body, it's null if no JSON response can be captured.

Initialize

init(callback, StoreId, StoreObjectId, Logger)

Before you call the other methods you need to initialize the library.

In client JS (browser) StoreId is not required, if undefined, it will be set in function of site domain name.

You have to define StoreId, and should also define StoreObjectId, if using SDK on backend with Node.js, or if you are embedding the store in another external site, such as a blog, not in the storefront.

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	Type	Required
callback	Function	✔️
StoreId	Number
StoreObjectId	String
Logger	Console object

// storefront on browser
EcomIo.init(callback)

// Node.js or not storefront site
EcomIo.init(callback, 100, '5a674f224e0dcec2c3353d9d')

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.

Get Store

getStore(callback, id)

API reference

Method to read a store object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String

The id is not required only if StoreObjectId is set, then this method will get the object of current store.

StoreObjectId will be set automaticly if SDK is running on storefront with browser.

// get current store object
// uses saved StoreObjectId
EcomIo.getStore(callback)

// specific store by object id
EcomIo.getStore(callback, '5a674f224e0dcec2c3353d9d')

Get Product

getProduct(callback, id)

API reference

Method to read a product object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getProduct(callback, '123a5432109876543210cdef')

Example of returned body:

{
  '_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,
  // ...
}

Get Product By Sku

getProductBySku(callback, sku)

Similar to getProduct, with the same return, but here you pass the product SKU instead of ID.

Arguments	Type	Required
callback	Function	✔️
sku	String	✔️

EcomIo.getProductBySku(callback, 'COD1')

Get Order

getOrder(callback, id)

API reference

Method to read an order object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getOrder(callback, 'fe1000000000000000000005')

Get Cart

getCart(callback, id)

API reference

Method to read a cart object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getCart(callback, '2ca000000000000000000003')

Get Customer

getCustomer(callback, id)

API reference

Method to read a customer object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getCustomer(callback, '3c1000000000000000000003')

Get Application

getApplication(callback, id)

API reference

Method to read an application object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getApplication(callback, '42aa00000000000000000111')

Get Brand

getBrand(callback, id)

API reference

Method to read a brand object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getBrand(callback, 'a10000000000000000000001')

Find Brand By Slug

findBrandBySlug(callback, slug)

API reference

Method to find and read a brand by the slug.

Arguments	Type	Required
callback	Function	✔️
slug	String	✔️

EcomIo.findBrandBySlug(callback, 'brand-four')

List Brands

listBrands(callback, offset, limit, sort, fields, customQuery)

API reference

Method to list the store brands.

Arguments	Type	Required
callback	Function	✔️
offset	Number
limit	Number
sort	Number
fields	Array
customQuery	String

Offset, limit, sort and fields are URL parameters (metadata) for pagination and ordering, you can use customQuery to query by particular object properties. Default enumered sort options:

Number	Usage
1	Sort by name ascending
2	Sort by name descending
3	Sort by creation date ascending
4	Sort by creation date descending
5	Sort by popularity descending

EcomIo.listBrands(callback)

EcomIo.listBrands(callback, 0, 1000, 1, ['name'])

EcomIo.listBrands(callback, null, null, null, null, 'limit=2&offset=4')

Get Category

getCategory(callback, id)

API reference

Method to read a category object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getCategory(callback, 'f10000000000000000000001')

Find Category By Slug

findCategoryBySlug(callback, slug)

API reference

Method to find and read a category by the slug.

Arguments	Type	Required
callback	Function	✔️
slug	String	✔️

EcomIo.findCategoryBySlug(callback, 'category-four')

List Categories

listCategories(callback, offset, limit, sort, fields, customQuery)

API reference

Similar to listBrands, but listing store categories.

Arguments	Type	Required
callback	Function	✔️
offset	Number
limit	Number
sort	Number
fields	Array
customQuery	String

EcomIo.listCategories(callback)

EcomIo.listCategories(callback, 0, 1000, 1, ['name'])

EcomIo.listCategories(callback, null, null, null, null, 'limit=2&offset=4')

Get Collections

getCollection(callback, id)

API reference

Method to read a collection object by the ID.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

EcomIo.getCollection(callback, 'f10000000000000000000001')

Find Collection By Slug

findCollectionBySlug(callback, slug)

API reference

Method to find and read a collection by the slug.

Arguments	Type	Required
callback	Function	✔️
slug	String	✔️

EcomIo.findCollectionBySlug(callback, 'special-collection')

List Collections

listCollections(callback, offset, limit, sort, fields, customQuery)

API reference

Similar to listBrands, but listing store collections.

Arguments	Type	Required
callback	Function	✔️
offset	Number
limit	Number
sort	Number
fields	Array
customQuery	String

EcomIo.listCollections(callback)

EcomIo.listCollections(callback, 0, 1000, 1, ['name'])

EcomIo.listCollections(callback, null, null, null, null, 'limit=2&offset=4')

Search Products

searchProducts(callback, term, from, size, sort, specs, ids, brands, categories, prices, customDsl)

API reference

This method calls E-Com Plus Search API, that proxy pass all requests to Elasticsearch Search APIs with XGET HTTP verb (read only). Responses are the same as returned from Elasticsearch REST API, so you can read their documentation to get more info and examples.

You must follow Request Body Search specifications and this type mapping reference.

Arguments	Type	Required	Default	Description
callback	Function	✔️		Callback function
term	String			Term that you are searching for
from	number		0	Results offset number
size	number		24	Maximum number of results
sort	number		0	Results ordering, default is by views
specs	Object			Filter results by item specifications
ids	Array			Filter results by product IDs
brands	Array			Filter results by brands
categories	Array			Filter results by categories
prices	Object			Filter results by prices min and max
customDsl	Object			Custom search request body

// list trending items
EcomIo.searchProducts(callback)

Term

We use a multi match query to search specified term in two fields, the name and keywords of each product.

// search product by term
EcomIo.searchProducts(callback, 'tshirt')

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 option.

Default enumered sort options:

Number	Field	Usage
0	views	Sort by popularity, products with more page 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.

Specs

The specs argument should be an object with specifications properties that we use to filter the search. The key is the specifications name and the value is an array with the specifications values.

// sample specs object
let specs = {
  'color': [ 'blue', 'red' ],
  'size': [ 'G' ]
}

IDs

The ids argument should be an array of products IDs to filter the search. If used, only the products of specified object ID(s) will be returned.

// sample ids array
let ids = [
  '1234567890abcdef01291510',
  '1234567890abcdef01291511',
  '1234567890abcdef01291512'
]

Brands

The brands argument should be an array of brands IDs or names to filter the search. If used, only products of specified brand(s) will be returned.

// sample brands array
let brands = [
  'a10000000000000000001110'
]

// sample brands array with names
let brands = [
  'Lenovo',
  'HP'
]

Categories

The categories argument should be an array of categories IDs or names to filter the search. If used, only products of specified categorie(s) will be returned.

// sample categories array
let categories = [
  'b10000000000000000001110'
]

// sample categories array with names
let brands = [
  'Laptops',
  'All-in-One Computers'
]

Prices

The prices argument should be an object to filter search by price range. You can pass the minimum and the maximum prices.

It's based on Range query from Elasticsearch documentation.

// sample prices object
let prices = {
  'min': 10,
  'max': 100
}

Custom DSL

The customDsl is an object that you can pass to run your own Elasticsearch Query DSL.

It must be a valid Request Body Search.

List Recommended Products

listRecommendedProducts(callback, id)

API reference

Method to get a list of products to recommend together with one reference product.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

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".

EcomIo.listRecommendedProducts(callback, 'a00000000000000000000000')

List Related Products

listRelatedProducts(callback, id)

API reference

Method to get a list of products similar to one reference product.

Arguments	Type	Required
callback	Function	✔️
id	String	✔️

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".

EcomIo.listRelatedProducts(callback, 'a00000000000000000000000')

Map By Slug

mapBySlug(callback, slug)

Method to discouver the respective resource and ID by the page slug.

Arguments	Type	Required
callback	Function	✔️
slug	String	✔️

EcomIo.mapBySlug(callback, 'product-sample-slug')

Example of returned body:

{
  'resource': 'products',
  '_id': '123a5432109876543210cdef'
}

Map By Window URI

mapByWindowUri(callback)

Does the same as mapBySlug, but sets slug automaticlly from window.location.

Arguments	Type	Required
callback	Function	✔️

This method is available client side only (JS on browser)

EcomIo.mapByWindowUri(callback)

Get Any By ID

getById(callback, resource, id)

Generic method to read any public resource object from Store API by the ID.

Arguments	Type	Required
callback	Function	✔️
resource	String	✔️
id	String	✔️

EcomIo.getById(callback, 'products', '123a5432109876543210cdef')

Get Any List

getList(callback, resource, offset, limit, sort, fields, customQuery)

Generic method to read any public resource list from Store API.

Arguments	Type	Required
callback	Function	✔️
resource	String	✔️
offset	Number
limit	Number
sort	Number
fields	Array
customQuery	String

EcomIo.getList(callback, 'grids')

EcomIo.getList(callback, 'grids', 0, 1000, 1, ['title'])

EcomIo.getList(callback, 'grids', null, null, null, null, 'limit=2&offset=4')

Modules

Working with Modules API

TODO documentation

Calculate Shipping

calculateShipping(callback, body)

TODO documentation

List Payments

listPayments(callback, body)

TODO documentation

Create Transaction

createTransaction(callback, body)

TODO documentation

Checkout

checkout(callback, body)

TODO documentation