Welcome to WHALEGISTIC

This is a platform to help E-Commerce businesses, Wholesalers, Distributors and developers to start selling products as fast as possible and to manage their products, promotions, stocks and everything related with an E-Commerce store. Whalegistic is currently evolving to bring a better experience for people that want to start their Online Store.

With this in mind, we created a way for developers to connect with our platform and fetch all the information necessary to build an online store in no time. Get the products, group them by color or size, search for promotions, show your clients the available stock, fetch all your product collections, create orders and search for already existing order for specific clients.

Quickstart

In order for you to be able to use this tool you will need to create an account at Whalegistic. To do soo, navigate to our website Whalegistic Website and create an account in this url Whalegistic Registration (Note: if is asking for you to send a registration request is because we are still in the Beta phase and we need to review your application).

After you have an account create an Store > then go to settings > navigate to API > and create your first API keys. You will need those keys in order to access your account through the API. Don't show them to anyone out of your trust!

To install Whalegistic API tool just run the following command:

npm install whalegistic

After that you can connect with your account using Whalegistic API library and your API keys. In the following sections it will be explained how to do that!

Connect to Whalegistic

In order to connect to Whalegistic you will need both the secret and the public key. This is your login method to Whalegistic. From then on you will be able to connect to Whalegistic using the whale variable:

var Whalegistic = require('whalegistic');

var whale = new Whalegistic(
    WHALEGISTIC_SECRET_KEY, 
    WHALEGISTIC_PUBLIC_KEY
);

It is only necessary to do this once, in order to receive the necessary credentials to be used with Whalegistic API.

Requests

IMPORTANT NOTES!!!

If you have to send a request with an object inside that same request object, for example, the getProducts function has the search_obj and search_by_names parameters that are JSON objects. This need to be converted to string in order to be able to be sent. This can be done with the help of the function JSON.stringify({ OBJECT }).

Get Brands

Get all the Brands created on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {} // no parameters

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        brands: // array of all brands objects
    }

Send request code:

var response = await whale.getBrands(request_parameters)

Get Categories

Get all the Product's Categories created on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        categories: // array of all categories objects
    }

Send request code:

var response = await whale.getCategories(request_parameters)

Get Collections

Get all the Product's Collections created on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        collections: // array of all collections objects
    }

Send request code:

var response = await whale.getCollections(request_parameters)

Get Store

Get all the necessary information to display on your Online Store. Normally this is the stepping stone for starting showing all the different filters like the different brands, categories, collections and products. This is a combination of multiple functions.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        min_price: // lowest price for the searched products
        max_price: // highest price for the searched products
        offset: // offset of products ex: 20 will skip the first 20 products
        limit: // limit of products ex: 40 will send back 40 products
        promotions:
        search_by_names: [
            Products: // name of products searching for
            Brands: // brand name of products searching for
            Categories: // categories name of products searching for
            Collections: // collections name of products searching for
        ]
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
{
    products: // array of products objects
    max_product_price: // the highest product price
    number_products: // total number of products
    brands: // array of all the brands objects
    categories: // array of all the categories objects
    collections: // array of all the collections objects
}

Send request code:

var response = await whale.getStore(request_parameters)

Get Products

Get all the products created on your Whalegistic Store and filtered by the parameters sent by the request. It is returned an Array of products, the highest priced product price and the total number of products you have available.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        min_price: // lowest price for the searched products
        max_price: // highest price for the searched products
        offset: // offset of products ex: 2 will skip the first 2 products
        limit: // limit of products ex: 4 will send back 4 products
        promotions:
        search_obj: {
            Products_IDs: // array of products ids ex: [1, 2, 3, ...]
            Name: // name of products searching for
            SKU: // SKU of product searching for
            Models_IDs: // array of models ids of products searching for ex: [1, 2, 3, ...]
            Brands: // array of brands ids of products searching for ex: [1, 2, 3, ...]
            Categories: // array of categories ids of products searching for ex: [1, 2, 3, ...]
        }
        search_by_names: {
            Products: // name of products searching for
            Brands: // brand name of products searching for
            Categories: // categories name of products searching for
            Collections: // collections name of products searching for
        }
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
{
    succ: // true or false if request was successfull. If false it sends the Error
    products: // array of products objects
    max_product_price: // the highest product price
    number_products: // total number of products
}

