Home » Service & Support » Open API Services

ApiOpenStep.jpg

Common Calling Convention

   1. API End Point:
       http://www.sunsky-api.com
       API URL sample: http://www.sunsky-api.com/openapi/category!getChildren.do
   2. Common Parameters:
       key: The api key you got from SUNSKY Open API Platform.
       signature: The signature for the parameters, it is generated with the parameter values and the secret you got from SUNSKY Open API Platform.
   Attention: The parameters should be sorted by the name before the signature generation.
   3. Result Format
       The return value is formatted in JSON.
       (a) Successful Result Example:
           { result: "success", data: [{"id":1032,"code":"003","gmtCreated":"01/31/2013 00:00","name":"N Style Phone","parentId":408,"status":1}] }
       (b) Failed Result Example:
           { result: "error", messages: [  "The record you visiting does NOT exist." ] }
   Attention: All the parameters and return values are case sensitive.

Interface 1: Get children of the category specified in the parameters

    (a) URL: /openapi/category!getChildren.do
    (b) Parameters: 
          If you don't pass any parameter, this API will retur all of the categories.
          You can specify the parameters below to filter the categories you want to fetch:
          * parentId: The ID of the category, which you want to get its direct child categories, optional;
          * gmtModifiedStart: To fetch the categories ever changed since 'gmtModifiedStart', in the format of MM/dd/yyyy HH:mm:ss(i.e. 10/31/2013 01:23:20), optional;
    (c) Result:
           Summary: 
           * If you don't pass the parentId parameter, then an array of the all categories is returned; 
           * If you specify '0' for the parentId, then an array of the top categories is returned;
           * If you specify other number for the parentId, then an array of the direct child categories is returned;
           * If you specify a date for the gmtModifiedStart, then an array of the categories ever changed since 'gmtModifiedStart' is returned;
           Fields:
           * id: The unique ID of the category;
           * code: The code of the category. The children of the category are sorted by code;
           * name: The full name of the category;
           * shortName: The short name of the category, could be empty;
           * hsCode: The HS code for the products in the category, could be empty. If the HS code is empty, please check the HS code of the parent category;
           * status: The status of the category. See Appendix A;
           * parentId The ID of the parent category;
           * gmtModified: The change time, in format of MM/dd/yyyy HH:mm:ss (i.e. 10/31/2013 01:23:20);
      Hint: How to get the changed categories?
            (1) Before calling the getChildren API, load the previously saved time T0 from db/file;
(2) Call the getChildren API with gmtModifiedStart=T0, it'll return the categories that ever changed since T0; (3) Update your local db with the category data returned by the getChildren API; (4) Update T0 to the max gmtModified among the catetories returned by the getChildren API, then save T0 to db/file; (5) Increase the page number and repeat step 2~4 until the getChildren API returns no data;

Interface 2: Search products

    (a) URL: /openapi/product!search.do 
    (b) Parameters: 
           * categoryId: The ID of the category, which you want to search the products within (including its subcategories), optional;
           * pageSize: The array size of the products returned, default set to 40, max is 100;
           * page: The page number, default set to 1;
           * gmtModifiedStart: To fetch the products ever changed since 'gmtModifiedStart', in the format of MM/dd/yyyy HH:mm:ss (i.e. 10/31/2013 01:22:31), optional;
           * status: The status of the products you want to fetch, see Appendix B, optional;
           * brandName: The brand name of the products you want to fetch, i.e. iPartsBuy, Xiaomi, Huawei, Meizu, optional;
    (c) Result:
           Summary: 
           * This API return the products which match the conditions you specified.
           Fields:
           * total: The total product number match the conditions you specified.
           * pageCount: The total page number, calculated by total and pageSize.
           * result: An array contains product records, refer to the Interface 'openapi/product!detail.do' to get the details.
      Hint: How to get the changed product?
            (1) Before calling the search API, load the previously saved time T0 from db/file;
(2) Call the search API with gmtModifiedStart=T0, it'll return the products that ever changed since T0;
(3) Update your local db with the product data returned by the search API;
(4) Update T0 to the max gmtModified among the products returned by the search API, then save T0 to db/file;
(5) Increase the page number and repeat step 2~4 until the search API returns no data;

