產品類別

首頁 » 服務 & 支持 » API數據服務

ApiOpenStep.jpg

公共接口約定


   1. API 接口地址:

       http://www.sunsky-api.com

       API URL 示例: http://www.sunsky-api.com/openapi/category!getChildren.do

   2. 公共參數:

       key: 用於您的程序接入SUNSKY API數據服務接口的唯一標識。

       signature: 簽名參數,它是根據您的傳入參數並且加密後得到的。

   注意: 生成簽名串前要把所有的參數根據名稱排序。

   3. 返回數據格式

       返回的數據是JSON格式。

       (a) 成功返回示例:

           { result: "success", data: [{"id":1032,"code":"003","gmtCreated":"01/31/2013 00:00","name":"N Style Phone", "parentId":408,"status":1}] }

       (b) 失敗返回示例:

           { result: "error", messages: [ "The record you visiting does NOT exist." ] }

   4. 調用頻率控制

       為了降低服務器壓力,將控制用戶並發請求,SUNSKY API 會對用戶調用的接口做調用頻率的限制。

       請到如下頁面查看頻率控制詳細: http://www.sunsky-api.com/admin/apiAccessControl!list.do

注意: 所有參數和返回結果都要區分大小寫。

Interface 1: 獲取類別和指定類別


    (a) URL: /openapi/category!getChildren.do

    (b) 參數:

          如果您未傳入任何參數,將返回所有類別信息;.

          您可以指定以下參數來過濾要獲取的類別:

          * parentId: 類別的父ID,可以獲取到當前類別ID下的所有子類別,可選;

          * gmtModifiedStart: 獲取自'gmtModifiedStart'以來更改過的類別,格式為MM/dd/yyyy HH:mm:ss(例如10/31/2013 01:23:20),可選;

    (c) 返回結果:

           摘要:

           * 如果未傳入parentId參數,則返回所有類別的數組;

           * 如果為parentId指定“0”,則返回頂級類別的數組;

           * 如果為parentId指定其他編號,則返回直接子類別的數組;

           * 如果為gmtModifiedStart指定日期,則返回自“gmtModifiedStart”以來更改的類別數組;

           字段:

           * id: 類別唯一ID;

           * code: 類別的code。該類別的子類別按代碼排序;

           * name: 類別的完整名稱;

* shortName: 類別的短名稱,有可能為空;

           * hsCode: 類別中產品的HS Code可能為空。如果HS Code為空,請參照父類別的HS Code;

           * status: 類別的狀態. 請參閱附錄A;

           * parentId: 類別的父ID;

           * gmtModified: 變更時間,格式為 MM/dd/yyyy HH:mm:ss (例如 10/31/2013 01:23:20);

      提示: 如何獲取已變更的類別?

            (1) 在調用getChildren API之前,從db / file加載先前保存的時間T0;

            (2) 使用gmtModifiedStart = T0調用getChildren API,它將返回自T0以來發生過更改的類別;

            (3) 使用getChildren API返回的類別數據更新本地數據庫;

            (4) 將T0更新為getChildren API返回的catetories中的max gmtModified,然後將T0保存到db / file;

            (5) 增加頁碼並重複步驟2~4,直到getChildren API沒有返回數據;

Interface 2: 獲取產品列表


    (a) URL: /openapi/product!search.do

    (b) 參數:

           * categoryId: 要在其中搜索產品的類別的ID(包括其子類別),可選;

           * pageSize: 每頁返回的產品數組大小,默認設置為40,最大值為100;

           * page: 頁碼,默認設置為1;

           * gmtModifiedStart: 要獲取自'gmtModifiedStarted'以來更改過的產品,格式為MM/dd/yyyy HH:mm:ss(例如10/31/2013 01:22:31),可選;

           * status: 產品狀態,請參閱附錄B,可選;

           * brandName: 品牌名稱, 例如 iPartsBuy, Xiaomi, Huawei, Meizu, 可選;

    (c) 返回結果:

           摘要:

           * 此API返回符合您指定條件的產品。

           字段:

           * total: 符合您指定的條件產品總數;

           * pageCount: 通過Total和pageSize計算出來的頁數;

           * result: 產品數據結果列表, 請參閱Interface 'openapi/product!detail.do' 查看詳細內容。

      提示: 如何獲取改變的產品?

            (1) 在調用搜索API之前,從db / file加載先前保存的時間T0;

            (2) 使用gmtModifiedStart = T0調用搜索API,它將返回自T0以來發生過更改的產品;

            (3) 使用API​​返回的產品數據更新本地數據庫;

            (4) 將T0更新為搜索API返回的產品中的最大gmtModified,然後將T0保存到db / file;

            (5) 增加頁碼並重複步驟2~4,直到搜索API沒有返回數據;