Send request code:

var response = await whale.getProducts(request_parameters)

Get Models

Get all the Models created on your Whalegistic Store. The Models are the parent Product that can store all your products information, photos and video to make easier to create new products that are associated to a specific Model.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        offset: // offset of products ex: 2 will skip the first 2 products
        limit: // limit of products ex: 4 will send back 4 products
        search_obj: {
            model_name: // name of models searching for
            model_mid: // MID of models searching for
            brand_name: // brand name of models searching for
            category_name: // categories of models searching for
        }
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        models: // array of all models objects
    }

Send request code:

var response = await whale.getModels(request_parameters)

Get Products from Collection

Get all the products on a Collection created on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        collections: // array of collections id's ex: [1, 2, 3, ...]
        offset: // offset of products ex: 2 will skip the first 2 products
        limit: // limit of products ex: 4 will send back 4 products
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        products: // array of all products objects
        total_products_count: // total number of products on that collection
        max_price: // highest price of a product on that collection
    }

Send request code:

var response = await whale.getCollectionProducts(request_parameters)

Get Related Products

Get all the products that are related to a specific product that is sent as a request parameter. This related products are chosen based on the amount of purchases were made together with the target product. If there is no products that were purchase together with the target product, this will be filled with random products until there is a specific pattern of related products.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        product_id: // desired product id
        offset: // offset of products ex: 2 will skip the first 2 products
        limit: // limit of products ex: 4 will send back 4 products
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        products: // array of all products objects
    }

Send request code:

var response = await whale.getRelatedProducts(request_parameters)

Get Product by Slug

Get a specific products, created on your Whalegistic Store, based on its customized URL Slug. This is ideal for Webstores that want to have the name of the desire product on the website url for better SEO.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        product_slug: // desired product's url slug
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        product: // product's object
    }

Send request code:

var response = await whale.getProductBySlug(request_parameters)

Get Client

Get a specific Client object created on your Whalegistic Store or by the API.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        client_id: // id of the desired client
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        client: // client's object
    }

Send request code:

var response = await whale.getClient(request_parameters)

Create New Client

Create a new Client object on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        name: // client's name
        email: // client's email
        phone: // client's phone
        del_address: // client's delivery address
        del_city: // client's delivery city
        del_country: // client's delivery country
        del_zip: // client's delivery zip code
        vat_num: // client's delivery VAT number
        inv_name: // client's invoice name
        inv_address: // client's invoice address
        inv_city: // client's invoice city
        inv_country: // client's invoice country
        inv_zip_code: // client's invoice zip code
        inv_vat_number: // client's invoice VAT number
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        obj_insert: // object that was inserted with its ID
    }

Send request code:

var response = await whale.createClient(request_parameters)

Update Client

Update a new Client object on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        client_id: // id of the desired client
        client_name: // client's name
        client_email: // client's email
        client_phone: // client's phone contact
        client_vat_number: // client's VAT number
        delivery_address: // client's delivery address
        delivery_city: // client's delivery city
        delivery_country: // client's delivery country
        delivery_zip_code: // client's delivery zip code
        invoice_address: // client's invoice address
        invoice_city: // client's invoice city
        invoice_country: // client's invoice country
        invoice_zip_code: // client's invoice zip code
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
    }

Send request code:

var response = await whale.updateClient(request_parameters)

Get Client's Orders

Get a specific Client's orders objects created on your Whalegistic Store or by the API.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        client_id: // id of the desired client
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        orders: // array of all orders objects
    }

Send request code:

var response = await whale.getClientOrders(request_parameters)

Get Client Profile

Get a specific Client's orders objects and its profile as well created on your Whalegistic Store or by the API.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        client_id: // id of the desired client
    }

This is what the return object looks like:

Return:
{
    client: // the client's object
    client_orders: // an array of the client's orders objects
}

Send request code:

var response = await whale.getClientProfile(request_parameters)

Create New Contact

Create a new contact from a client on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        name: // contact name
        email: // valid contact email
        about: // what the contact is about
        message: // the contact message
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        obj_insert: // object that was inserted with its ID
    }

Send request code:

var response = await whale.createContact(request_parameters)

Create New Newsletter

Submit a new Newsletter subscription from a client on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        email: // desired email to add to the newsletter list
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        obj_insert: // object that was inserted with its ID
    }