Interface 3: Get the details of the specified product

    (a) URL: /openapi/product!detail.do 
    (b) Parameters: 
           * itemNo: The item # of the product you want to get details.     
    (c) Result:
           Summary: 
           * This API return the full information of the specified product.
           Fields:
           * id: The unique ID of the product;
           * categoryId: The category ID of the product;
           * itemNo: The item # of the product;
           * groupItemNo: The base item # of the product. If the product is NOT multi-model, the group item # is the same as item #;
           * name: The name of the product;
           * barcode: The barcode of the product;
           * description: The detail description of the product;
           * leadTime: The lead time description. i.e. "Same Day Shipping on orders before 6PM (GMT+8)", "1~3 Days", "2~5 Days";
           * gmtListed: The time when the product was listed, in format of MM/dd/yyyy HH:mm:ss (i.e. 10/31/2013 01:23:20). The products whose listed time in the past 90 days are new arrivals;
           * gmtModified: The change time, in format of MM/dd/yyyy HH:mm:ss (i.e. 10/31/2013 01:23:20);
           * warehouse: The delivery warehouse for the product. i.e CN, HK or RU;
           * giftItemNo: If the product contains a free gift, this field has the gift's item #;
           * moq: The minimum order quantity, default to 1;
           * brandName: If the product is branded, it contains the brand name, such as 'Huawei';
           * modelLabel: If the product is multi-model, it indicates the classification criterion(i.e. Color, Size...).
           * modelList: If the product is multi-model, it is an array of the models. 
                        Every element in array is a key-value pair, the key is the item #, the value is the model description. 
                        i.e. [ { key: 'S-MPH-001', value: 'White' }, { key: 'S-MPH-002', value: 'Black' } ]
           * optionList: Similar items for listings. 
                       {
                              display: "text" or "picture",
                              items: [ {
                                     itemNo: "S-MPH-0002",
                                     keywords: "Plastic Case for S7"
                              } ]
                       }
           * price: The current price of the product;
           * priceList: The wholesale prices of the price, according to the purchase quantity.
                        Every element in array is a key-value pair, the key is the quantity, the value is the corresponding price.
                        i.e. [ { key: 2, value: '2.98' }, { key: 10, value: '2.49' } ] 
           * clearance: Is the product in clearance?
           * orgPrice: If the product is in clearance or in promotion, this field stores the original price;
           * priceExpired: If the product is in promotion, this field stores the expiration date, in format of MM/dd/yyyy HH:mm (i.e. 10/31/2013 00:00). It may be null;
           * status: The status of the product. See Appendix B;
           * unitWeight: The unit weight of the product;
           * packQty: The quantity of the products in a case;
           * packWeight: The weight of the products in a case, in 'kg' unit;
           * packLength&packWidth&packHeight: The cubage of the product in a case, in 'mm' unit;
           * containsBattery: Does the product contain battery? true or false;
           * brands: If this product is a kind of accessory, this field lists the brand models it's compatible with. This field is NOT returned by '/openapi/product!search.do'.
                     For example: [ { brand: { name: "Apple" }, models: [ { name: "iPhone" }, { name: "iPad" } ] } ]
           * params: The key parameters for the product. This field is NOT returned by '/openapi/product!search.do'.
                     For example: [ { name: "Connectivity" , values: [ "WIFI", "3G", "GPS" ] } ]

Interface 4: Download the images of the specified product

    (a) URL: /openapi/product!getImages.do 
    (b) Parameters: 
           * itemNo: The item # of the product you want to get details.     
           * size: The size of the product images you prefered, in pixels, optional.
                   The max size is 800, some old items are 500.
           * watermark: The watermark text, optional.
    (c) Result:
           Summary: 
           * If the itemNo doesn't exist, the response code is 404, otherwise a zip stream is returned.

Interface 5: Get the image changlist

    (a) URL: /openapi/product!getImageChangeList.do 
    (b) Parameters: 
           * pageSize: The array size of the changelist returned, default set to 40, max is 100;
           * page: The page number, default set to 1;
           * gmtModifiedStart: To fetch the item numbers whose images ever changed since 'gmtModifiedStart', in the format of MM/dd/yyyy HH:mm:ss (i.e. 10/30/2016 11:14:01);
    (c) Result:
           Summary: 
           * total: The total item numbers match the conditions you specified.
           * pageCount: The total page number, calculated by total and pageSize.
           * result: An array contains the item number and the time its images was updated. i.e. [{"itemNo": "S-MPH-001", "gmtModified": "10/31/2016 01:04:22"}]
     Please re-download the product images whose item number listed in the changelist.
      Hint: How to get the changed images?
            (1) Before calling the changelist API, load the previously saved time T0 from db/file;
(2) Call the changelist API with gmtModifiedStart=T0, it'll return the items whose images ever changed since T0;
(3) Re-download the product images whose item number listed in the changelist;
(4) Update T0 to the max gmtModified among the items returned by the changelist API, then save T0 to db/file;
(5) Increase the page number and repeat step 2~4 until the changelist API returns no data;