Interface 3: 獲取指定產品詳細


    (a) URL: /openapi/product!detail.do

    (b) 參數:

           * itemNo: 要獲取詳細信息的產品型號。

    (c) 返回結果:

           摘要:

           * 此API返回指定產品的完整信息。

           字段:

           * id: 產品唯一ID;

           * categoryId: 產品的類別ID;

           * itemNo: 產品型號;

           * groupItemNo: 產品的組型號。如果產品不是多型號,則組型號與產品型號相同;

           * name: 產品名稱;

           * barcode: 產品條碼;

           * description: 產品描述;

           * leadTime: 交貨時間描述. 例如. "18點前下單當天發貨 (GMT+8)", "1~3 天", "2~5 天";

           * gmtListed: 產品上市的時間, 格式為 MM/dd/yyyy HH:mm:ss (例如 10/31/2013 01:23:20). 上市90天內都是新品;

           * gmtModified: 產品修改時間, 格式為 MM/dd/yyyy HH:mm:ss (例如 10/31/2013 01:23:20);

           * warehouse: 產品的發貨倉庫. 例如 CN, HK 或者 RU;

           * stock: 如果倉庫是海外倉庫 (不是 CN), 該字段為當前庫存數量;

           * moq: 最小訂貨量,默認為1;

           * brandName: 品牌名稱,例如 'Huawei';

           * modelLabel: 如果產品是多型號產品,它將用於區分產品的屬性(例如 顏色, 尺寸...).

           * modelList: 如果產品是多型號產品,它將返回一個型號列表.

                        列表中的每個元素都是由key-value組成,key是產品型號,value是型號屬性描述。

                        例如 [ { key: 'S-MPH-001', value: 'White' }, { key: 'S-MPH-002', value: 'Black' } ]

           * optionList: 相似產品列表

                       {

                              display: "text" or "picture",

                              items: [ {

                                     itemNo: "S-MPH-0002",

                                     keywords: "Plastic Case for S7"

                              } ]

                       }

           * price: 產品當前價格;

           * priceList: 產品價格列表,根據購買數量變動對應價格。

                        列表中每個元素是key-value對象, key對應數量, value對應數量相對應的價格。

                        例如 [ { key: 2, value: '2.98' }, { key: 10, value: '2.49' } ]

           * clearance: 是否清倉產品?

           * orgPrice: 如果產品是清倉或促銷活動產品,該字段保存的是原始的價格;

           * priceExpired: 如果產品是促銷活動產品,這個字段保存的是活動到期時間,格式為 MM/dd/yyyy HH:mm (例如 10/31/2013 00:00). 可能為空;

           * status: 產品狀態,詳見附錄B;

           * unitWeight: 產品單個重量;

           * packQty: 一箱的產品數量;

           * packWeight: 一箱的產品重量,單位kg;

           * packLength&packWidth&packHeight: 一箱的產品體積,單位mm;

           * containsBattery: 是否含有電池? true 或者 false;

           * giftItemNo: 如果產品包含免費禮品,這個字段保存的是對應的禮品型號;

           * brands: 如果此產品是一種配件,此字段列出了與其兼容的品牌型號。 “/openapi/product!search.do”不返回此字段。

                     例如: [ { brand: { name: "Apple" }, models: [ { name: "iPhone" }, { name: "iPad" } ] } ]

           * params: 產品的關鍵參數。 “/openapi/product!search.do”不返回此字段。

                     例如: [ { name: "Connectivity" , values: [ "WIFI", "3G", "GPS" ] } ]

Interface 4: 下載指定產品圖片


    (a) URL: /openapi/product!getImages.do

    (b) 參數:

           * itemNo: 想要獲取的產品型號.

           * size: 產品圖片尺寸大小,以像素為單位,可選.

                   尺寸最大800 x 800, 一些老產品圖片可能是 500 x 500.

           * watermark: 圖片水印, 可選.

    (c) 返回結果:

           摘要:

           * 如果這個型號不存在,將返回404,否則返回一個zip數據流。