Send request code:

var response = await whale.createNewsletter(request_parameters)

Get Shipping Rates

Get all the Shipping Costs Rates available on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {} // no parameters

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        shipping_costs: // array of all shipping costs objects
    }

Send request code:

var response = await whale.getShippingRates(request_parameters)

Get a specific Shipping Rate

Get a specific Shipping Cost Rate and its Tax Conversions available on your Whalegistic Store.

This is what the request parameters looks like:

Parameters:
    var request_parameters = { // it's necessary to choose one of the two
        country_name: // value of the country name
        country_code: // 2 digit country indentifier ex: "US", "GB", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        shipping: // shipping cost object
        conversion_taxes: // array of all tax conversions objects
    }

Send request code:

var response = await whale.getShippingRate(request_parameters)

Get Promo Code

Get a specific Promo Code on your Whalegistic Store. Basically this could be used to verify if the promo code exists.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        promo_code: // target promo code value
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        promo_code: // promo code object
    }

Send request code:

var response = await whale.getPromoCode(request_parameters)

Get Order

Get a specific order created on your Whalegistic Store, by the platform or by the API.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        order_id: // id of the desired order
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        order: // order object
    }

Send request code:

var response = await whale.getOrder(request_parameters)

Get Order Total

This function simply calculates the total price, tax, shipping and promotions based on the different parameters sent. It returns also all the products with all the necessary information needed for creating that order from that specific products and characteristics.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        products: [ // array of products ID's as an object
            {
                id: // id of the product
                quantity: // quantity of the product
            }, 
            {...} // other object
        ]
        shipping_country: // shipping country name to where this order will be sent
        shipping: // default shipping cost if there is no shipping country
        language: // 2 digit language code for translation ex: "EN", "FR", ...
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        total_value: // total price for this order
        vat_value: // total VAT value for this order
        shipping: // shipping price for this order
        currency: // currency of this order
        products: // array of products objects on this order
        promo_code: // promo code this order
    }

Send request code:

var response = await whale.getTotal(request_parameters)

Create New Order

Create a new order based on the parameters sent. This will also create the client if there is no information already in the system on your Whalegistic Store. The client is created and connected to this order by the email address.

This is what the request parameters looks like:

Parameters:
    var request_parameters = {
        products: [ // array of products ID's as an object
            {
                id: // id of the product
                quantity: // quantity of the product
            }, 
            {...} // other object
        ]
        del_name: // delivery client's name
        del_email: // delivery client's email
        del_phone: // delivery client's phone contact
        del_address: // delivery client's address
        del_city: // delivery client's city
        del_country: // delivery client's country
        del_zip_code: // delivery client's zip code
        inv_name: // invoice client's name
        inv_address: // invoice client's address
        inv_city: // invoice client's city
        inv_country: // invoice client's country
        inv_zip_code: // invoice client's zip code
        inv_vat_number: // invoice client's VAT number
        payment_status: // "paid" or "not paid"
        shipping: // default shipping cost if the country is not found
        promo_code_id // order promo code id value (don't need to send both promo_code_id and promo_code together)
        promo_code // order promo code value
        is_pvp: // True for an PVP priced or False for a reseller priced order
    }

This is what the return object looks like:

Return:
    {
        succ: // true or false if request was successfull. If false it sends the Error
        new_order: // order object
        order_products: // array of products objects on the new order
        promo_code: // promo code object
    }

Send request code:

var response = await whale.createOrder(request_parameters)

Report Errors

If, during the utilization of Whalegistic App any error is found, please let us know! We depend on testers and developers to help us develop our platform and libraries.

You can contact us by email or by the contact form located on Whalegistic's Website specific for reporting errors - Error Reporting.

You can also contact Whalegistic with our normal contact form for suggestions that you may have for our platform - Contact Form.

Final Thoughts

Whalegistic is still an young project with big projects and plans ahead. If you would like what we are developing and want to help us develop Whalegistic and improve our project please feel free to contact us whenever you wish with any suggestions and solutions.

We also have our Slack Site if anyone that want to join our team and discuss further Whalegistic application and how it can grow into a better and bigger platform for E-Commerce.

Any help is welcomed and necessary!

In name of all the Whalegistic Team, Many thanks for your support!