Interface 6: Get the country list for shipping

    (a) URL: /openapi/order!getCountries.do 
    (b) Parameters: 
           NONE.
    (c) Result:
           Summary: 
           * Get the country list for shipping, including the states/provinces if exist.
           Fields:
           * id: The unique ID of the country;
           * code: The country code, comply with ISO 3166;
           * name: The country name;
           * shipToState: Is the shipping cost cucaluated based on the state? Maybe less cost. true/false;
           * stateList: An optional state/province list of the country, the fields as below:
                   ** code: The state/province code;
                   ** name: The state/province name;

Interface 7: Get the prices and the shipping costs for the items

    (a) URL: /openapi/order!getPricesAndFreights.do 
    (b) Parameters: 
           * countryId: The unique ID of the country;
           * state: The state code of the shipping address, see '/openapi/order!getCountries.do', optional;
           * items.#.itemNo, items.#.qty: The item list to calculate the prices and the shipping costs. 
                   ** The # is an integer number to distinguish the items, i.e. items.1.itemNo, items.2.itemNo...
                   ** itemNo: The item # of the product;
                   ** qty: The quantity for the item;
    (c) Result:
           Summary: 
           * Get the prices and the shipping costs for the items.
           Fields:
           * priceList: The prices for the items, the fields as below:
                   ** productId: The unique ID of the product;
                   ** itemNo: The item # of the product;
                   ** qty: The quantity for the item;
                   ** price: The final unit price for the item;
                   ** orgPrice: The original unit price for the item, the final price may be cheaper;
                   ** amount: The final subtotal amount for the item;
                   ** orgAmount: The original subtotal amount for the item, the final amount may be cheaper;
           * freightList: The shipping costs for the items, the fields as below:
                   ** id: The unqiue ID of the Shipping Way;
                   ** name: The name of the Shipping Way;
                   ** logo: The logo URL of the Shipping Way;
                   ** description: The description of the Shipping Way;
                   ** website: The website of the Shipping Way;
                   ** transitTime: The shipping time description for the items;
                   ** shippingCost: The shipping cost for the items;

Interface 8: Create an order

    (a) URL: /openapi/order!createOrder.do 
    (b) Parameters: 
           * siteNumber: You own order number or other additional reference number to the SUNSKY order, optional. Max length: 32 characters.
           * useBalanceOnly: If set to true, you must have sufficient balance on SUNSKY website, otherwise, an excepiton of 'INSUFFICENT_BALANCE' will be thrown out. 
                   If set to false, the order will be created with the payment method of Bank Transfer when your have not enough balance. Default set to false, optional;
           * coupon: Coupon code can be used;
           * deliveryAddress.countryId: The unique ID of the country;
           * deliveryAddress.state: The state code of the shipping address, see '/openapi/order!getCountries.do'. 
                   If there are no state info for the country, please input manually. Max length: 40 characters;
           * deliveryAddress.city: The city of the shipping address. Max length: 40 characters;
           * deliveryAddress.company: The company name of the shipping address, optional. Max length: 100 characters;
           * deliveryAddress.address: The street address of the shipping address. Max length: 100 characters;
           * deliveryAddress.address2: The street address line 2 of the shipping address, optional. Max length: 100 characters;
           * deliveryAddress.postcode: The postal code/zip code of the shipping address. Max length: 20 characters;
           * deliveryAddress.receiver: The full name of the receiver. Max length: 32 characters;
           * deliveryAddress.telephone: The contact telephone of the receiver, optional, but recommended. Max length: 20 characters;
           * deliveryAddress.shippingWayId: The unique ID of the shipping way. 
                   You can get the shipping way list by calling   '/openapi/order!getPricesAndFreights.do', and get the id property from the 'freightList' in result;
           * deliveryAddress.shipment: drop -- dropshipping; wholesale -- buy for yourself, optional. Default set to 'wholesale';
           * items.#.itemNo, items.#.qty: The item list to create order. 
                   ** The # is an integer number to distinguish the items, i.e. items.1.itemNo, items.2.itemNo...
                   ** itemNo: The item # of the product;
                   ** qty: The quantity for the item;
    (c) Result:
           Summary: 
           * Create a SUNSKY order with the items and the delivery address info.
           * Please contact SUNSKY to verify your website account to create order.
           Fields:
           * number: The number for the order;
           * status: The status of the order. See Appendix C;
           * amount: The subtotal amount of the items;
           * shippingCost: The shipping cost of the order;
           * totalAmount: The total amount of the order. totalAmount=amount+shippingCost;
           * siteNumber: See '/openapi/order!createOrder.do';
           * trackingNumber: The tracking number of the order;
           * gmtCreated: The created time of the order, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);
           * gmtPaid: The paid time of the order, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);
           * gmtShipped: The shipped time of the order, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);
           * deliveryAddress.*: The shipping address info. See '/openapi/order!createOrder.do';
                   Additional Feilds:
                   ** shippingWay.id: The unique ID of the shipping way;
                   ** shippingWay.name: The name of the shipping way;
           * detailList: The item array of the order, the fields as below:
                   ** productId: The unique ID of the product;
                   ** itemNo: The item # of the product;
                   ** title: The name of the product;
                   ** qty: The quantity for the item;
                   ** price: The final unit price for the item;
                   ** amount: The final subtotal amount for the item;

