-
Доставка в:
-
Валюта:
- English Français Español Português Deutsch Italiano Nederlands عربي 日本語 한국어 ไทย Tiếng Việt 中文简体 中文繁体 русский язык
Главная страница » Служба поддержки » Открытые API-сервисы
Common Calling Convention
1. API End Point:
https://open.sunsky-online.com
API URL sample: https://open.sunsky-online.com/openapi/category!getChildren.do 2. Parameters:
We recommend that you use POST method to pass the parameters. You should always include the following two parameters in every call:
* key: The API key you got from the sales manager.
* signature: The signature for the parameters, it is generated with the key & secret and the other parameter values. For example, we have three parameters to pass:
* name: John Smith
* age: 19
* gendar: mail
and the key & secret got from the sales manager:
* key: MYKEY
* secret: MYSECRET
Then generate the signature by 3 steps:
(a) Get a concatenated string with the key and the other parameter values which are sorted by their corresponding names: 19mailMYKEYJohn Smith; (Keep the whitespaces)
(b) Append a character of '@' and the secret to the string: 19mailMYKEYJohn Smith@MYSECRET;
(c) Calculate the signature with MD5 algo: signature=MD5("19mailMYKEYJohn Smith@MYSECRET");Attention: Do NOT place the secret into the parameters.
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." ] }
4. Call Frequency Control
SUNSKY will limit the API call frequency in case the mass calls overwhelm the servers.
Please refer this to get the frequency control info: https://open.sunsky-online.com/admin/apiAccessControl!list.doAttention: 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:
* lang: The language describing the categories, see Appendix E, optional;
* 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); Interface 2: Search products
(a) URL: /openapi/product!search.do
(b) Parameters:
* lang: The language describing the products, see Appendix E, optional;
* 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, -1 for all the status, see Appendix B, optional;
* brandName: The brand name of the products you want to fetch, i.e. iPartsBuy, Xiaomi, Huawei, Meizu, optional;
* leadTimeLevel: A number between 1 and 5, level 5 is for the shortest lead time, see Appendix D, 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 products?(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) Get the max gmtModified among the products as T, then save T to db/file; (4) If T equals T0, then increase the page number, else update T0 to T and reset the page number to 1;
(5) Repeat step 2~5 until the search API returns no data or the current page number is smaller than the page count;Date t0 = loadFromDB();
DateFormat df = new SimpleDateFormat("MM/dd/yyyy");
int page = 1;
PageList pageList;
do {
Map params = new HashMap();
params.put("gmtModifiedStart", df.format(t0));
params.put("page", page);
pageList = get("search.do", params);
Date t = t0;
for (Product item : pageList.list) {
// ...
if (item.gmtModified.after(t)) {
t = item.gmtModified;
}
}
saveToDB(t);
if (t.compareTo(t0) == 0) {
page++;
} else {
t0 = t;
page = 1;
}
} while (!pageList.list.isEmpty() || page < pageList.pageCount);
Interface 3: Get the details of the specified product
(a) URL: /openapi/product!detail.do
(b) Parameters:
* lang: The language describing the products, see Appendix E, optional;
* 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:
* lang: The language describing the product, see Appendix E;
* 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 #;
* picCount: The number of the detail pictures;
* baseImgCount: The number of the common pictures related to the base item #;
* name: The name of the product;
* barcode: The barcode of the product;
* description: The detail description of the product;
* videoUrl: The video URL for 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;
* stock: If the warehouse is an oversea warehouse (NOT CN), this field gives the current stock quantity;
* 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;
* unitLength&unitWidth&unitHeight: The size of the product, in 'mm' unit;
* packWeight: The weight of the products in a case, in 'kg' unit;
* packLength&packWidth&packHeight: The size of the product in a case, in 'mm' unit;
* oem: Does this product support OEM? true or false;
* withLogo: true or false; (If true, maybe need license to resell, please confirm it with your sales manager before you sell on the 3rd platform.)
* containsBattery: Does the product contain battery? true or false;
* giftItemNo: If the product contains a free gift, this field has the gift's item #;
* 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 changelist
(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 item numbers whose images ever changed since T0;
(3) Get the max gmtModified among the item numbers as T, then save T to db/file; (4) If T equals T0, then increase the page number, else update T0 to T and reset the page number to 1;
(5) Repeat step 2~5 until the changelist API returns no data or the current page number is smaller than the page count;Date t0 = loadFromDB();
DateFormat df = new SimpleDateFormat("MM/dd/yyyy");
int page = 1;
PageList pageList;
do {
Map params = new HashMap();
params.put("gmtModifiedStart", df.format(t0));
params.put("page", page);
pageList = get("getImageChangeList.do", params);
Date t = t0;
for (Item item : pageList.list) {
// ...
if (item.gmtModified.after(t)) {
t = item.gmtModified;
}
}
saveToDB(t);
if (t.compareTo(t0) == 0) {
page++;
} else {
t0 = t;
page = 1;
}
} while (!pageList.list.isEmpty() || page < pageList.pageCount);
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, otherwise, an excepiton of 'INSUFFICENT_BALANCE' will be thrown out.
If set to false, an UNPAID order will be created. Default set to false, optional;
* vatNumber: VAT number. It is recommended to fill in when the recipient is in an EU country and the order item amount exceeds 150 euros;
* eoriNumber: EORI number. It is recommended to fill in when the recipient is in an EU country and the order item amount exceeds 150 euros;
* iossNumber: IOSS number. It is recommended to fill in when the recipient is in an EU country and the order item amount is smaller than 150 euros. This IOSS number must be registered in IOSS Settings in advance;
* 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.email: The contact email of the receiver, optional, but recommended. Max length: 40 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;
** remark: The remark for the item. Max length: 100 characters; (c) Result:
Summary:
* Create a SUNSKY order with the items and the delivery address info.
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;
* taxAmount: The VAT amount of the order;
* totalAmount: The total amount of the order. totalAmount=amount+shippingCost+taxAmount;
* siteNumber: See '/openapi/order!createOrder.do';
* vatNumber: VAT number;
* coupon: Coupon code can be used;
* packStatus: 0-Preparing; 1-Packing; 2-Mostly Packaged; 3-Packaged and ready to ship;
* 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;
** shippingWay.queryUrl: The URL to validate the tracking number;
* 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;
** remark: The remark for the item;
** price: The final unit price for the item;
** amount: The final subtotal amount for the item;
** scaned: 0-Not ready to pack; 1-Ready to pack;
** delayToShip: 0-Normal; 1-Delay to ship;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: Add labels to the order
(a) URL: /openapi/order!addLabels.do
(b) Parameters:
* number: The SUNSKY order number;
* items.#.barcode, items.#.url: The labels for the order.
** The # is an integer number to distinguish the items, i.e. items.1.barcode, items.2.barcode...
** barcode: The barcode in the label file for the order;
** url: The label file URL;
(c) Result:
Summary:
* This API return the standard success/error format.
Interface 12: Fetch the labels for the order
(a) URL: /openapi/order!getLabels.do
(b) Parameters:
* number: The SUNSKY order number;
(c) Result:
Summary:
* This API return all the labels for the order.
Fields:
* barcode;
* url;Interface 13: 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 14: 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 15: 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.
Interface 16: Get the coupon list
(a) URL: /openapi/coupon!getList.do
(b) Parameters:
* pageSize: The array size of the coupons returned, default set to 40, max is 100;
* page: The page number, default set to 1;
(c) Result:
Summary:
* This API return the coupons which match the conditions you specified.
Fields:
* total: The total coupon number match the conditions you specified.
* pageCount: The total coupon number, calculated by total and pageSize.
* result: An array contains coupons. The fields as below:
* code: The coupon code;
* description: The coupon description to explain how to use the coupon;
* startTime: The start time of the coupon, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);
* endTime: The end time of the coupon, in format 'MM/dd/yyyy HH:mm'(i.e. 10/31/2013 05:01);
* personLimit: The times one person can use the coupon;
* qty: The item quantity the coupon can be used on for a discount;
* strikeType:
0 -- discount vary by quantity;
1 -- only discount on the Nth item;
2 -- discount vary by order amount;
* discountType:
1 -- fixed discounted amount;
2 -- discount in percentage, 90 means 10% OFF;
* discount: According to the different strikeType, the corresponding value means:
strikeType=0&discountType=2: [{"key":"10","value":"90"},{"key":"20","value":"80"}] means 10% OFF when the quantity is greater than 10, 20% OFF when the quantity is greater than 20;
strikeType=1&discountType=1: [{"key":"2","value":"5"},{"key":"5","value":"15"}] means $5 OFF on the 3rd item and $15 OFF on the 6th item;
strikeType=2&discountType=2: [{"key":"100","value":"90"},{"key":"200","value":"80"}] means 10% OFF when the order amount is greater than $100, 20% OFF when the order amount is greater than $200;
* targetType:
0 -- All items;
1 -- Category;
2 -- Product;
3 -- Order Amount threshold;
4 -- Brand;
* target: According to the different targetType, the corresponding value as below:
targetType=1: The category json list (string), i.e. [ { id: 'category id', name: 'Category name' } ]
targetType=2: The product json list (string), i.e. [ { id: 'product id', name: 'Product name', itemNo: 'Item #' } ]
targetType=3: The order amount threshold (string), i.e. 200;
targetType=4: The brand json list (string), i.e. [ { name: 'HAWEEL' } ];
Callback interface:
You could provide us a URL to your sales manager to get all events notified. The events include:
* order/shipped: Your order has been shipped.
* order/cancelled: Your order has been cancelled.
* order/tracking: The tracking number for your order has been changed.We'll call your URL via POST every 5 minutes until it returns an HTTP 200 response. The data in the POST body is as follows: { "event": "order/shipped", "order": { ... } }
Appendix A: Category Status
1 - Valid
2 - Deleted
Appendix B: Product Status
1 - Valid
2 - Deleted
3 - Out of stock
4 - Hidden (too old)Appendix C: Order Status
1 - Unpaid
2 - Paid
3 - Shipped
4 - Cancelled
5 - Delivered
Appendix D: Lead Time Level
5 - Same-day shipping
4 - Ship in 2 days
3 - Ship in 2-3 days
2 - Ship in 3-5 days
1 - Out of stock
Appendix E: Language List
en - English
ru - русский язык
fr - Français
es - Español
pt - Português
de - Deutsche
it - Italiano
nl - Nederlands
ar - عربي
vi - Tiếng Việt
th - ไทย
ko - 한국어
ja - 日本語
zh_CN - 中文简体
zh_TW - 中文繁体Appendix F: Sample Code (Java, PHP)
OpenApiService.zip
Appendix G: Other Third-party SDK
- Python: https://github.com/progressify/pysunsky (Thanks for Antonio Porcelli)
