产品类别

首页 » 服务 & 支持 » 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: 优惠码可使用的打折产品个数上限;
                     * 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. Peggy
+86-18823353967
+86-15521088658
+86-15521088658
更多