Interface 5: 獲取變更的產品圖片


    (a) URL: /openapi/product!getImageChangeList.do

    (b) 參數:

           * pageSize: 每頁返回變更的數量,默認40,最大100;

           * page: 頁碼,默認1;

           * gmtModifiedStart: 獲取自“gmtModifiedStart”以來圖片發生變化的產品型號, 格式為 MM/dd/yyyy HH:mm:ss (例如 10/30/2016 11:14:01);

    (c) 返回結果:

           摘要:

           * total: 符合過濾條件的結果總數.

           * pageCount: 頁碼總數.

           * result: 返回的結果中包含一個產品型號和對應圖片更新時間,例如 [{"itemNo": "S-MPH-001", "gmtModified": "10/31/2016 01:04:22"}]

     請根據已變更的產品型號列表重新下載對應產品圖片。

      提示: 如何獲取變更的產品圖片?

            (1) 在調用changelist API之前,從db / file加載先前保存的時間T0;

            (2) 使用gmtModifiedStart = T0調用changelist API,它將返回自T0以來圖片發生變化的產品;

            (3) 重新下載更改列表中列出的產品型號的產品圖片;

            (4) 將T0更新為changelist API返回的產品中的最大的 gmtModified,然後將T0保存到db / file;

            (5) 增加頁碼並重複步驟2~4,直到changelist API沒有返回數據;

Interface 6: 獲取可運送的國家列表


    (a) URL: /openapi/order!getCountries.do

    (b) 參數:

           無.

    (c) 返回結果:

           摘要:

           * 獲取運輸國家/地區列表,包括州/省(如果存在)。

           字段:

           * id: 國家唯一ID;

           * code: 國家代碼,符合ISO 3166;

           * name: 國家名稱;

           * shipToState: 是否根據州/省計算運費? 可能會更便宜. 值:true/false;

           * stateList: 國家/地區的可選州/省列表,字段如下:

                   ** code: 州/省代碼;

                   ** name: 州/省名稱;

Interface 7: 獲取產品價格和運費


    (a) URL: /openapi/order!getPricesAndFreights.do

    (b) 參數:

           * countryId: 國家唯一ID;

           * state: 州代碼, 詳見'/openapi/order!getCountries.do', 可選;

           * items.#.itemNo, items.#.qty: 產品列表,用於計算產品價格和運費.

                   ** 用數字代替#,用以區分每個產品,例如: items.1.itemNo, items.2.itemNo...

                   ** itemNo: 產品型號;

                   ** qty: 產品型號對應的數量;

    (c) 返回結果:

           摘要:

           * 獲取產品價格和運費.

          字段:

           * priceList: 產品價格列表,字段如下:

                   ** productId: 產品唯一ID;

                   ** itemNo: 產品型號;

                   ** qty: 產品數量;

                   ** price: 產品單個價格;

                   ** orgPrice: 產品原始單個價格,最終的價格可能會比原始價格便宜;

                   ** amount: 單項多個產品總金額;

                   ** orgAmount: 單項多個產品原始總金額,最終的總金額可能比這個原始總金額便宜;

           * freightList: 運費列表,字段如下:

                   ** id: 貨運方式唯一ID;

                   ** name: 貨運名稱;

                   ** logo: 貨運方式Logo URL地址;

                   ** description: 貨運方式描述;

                   ** website: 貨運方式官網;

                   ** transitTime: 貨運時間描述;

                   ** shippingCost: 運費;