Interface 9: Search orders

    (a) URL: /openapi/order!getOrderList.do 
    (b) Parameters: 
           * pageSize: The array size of the orders returned, default set to 40, max is 100;
           * page: The page number, default set to 1;
           * status: The status of the order, optional. See Appendix C;
           * siteNumber: Optional. See '/openapi/order!createOrder.do';
           * gmtCreatedStart: To fetch the orders created after(including) 'gmtCreatedStart', in the format of MM/dd/yyyy(i.e. 10/31/2013), optional;
           * gmtCreatedEnd: To fetch the orders created before(including) 'gmtCreatedEnd', in the format of MM/dd/yyyy(i.e. 10/31/2013), optional;      
    (c) Result:
           Summary: 
           * This API return the orders which match the conditions you specified.
           Fields:
           * total: The total order number match the conditions you specified.
           * pageCount: The total order number, calculated by total and pageSize.
           * result: An array contains order records, refer to the '/openapi/order!createOrder.do' to get the details. 
                     The 'detailList' is NOT returned by this interface, please use '/openapi/order!getOrderDetails.do' to get the items info.


Interface 10: Fetch the order details

    (a) URL: /openapi/order!getOrderDetails.do 
    (b) Parameters: 
           * number: The SUNSKY order number;      
    (c) Result:
           Summary: 
           * This API return the full information of the specified order.
           Fields:
           * See '/openapi/order!createOrder.do';


Interface 11: Check your balance on SUNSKY

    (a) URL: /openapi/order!getBalance.do 
    (b) Parameters: 
           NONE      
    (c) Result:
           Summary: 
           * This API return your balance on SUNSKY.
           Fields:
           Just a string contains your balance amount, i.e. "1200.00".


Interface 12: Get your balance history

    (a) URL: /openapi/order!getBillList.do 
    (b) Parameters: 
           * pageSize: The array size of the bills returned, default set to 40, max is 100;
           * page: The page number, default set to 1;
           * gmtCreatedStart: To fetch the bills created after(including) 'gmtCreatedStart', in the format of MM/dd/yyyy(i.e. 10/31/2013), optional;
           * gmtCreatedEnd: To fetch the bills created before(including) 'gmtCreatedEnd', in the format of MM/dd/yyyy(i.e. 10/31/2013), optional;      
    (c) Result:
           Summary: 
           * This API return the bills which match the conditions you specified.
           Fields:
           * total: The total bill number match the conditions you specified.
           * pageCount: The total bill number, calculated by total and pageSize.
           * result: An array contains bills. The fields as below:
                     * txType: prepay/createOrder/payForOrder/cancelOrder;
                     * refId: The order # related to the bill, if the txType is createOrder/payForOrder/cancelOrder;
                     * amount: The amount changed after the transaction;
                     * balance: The balance amount on SUNSKY after the transaction;
                     * gmtCreated: The created time of the bill, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);


Interface 13: Get the hot items

    (a) URL: /openapi/stats!getHotItems.do 
    (b) Parameters: 
           * countryId: The unique ID of the country;     
    (c) Result:
           Summary: 
           * This API return a hot item list in the specified country.
           Fields:
           * itemNo: The item # of the product.

Appendix A: Category Status

    0 - Invalid
    1 - Valid
    2 - Deleted

Appendix B: Product Status

    0 - Invalid
    1 - Valid
    2 - Deleted
    3 - Out of Stock

Appendix C: Order Status

    1 - Unpaid
    2 - Paid
    3 - Shipped
    4 - Cancelled
    5 - Delivered

Appendix D: Sample Code (Java, PHP)

    OpenApiService.zip
Contact SUNSKY
Sales Manager: Ms. Yolanda
+86-13657966994
+86-13657966994
+86-136 5796 6994