金蝶订单100外部API说明R2.1.docx

资源描述

订单100外部API说明产品版本金蝶订单100 V1.0 系统名称订单100 模块名称修订记录 Ver. No 日期编制/修订审核批准修改的章节号 R1.0 2014-9-9 曾晓东张建东、徐英 R2.0 2014-9-17 曾晓东张建东、徐英新增退款单接口，修正实体是否必须描述，实体Order新增一个字段oid，新增实体Refund。 R2.1 2015-1-19 张建东徐英更新了签名说明及个别实体字段名称与对应关系一. 文档说明本文档的使用对象是第三方开发接入平台。第一部分系统参数的蓝色表格是要求每个API都要传入的参数，绿色表格是要求出现错误时返回的参数；第二部分是要求第三方实现的API列表，其中蓝色表格表示输入参数格式，绿色表格表示输出参数格式；第三部分是API要求返回的数据对应的实体。二. 系统参数名称类型是否必须描述 method String 是 API名称。 app_key String 是商城分配给应用的AppKey。 session String 是商城分配给用户的SessionKey。 v String 是 API协议版本。可选值:1.0 timestamp String 是时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2008-01-25 20:23:30。检查发起请求时间与服务器时间相差多大，判断是否回放请求 sign String 是 API输入参数签名结果。参考签名。 sign_method String 是参数的加密方法选择。可选值:md5 format String 否可选。指定参数格式。默认是json，支持格式为xml和json。名称类型是否必须描述 sub_code String 否错误码。 sub_msg String 否错误描述。错误返回 {"error_response":{sub_code":"3","sub_msg":"错误描述"}} 签名sign 调用API 时需要对请求参数进行签名验证，TOP服务器也会对该请求参数进行验证是否合法的。方法如下：根据参数名称（除签名和图片）将所有请求参数按照字母先后顺序排序:key + value .... key + value例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值链接后，得到拼装字符串bar2baz3foo1 md5：将secret 拼接到参数字符串头、尾进行md5加密后，再转化成大写，格式是：(md5(secretkey1value1key2value2...secret) 三. API列表 1. kingdee.items.get (下载商品) 名称类型是否必须示例值默认值描述 start_time Date 可选 2000-01-01 00:00:00 开始时间，格式:yyyy-MM-dd HH:mm:ss。 end_time Date 可选 2000-12-01 00:00:00 结束时间，格式:yyyy-MM-dd HH:mm:ss。 page_no Number 可选 1 1 页码。取值范围:大于零的整数。默认值为1,即默认返回第一页数据。 page_size Number 可选 100 100 每页条数。取值范围:大于零的整数; 默认值：100。 status Number 可选 onsale onsale表示上架，instock表示下架。不填写将返回包括上架和下架的所有商品。 num_iid String 可选 29446852 商品数字Id。填写这个参数，其它业务参数不传值名称类型是否必须示例值描述 total_results Number 是 200 所有符合条件的商品数量。 items Item[] 是返回商品列表。Item类型要求返回的对象具体参照实体附录。 { "items_get_response": { "items": { "item": [] }, "total_results": 6 } } 2. kingdee.item.quantity.update (修改商品库存) 名称类型是否必须示例值默认值描述 num_iid Number 必须 29446852 商品数字Id。 quantity Number 必须 50 库存修改值。 sku_id Number 可选 12305 要操作的sku 的数字ID。如果不填写，默认修改的是商品的库存，填写的话就是修改sku的库存。 type Number 可选 2 1 库存更新方式，可选。1为全量更新，2为增量更新。如果不填，默认为全量更新。名称类型是否必须示例值描述如更新成功没有错误返回 { "item_quantity_update_response": { is_success:true} } 3. kingdee.trades.get (查询卖家已卖出的交易数据) 名称类型是否必须示例值默认值描述 start_time Date 可选 2000-01-01 00:00:00 查询交易创建时间开始。格式:yyyy-MM-dd HH:mm:ss。默认返回3天数据 end_time Date 可选 2000-01-01 00:00:00 查询交易创建时间结束。格式:yyyy-MM-dd HH:mm:ss。 page_no Number 可选 10 1 页码。取值范围:大于零的整数。默认值为1,即默认返回第一页数据。 page_size Number 可选 100 100 每页条数。取值范围:大于零的整数; 默认值：100。 use_has_next Bool 可选 true false 是否启用has_next的分页方式，如果指定true，则返回的结果中不包含总记录数，但是会新增一个是否存在下一页的的字段。 status String 可选 TRADE_FINISHED TRADE_WAIT_BUYER_PAY 没有付款 TRADE_SELLER_SEND_GOODS 已付款 TRADE_WAIT_BUYER_CONFIRM_GOODS 已发货 TRADE_FINISHED 交易完成 TRADE_AUTOMATIC_CLOSED 交易关闭 datetype Number 可选 1 1 1按创建时间，2按修改时间。 tid String 可选 13365,4566 订单号。填写这个参数，其它业务参数不传值名称类型是否必须示例值描述 total_results Number 否 200 所有符合条件的商品数量。 has_next Bool 否 true 是否存在下一页。 trades Trade[] 是返回商品列表。Trade类型要求返回的对象具体参照实体附录。返回示例 { "trades_get_response": { "trades": { "trade": [{“tid”:”123456”, “orders”:{ “order”:[{“oid”:”122” },{“oid”:”14566” }]} ] }, "total_results": 100 } } 4. kingdee.logistics.offline .send (物流发货) 名称类型是否必须示例值默认值描述 tid Number 必须 135468 交易编号。 out_sid String 必须 SF05052 运单号。具体一个物流公司的真实运单号码。 company_code String 必须 ZJS 物流公司代码。如"POST"就代表中国邮政,"ZJS"就代表宅急送。 is_split Number 可选 1 0 表明是否是拆单。1表示拆单 0表示不拆单，默认值0。 sub_tid Number[] 可选 [1,2,3] 需要拆单发货的子订单集合，为空表示不做拆单发货。名称类型是否必须示例值描述没有错误就是发货成功返回实例 { "logistics_offline_send_response": { is_success:true } } 5. kingdee.refunds.get (退款单获取) 名称类型是否必须示例值默认值描述 start_time Date 可选 2000-01-01 00:00:00 查询修改时间开始。格式:yyyy-MM-dd HH:mm:ss。默认返回7天数据 end_time Date 可选 2000-01-01 00:00:00 查询修改时间结束。格式:yyyy-MM-dd HH:mm:ss。 page_no Number 可选 10 1 页码。取值范围:大于零的整数。默认值为1,即默认返回第一页数据。 page_size Number 可选 100 100 每页条数。取值范围:大于零的整数; 默认值：100。 use_has_next Bool 可选 true false 是否启用has_next的分页方式，如果指定true，则返回的结果中不包含总记录数，但是会新增一个是否存在下一页的的字段。 refund_id String 可选退款单号。填写这个参数，其它业务参数不传值名称类型是否必须示例值描述 total_results Number 否 200 所有符合条件的商品数量。 has_next Bool 否 true 是否存在下一页。 refunds Refund [] 是退款信息列表。Refund类型要求返回的对象具体参照实体附录。返回实例返回示例 { " refunds_get_response": { " refunds": { "refund": [实体【refund】] }, "total_results": 100 } } 四. 实体附录 1. Sku实体名称类型是否必须示例值描述 sku_id Number 是 12305 sku数字Id。 num_iid Number 是 29446852 sku所属商品Id。 quantity Number 否 50 sku商品数量。 price String 否 200.07 属于这个sku的商品的价格取值范围:0-100000000;精确到2位小数;单位:元。如:200.07，表示:200元7分。 created Date 否 2013-11-10 15:10:05 sku创建日期，时间格式：yyyy-MM-dd HH:mm:ss。 modified Date 是 2013-11-11 15:10:05 sku最后修改时间，时间格式：yyyy-MM-dd HH:mm:ss。 status String 是 normal sku状态。 normal:正常；delete:删除。 properties_name String 是 sku所对应的销售属性的中文名字串。 outer_id String 否 12345 商家设置的外部Id。 barcode String 否 6903244981002 商品条形码。 2. Item实体名称类型是否必须示例值描述 num_iid Number 是 29446852 商品数字Id。 num Number 否 888 商品数量。 outer_id String 否 12345 商家设置的外部Id。 price Price 是 5.00 商品价格，格式：5.00；单位：元；精确到：分。 skus Sku[] 否 Sku列表。Sku类型要求返回的对象具体参考实体附录。 approve_status String 是 onsale 商品上传后的状态。商品上传后的状态。onsale出售中，instock库中。 barcode String 否 6903244981002 商品条形码。 title String 是测试商品商品标题，不能超过60字节。 desc String 否这是测试商品描述。 created Date 否 2013-11-10 15:10:05 商品创建时间。（格式：yyyy-MM-dd HH:mm:ss） modified Date 是 2013-11-11 15:10:05 商品最后修改时间。（格式：yyyy-MM-dd HH:mm:ss） pic_url String 否商品主图片地址。 detail_url String 否 item.htm?id=4947813209 商品URL链接。 3. Order实体名称类型是否必须示例值描述 oid String 是 I1200351 子订单Id号。 outer_iid String 否 12345 商家设置的外部Id。 title String 是 iphone5s 商品标题。 price Price 是 200.07 商品价格。精确到2位小数;单位:元。如:200.07，表示:200元7分。 num_iid String 是 29446852 商品数字Id。 outer_id String 否 12345 商家设置的外部Id。 sku_id String 是 12305 商品的最小库存单位Sku的id。 num Number 是 1 购买数量。取值范围：大于零的整数。 outer_sku_id String 否 81893848 外部网店自己定义的Sku编号。 total_fee Price 是 200.07 应付金额（商品价格 * 商品数量 + 手工调整金额 - 子订单级订单优惠金额）。精确到2位小数；单位:元。如:200.07，表示:200元7分。 payment Price 是 200.07 子订单实付金额。精确到2位小数；单位:元。如:200.07，表示:200元7分。 discount_fee Price 否 200.07 子订单级订单优惠金额。精确到2位小数;单位:元。如:200.07，表示:200元7分。 modified Date 否 2013-11-11 15:10:05 订单修改时间。（格式：yyyy-MM-dd HH:mm:ss） sku_properties_name String 否颜色:桔色;尺码:M SKU的值。 end_time Date 否 2012-04-07 00:00:00 子订单的交易结束时间。 consign_time String 否 2013-01-13 15:23:00 子订单发货时间。 4. Trade实体名称类型是否必须示例值描述 tid String 是 2231598456416 交易编号。 seller_nick String 否测试账户卖家昵称。 buyer_nick String 是我是买家昵称。 payment Price 是 200.07 实付金额。精确到2位小数;单位:元。如:200.07，表示:200元7分。 post_fee Price 是 15.00 邮费。精确到2位小数;单位:元。如:200.07，表示:200元7分。 discount_fee Price 否 200.07 如打折，VIP，满就送等），精确到2位小数，单位：元。如：200.07，表示：200元7分。 total_fee Price 否 200.07 商品金额（商品价格乘以数量的总金额）。精确到2位小数;单位:元。如:200.07，表示:200元7分。 receiver_name String 是东方不败收货人姓名。 receiver_state String 是浙江省收货人所在的省份。 receiver_address String 是杭州淘宝城收货人的详细地址。 receiver_zip String 是 515100 收货人邮编。 receiver_mobile String 是 13512501826 收货人手机号码。 receiver_phone String 是 020-8386452 收货人电话号码。 receiver_city String 是杭州市收货人所在城市。 receiver_district String 是西湖区收货人所在地区。 consign_time Date 否 2000-01-01 00:00:00 卖家发货时间。（格式:yyyy-MM-dd HH:mm:ss） orders Order[] 是订单列表。Order类型要求返回的对象具体参考实体附录。 status String 是 TRADE_FINISHED 交易状态。可选值: TRADE_WAIT_BUYER_PAY 没有付款 TRADE_SELLER_SEND_GOODS 已付款 TRADE_WAIT_BUYER_CONFIRM_GOODS 已发货 TRADE_FINISHED 交易完成 TRADE_AUTOMATIC_CLOSED 交易取消 created Date 是 2000-01-01 00:00:00 交易创建时间。（格式:yyyy-MM-dd HH:mm:ss） pay_time Date 否 2000-01-01 00:00:00 付款时间。（格式:yyyy-MM-dd HH:mm:ss） modified Date 是 2000-01-01 00:00:00 交易修改时间。（格式:yyyy-MM-dd HH:mm:ss） end_time Date 否 2000-01-01 00:00:00 交易结束时间。（格式:yyyy-MM-dd HH:mm:ss） buyer_message String 否要送人的礼物买家留言。 buyer_memo String 否上衣大一号买家备注。 seller_memo String 否好的卖家备注。 invoice_name String 否某某公司发票抬头。 invoice_type String 否图书发票类型。 5. Refund 实体名称类型是否必须示例值描述 refund_id String 是 83477 退款单号Id。 tid String 是 2231598456416 交易编号。 oid String 是 2231598456416 子订单号 total_fee Price 否 10.00 交易总金额。精确到2位小数;单位:元。如:200.07，表示:200元7分。 created Date 是 2000-01-01 00:00:00 退款申请时间。格式:yyyy-MM-dd HH:mm:ss。 modified Date 是 2000-01-01 00:00:00 更新时间。格式:yyyy-MM-dd HH:mm:ss。 status String 是 SUCCESS 退款状态。可选值 WAIT_SELLER_AGREE (买家已经申请退款，等待卖家同意) WAIT_BUYER_RETURN_GOODS (卖家已经同意退款，等待买家退货) WAIT_SELLER_CONFIRM_GOODS (买家已经退货，等待卖家确认收货) SELLER_REFUSE_BUYER(卖家拒绝退款) CLOSED(退款关闭) SUCCESS(退款成功)。 has_good_return Bool 否 true 买家是否需要退货。可选值:true(是),false(否) refund_fee Price 是 10.00 退还金额(退还给买家的金额)。精确到2位小数;单位:元。如:200.07，表示:200元7分。 payment Price 否 10.00 支付给卖家的金额(交易总金额-退还给买家的金额)。精确到2位小数;单位:元。如:200.07，表示:200元7分。 reason String 是退款邮费退款原因。 desc String 否这是退款说明退款说明。

展开阅读全文