Interface 8: 創建訂單


    (a) URL: /openapi/order!createOrder.do

    (b) 參數:

           * siteNumber: 您擁有SUNSKY訂單的訂單號或其他附加訂單號,用於指向當前SUNSKY訂單,可選。最大長度:32個字符。

           * useBalanceOnly: 如果設置為true,您必須在SUNSKY網站上有足夠的餘額,否則將會拋出“INSUFFICENT_BALANCE”(餘額不足)的異常。

                   如果設置為false,則當您的餘額不足時,將使用銀行轉帳的付款方式創建訂單。默認設置為false,可選;

           * coupon: 使用的優惠碼;

           * deliveryAddress.countryId: 國家ID;

           * deliveryAddress.state: 州代碼, 詳見 '/openapi/order!getCountries.do'.

                   如果該國家/地區沒有州信息,請手動輸入。最大長度:40個字符;

           * deliveryAddress.city: 城市。最大長度:40個字符;

           * deliveryAddress.company: 公司名稱, 可選. 最大長度:100個字符;

           * deliveryAddress.address: 街道地址. 最大長度:100個字符;

           * deliveryAddress.address2: 街道地址2, 最大長度:100個字符;

           * deliveryAddress.postcode: 郵編,最大長度:20個字符;

           * deliveryAddress.receiver: 收貨人全名,最大長度:32個字符;

           * deliveryAddress.telephone: 收貨人電話, 可選, 建議填寫. 最大長度:20個字符;

           * deliveryAddress.shippingWayId: 貨運方式ID.

                   您可以通過調用'/openapi/order!getPricesAndFreights.do'獲取送貨方式列表,並從結果中的'freightList'獲取id屬性;

           * deliveryAddress.shipment: drop -- 代客發貨; wholesale -- 自己購買, 可選. 默認 'wholesale';

           * items.#.itemNo, items.#.qty: 創建訂單列表元素.

                   ** 用數字代替#, 例如 items.1.itemNo, items.2.itemNo...

                   ** itemNo: 產品型號;

                   ** qty: 產品數量;

    (c) 返回結果:

           摘要:

           * 提交產品和交貨地址信息來創建SUNSKY訂單.

           字段:

           * number: 訂單號;

           * status: 訂單狀態. 詳見附錄 C;

           * amount: 產品總金額;

           * shippingCost: 訂單運費;

           * totalAmount: 訂單總金額. 訂單總金額 = 產品總金額 + 運費;

           * siteNumber: 詳見 '/openapi/order!createOrder.do';

           * packStatus: 0-備貨中; 1-打包中; 2-部分已打包; 3-已打包並發貨;

           * trackingNumber: 訂單物流跟踪號;

           * gmtCreated: 訂單創建時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);

           * gmtPaid: 訂單支付時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);

           * gmtShipped: 訂單發貨時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);

           * deliveryAddress.*: 貨運地址. 詳見 '/openapi/order!createOrder.do';

                   其它字段:

                   ** shippingWay.id: 貨運方式ID;

                   ** shippingWay.name: 獲取方式名稱;

           * detailList: 訂單詳細列表,字段如下:

                   ** productId: 產品ID;

                   ** itemNo: 產品型號;

                   ** title: 產品名稱;

                   ** qty: 產品數量;

                   ** price: 產品價格;

                   ** amount: 單項總金額;

                   ** scaned: 0-未打包; 1-已打包;

                   ** delayToShip: 0-正常; 1-延期發貨;

Interface 9: 查詢訂單


    (a) URL: /openapi/order!getOrderList.do

    (b) 參數:

           * pageSize: 頁面訂單數量,默認40,最大100;

           * page: 頁碼,默認1;

           * status: 訂單狀態, 可選. 詳見附錄 C;

           * siteNumber: 可選. 詳見 '/openapi/order!createOrder.do';

           * gmtCreatedStart: 獲取自 'gmtCreatedStart'開始的訂單, 格式為 MM/dd/yyyy(例如 10/31/2013), 可選;

           * gmtCreatedEnd: 獲取到'gmtCreatedEnd'為止的訂單, 格式為 MM/dd/yyyy(例如 10/31/2013), 可選;

    (c) 返回結果:

           摘要:

           * 此API返回符合條件的訂單數據.

           字段:

           * total: 符合查詢條件的訂單總數.

           * pageCount: 頁碼總數.

           * result: 訂單列表, 參見 '/openapi/order!createOrder.do' 獲取詳細.

                     此接口不返回'detailList'字段數據,請使用'/openapi/order!getOrderDetails.do'獲取產品詳細信息。 

Interface 10: 獲取訂單詳細


    (a) URL: /openapi/order!getOrderDetails.do

    (b) 參數:

           * number: SUNSKY訂單號;

    (c) 返回結果:

           摘要:

           * 此API返回完整的訂單詳細信息.

           字段:

           * 詳見 '/openapi/order!createOrder.do';


