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 | :heavy_check_mark: | | body | Object or null | :heavy_check_mark: |

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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | sku | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | slug | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | slug | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | slug | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | 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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | slug | String | :heavy_check_mark: |

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 | :heavy_check_mark: |

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 | :heavy_check_mark: | | resource | String | :heavy_check_mark: | | id | String | :heavy_check_mark: |

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 | :heavy_check_mark: | | resource | String | :heavy_check_mark: | | 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