Interface 11: 查看SUNSKY餘額


    (a) URL: /openapi/order!getBalance.do

    (b) 參數:

           無

    (c) 返回結果:

           摘要:

           * 此API用於查看SUNSKY餘額.

           字段:

           僅僅只是一個字符串,例如 "1200.00".


Interface 12: 獲取您的餘額賬單歷史記錄


    (a) URL: /openapi/order!getBillList.do

    (b) 參數:

           * pageSize: 每頁賬單數量,默認40,最大100;

           * page: 頁碼,默認1;

           * gmtCreatedStart: 獲取自 'gmtCreatedStart' 開始的賬單數據, 格式為 MM/dd/yyyy(例如 10/31/2013), 可選;

           * gmtCreatedEnd: 獲取到 'gmtCreatedEnd'為止的賬單數據, 格式為 MM/dd/yyyy(例如 10/31/2013), 可選;

    (c) 返回數據:

           摘要:

           * 此API返回符合條件的賬單數據.

           字段:

           * total: 符合條件的賬單總數

           * pageCount: 賬單頁碼總數

           * result: 賬單列表. 字段如下:

                     * txType: 交易類型,如 prepay / createOrder / payForOrder / cancelOrder;

                     * refId:如果txType是createOrder / payForOrder / cancelOrder,則訂單號與賬單相關聯;

                     * amount: 交易總金額;

                     * balance: 交易後剩下的餘額;

                     * gmtCreated: 賬單創建時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);


Interface 13: 獲取熱門產品


    (a) URL: /openapi/stats!getHotItems.do

    (b) 產品:

           * countryId: 國家唯一ID;

    (c) 返回結果:

           摘要:

           * 此API根據對應國家ID返回對應的熱門產品.

           字段:

           * itemNo: 產品型號.


Interface 14: 獲取優惠碼列表


    (a) URL: /openapi/coupon!getList.do

    (b) 參數:

           * pageSize: 每頁優惠碼數量,默認40,最大100;

           * page: 頁碼,默認1;

    (c) 返回結果:

           摘要:

           * 此API返回符合條件的優惠碼信息.

           字段:

           * total: 符合條件的總數.

           * pageCount: 頁碼總數

           * result: 優惠碼列表,字段如下:

                     * code: 優惠碼;

                     * description: 優惠券說明解釋如何使用優惠券;

                     * startTime: 優惠碼開始時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);

                     * endTime: 優惠碼過期時間, 格式為 'MM/dd/yyyy HH:mm'(例如 10/31/2013 05:01);

                     * personLimit: 優惠碼使用上限次數;

                     * qty: The item quantity the coupon can be used on for a discount;

                     * discountType: 折扣類型

                                   1 -- 固定折扣金額;

                                   2 -- 百分比折扣;

                                   3 -- 固定金額;

                     * discount: 根據discountType的不同,相應的值表示:

                                   1 -- 折扣金額 (字符串類型);

                                   2 -- 百分比 (字符串類型) 折扣, 90 代表 10% OFF 折扣;

                                   3 -- 最終價格 (字符串類型);

                     * targetType:

                                   1 -- 類別;

                                   2 -- 產品;

                                   3 -- 訂單金額閾值(滿減);

                                   4 -- 品牌;

                     * target: 根據不同的targetType,對應的值如下:

                                   1 -- 類別 json 列表 (字符串類型), 例如 [ { id: 'category id', name: 'Category name' } ]

                                   2 -- 產品 json 列表 (字符串類型), 例如 [ { id: 'product id', name: 'Product name', itemNo: 'Item #' } ]

                                   3 -- 訂單金額閾值(滿減) 200;

                                   4 -- 品牌 json 列表 (字符串類型), 例如 [ { name: 'HAWEEL' } ];

附錄 A: 類別狀態

    0 - 無效

    1 - 有效

    2 - 已刪除

附錄 B: 產品狀態


    0 - 無效

    1 - 有效

    2 - 已刪除

    3 - 缺貨

附錄 C: 訂單狀態


    1 - 未支付

    2 - 已支付

    3 - 已發貨

    4 - 已取消

    5 - 已到達

附錄 D: 示例代碼 (Java, PHP)


    OpenApiService.zip

聯繫SUNSKY
銷售經理: Ms. Grace
+86-13924630968
更多