物料平台openApi接口文档

1、物料平台openApi接口文档修改记录版本修改日期修改记录修改者V1.02017/06/16创建在东2017/07/171. 配送指令创建时间字段为:create_date2. 更新各字段和数据库一致.在东2017/07/201. 增加配送地址信息数据结构AssetDeliveryAddress2. 增加物流单信息数据结构LogisticsInfo3. 配送指令增加物料信息, 配送数量, 申请单id.3. 其他字段更新说明等.在东2017/07/25配送指令中物流信息改成单数, logistics_info 只在个性码生产时有一个在东2017/07/31物料生产流程图更新在东2017/08/0

2、7AssetDeliveryAddress加”区”的字段: district, 比如西湖区在东2017/08/09AssetDeliveryAddress的district拼写错误改正.在东2017/08/15生产指令asset_resource字段格式定义说明(目前用于获取空码备货的码值文件地址.).在东2017/08/18生产指令asset_resource, key值附录6.2说明.在东2017/10/231.生产指令新增3个字段, 用于透传:生产单号(key为produce_order), 备注(key为memo), 业务渠道(key为biz_tag).2.个性码的生产指令asset_

3、resource 中会新增个性码码值, key为PERSONAL_QRCODE.在东2017/12/41. 添加环境介绍2. 添加流程介绍3. 附录中添加demo4. 配送指令新增字段业务渠道(key为biz_tag).欧阳岩松2017/12/191.增加supplier_name, 和supplier_id一起标识对应供应商的信息.在东2018/02/05新增3.8 物料信息反馈接口在东2018/02/05机具序列号反馈格式为数组.在东2018/03/01增加3.4,3.7 - 暂不支持分批反馈说明.增加3.8 - 接口反馈节点说明.在东1 概述1.1 术语术语描述物料供应商(商户)物料生产

4、方物流供应商(商户)负责物流的供应商物料平台支付宝物料设计、生产、运输的信息平台.开放平台支付宝开放平台()，通过开放平台网关提供开放api给第三方调用1.2 整体流程介绍商家通过物料平台进行物料生产和配送, 操作生产单的读取和更新, 配送单的读取和更新.物料生产流程物料配送流程1.3 错误码错误码错误描述ILLEGAL_PARAMS参数不合法SYSTEM_ERROR系统繁忙INVALID_OP非法操作SIGN_CHECK_FAIL验签失败PAGE_SIZE_ILLEGAL请求订单数量不在指定范围PRODUCE_ORDER_QUERY_FAILED获取生产指令异常HAS_NO_ASSIGN_I

5、TEM供应商名下无此分配记录ASSET_PRODUCE_PROCESS_EXCEPTION配送反馈更新失败异常注意: 仅列出部分, 后面更新, 待增加.2 接入流程2.1开放平台接入接入指南详细步骤: 详见【物料平台商家接入开放平台】.线上(生产)环境由供应商按照文档指南进行接入.开发或测试环境由物料平台接口人负责提供账号进行联调.2.2环境介绍1. stable环境也叫开发环境, 供应商接入时开发联调在该环境进行, 测试app信息由物料平台接口人提供.openapi网关地址: 2. sit环境：SIT环境即TEST环境, 和开发环境一样属于线下环境.开发环境联调通过之后, 由物料平台接口人决

6、定, 供应商是否需要接入该环境进行联调. openAPI网关地址: 3. 预发布环境这是上线前的必须在该环境进行验收, 供应商需要在此前按照物料平台上架接入开放平台申请好线上账号.如何连接预发:- 供应商绑定hosts 8 - 然后访问 , 网关地址为 https:/ 注意:预发布环境的数据库跟线上生产环境是同一套，服务器是跟线上隔离的，PD/开发/测试在该环境下用真实的线上账号进行本次需求内容的测试验收.预发环境供应商必须走线下实际流程，必须实际在生产线上生产，然后送货至物流商，反馈实际的物流信息和物料信息。物流商也必须按照实际流程进行配送。完成流程以后预发才算通过。

7、4. 线上环境预发验证通过之后, 业务方确认后可以开启线上流量. 线上网关: 2.3调用说明该章节说明openAP请求参数格式以及返回结果的格式, 物料平台提供的api接口详情参照下一章节.(1) 基本参数所有API接口都必须传入的参数如下:参数名参数名称参数类型必填描述范例app_id开发者的AppidString(32)Y支付宝分配给开发者的应用Id2014072300007148method接口名称String(128)Y接口名称alipay.trade.paycharset参数字符编码String(10)Y请求使用的编码格式，如utf-8,gbk,gb2312等utf-8sign_ty

8、pe签名类型String(10)Y商户生成签名字符串所使用的签名算法类型，目前支持RSARSAsign签名String(256)Y商户请求参数的签名串详见签名生成规则timestamp时间戳StringY发送请求的时间，格式“yyyy-MM-dd HH:mm:ss”2014-07-24 03:07:50version接口版本号StringY调用的接口版本，固定为：1.01.0notify_url接口异步通知urlString(256)N支付宝服务器主动通知商户服务器里指定的页面http路径biz_content业务参数StringYJSON格式，具体包含的内容参见各个接口的业务参数描述详见各业

9、务接口(2) 业务参数每个API接口还有一些其他业务参数，可以在下文每个接口的详细介绍中查到相关的接口参数说明，例如查询生产指令接口, 业务参数在biz_content字段：(3) 接口返回结果成功结果: "ant_merchant_expand_assetproduce_assign_query_response": "code": "10000", "msg": "Success", "asset_produce_items": "apply_order_id&

10、quot;: "AO232323232323232323", " assign_item_id ": "2017031620076002000006742800", "biz_tag": ""ch_tag01":"服务商-开户"", "template_id": "234", "template_name": "A6个性码套装挂牌组", "create_date&qu

11、ot;: "2017-12-14 15:24:30", "count": "1", "apply_date": "2017-05-12 16:20:22", "receiver_name": "收货人姓名", "receiver_mobile": "联系人电话", "receiver_address": "收货人地址", "province": "

12、浙江", "city": "杭州", "district": "西湖区", "postcode": "postcode", "supplier_pid": "208812312313"，"asset_resource": ""PERSONAL_QRCODE_URL":" , "has_next_page": true , "sign&qu

13、ot;: " CwMoJ6Nu.MWKg="失败结果: "ant_merchant_expand_assetproduce_assign_query_response": "code": "40004", "msg": "Business Failed", "sub_code": "PAGE_SIZE_ILLEGAL", "sub_msg": "业务异常, 请求生产指令数量有误" , "

14、sign": "CwMoJ6Nu.MWKg="接口调用失败时，返回消息中一定存在code、msg、sub_code、sub_msg，其中sub_code和sub_msg表示业务定义的错误码, 具体参考【1.3 错误码】.接口返回各参数含义可参考FAQ5.1/5.23 详细接口3.1 接口列表接口编号API名称接口含义3.2ant.merchant.expand.assetproduce.assign.query获取生产指令接口3.3ant.merchant.expand.assetproduce.assign.sync生产指令接收反馈接口3.4plete.sync

15、物料生产完成反馈接口3.5ant.merchant.expand.assetdelivery.assign.query获取配送指令3.6ant.merchant.expand.assetdelivery.assign.sync配送指令接收反馈3.7plete.sync配送完成反馈3.8ant.merchant.expand.assetinfo.sync物料信息反馈接口3.2 生产指令获取接口- API名称：ant.merchant.expand.assetproduce.assign.query （获取生产指令接口）- API应用场景说明：获取某个供应商需要处理的生产指令, 包含所有物料的生产

16、指令（个性码，空码，基础物料）.- 参数详细说明:- 入参：参数类型是否必填最大长度描述示例page_sizeNumber是10一次请求获取数量 可选值为1,200100- 响应参数参数类型是否必填最大长度描述示例has_next_pageBoolean是-是否有下一页truecodeString是返回结果code10000msgString是返回接口描述Successasset_produce_itemsAssetProduceIte m是-生产指令集合-+ assign_item_idString是64订单明细IDPI2017031620076002+ apply_order_idStri

17、ng是64申请单号AO201608012007600+ template_idString是64模板ID160+ template_nameString是256模板名称，线下约定的物料名转账码吊牌、窗贴-10*10贴纸-推荐使用支付宝+asset_resourceString是4000生产资料大字段, 用于提供物料供应商生产所需资料.比如空码地址: "QRCORE_FILE_URL": "x-0.txt": " "x-1.txt": " 取出对应的txt地址值就好. 更多详情见: 附录6.2.+ countStri

18、ng是128数量1000+ apply_dateString是-申请日期, 格式:yyyy-MM-dd HH：mm:ss2017-04-12 19:12:57+ create_dateString是-订单创建日期, 格式:yyyy-MM-dd HH：mm:ss2017-05-01 19:12:57+ provinceString是256省浙江省+ cityString是256city杭州市+ districtString是256区西湖区+ postcodeString否128收件人地址邮编;310000+ supplier_pidString是1024供应商id.208830208328828

19、0+ data_versionString 是64数据版本, 目前来说只会是data_verion = 2. 1：旧模式，需要在生产完成后反馈运单号 2：新模式：不需要在生产完成后反馈运单号+ produce_orderString 是64生产单号PO2017101202096225+ memoString 否500备注业务方下达生产的备注.+ biz_tagString 是500业务渠道"ch_tag07":"红包码套装-天猫销售"- 错误码业务错误码错误描述解决方案PAGE_SIZE_ILLEGAL业务异常请求生产指令数量有误设置正确的page_si

20、ze, 范围为1, 200.PRODUCE_ORDER_QUERY_FAILED业务异常生产指令获取异常需要联系物料平台排查具体原因.3.3 生产指令下达反馈接口- API名称：ant.merchant.expand.assetproduce.assign.sync （生产指令接收反馈接口）- API应用场景说明：当调用方调用了生产指令下达接口后，并且供应商系统处理成功后调用该接口，保证再次获取生产指令接口时不会拉取到重复数据。- 参数详细说明:- 入参参数类型是否必填最大长度描述示例asset_resultsAssetResult 是-生产指令接收情况，最多200条-+ successBoo

21、lean是64接口处理结果true+ assign_item_idString是64订单明细ID2017031620076002000006742800+ error_codeString否64错误码error_code+ error_desc否否128error_desc错误描述- 响应参数参数类型是否必填最大长度描述示例asset_resultsAssetResult是1000生产指令反馈结果-+ successBoolean是64接口处理结果true+ assign_item_idString是64订单明细ID2017031620076002000006742800+ error_cod

22、eString否64错误码HAS_NO_ASSIGN_ITEM+ error_descString否128error_desc供应商名下无此分配记录- 错误码业务错误码错误描述解决方案PAGE_SIZE_ILLEGAL业务异常请求生产指令数量有误设置正确的page_size, 范围为1, 200.HAS_NO_ASSIGN_ITEM供应商名下无此分配记录确认订单明细ID是否正确;如果确实无误, 那么需要联系物料平台排查具体原因.注意:(1)接口返回结果code不是 ”10000” (比如”20000”, “40004) 时表示接口调用出现异常, 商家需要对所有订单重新进行反馈.(2) 接口返回

23、结果code是”10000”, 表示接口调用成功, 商家需要从接口返回的结果中判断每个生产单是否更新成功, 取AssetResult中的success判断该订单是否处理成功, 商家需要对success为false的订单重新反馈.3.4 生产订单完成反馈接口- API名称：plete.sync （物料生产完成反馈接口）- API应用场景说明：当生产的物料已经完成时，调用该接口。- 参数详细说明:- 入参参数类型是否必须最大长度描述示例值asset_produce_detailsAssetProduceDetail 是-物料生产单完成后制定物流信息-+ assign_item_idString是6

24、4订单明细ID2017031620076002000006742800(只能填写一条)- 响应参数参数类型是否必须最大长度描述示例值asset_resultsAssetResult是-物料订单更新结果信息-+ successBoolean是64truetrue+ error_codeString否64errorCodeHAS_NO_ASSIGN_ITEM+ error_descString否64错误描述供应商名下无此分配记录+assign_item_idString是64订单明细ID订单明细ID- 错误码业务错误码错误描述解决方案HAS_NO_ASSIGN_ITEM供应商名下无此分配记录确认订

25、单明细ID是否正确;如果确实无误, 那么需要联系物料平台排查具体原因.ASSET_PRODUCE_PROCESS_EXCEPTION配送反馈更新失败异常先进行重试, 如果仍然有问题, 需要联系物料平台排查具体原因.注意:(1)接口返回结果code不是 ”10000” (比如”20000”, “40004) 时表示接口调用出现异常, 商家需要对所有订单重新进行反馈.(2) 接口返回结果code是”10000”, 表示接口调用成功, 商家需要从接口返回的结果中判断每个生产单是否更新成功, 取AssetResult中的success判断该订单是否处理成功, 商家需要对success为false的订单

26、重新反馈.(3) 该接口暂不支持分批反馈, 比如一个生产指令生产完成之后, 调该接口一次性反馈. 3.5 获取配送指令- API名称：ant.merchant.expand.assetdelivery.assign.query （获取配送指令接口）- API应用场景说明：用于给物流服务商主动获取物料配送订单. Note: 获取配送订单之后, 需要调用”3.6 配送指令接收反馈” 接口进行反馈.参数详细说明:- 入参：参数类型是否必填最大长度描述示例page_sizeNumber是10一次请求获取数量 可选值为1,200100- 响应参数参数类型是否必填最大长度描述示例has_next_page

27、Boolean是-是否有下一页trueasset_delivery_itemsAssetDeliveryItem是-配送指令集合-+ assign_item_idString是64配送订单唯一Id2017031620076002000006742800+ assign_out_order_idString是64配送流水号，可用于对账支付宝内部的配送流水号, 可供物料商和物流商用于对账.+ apply_order_idString是64申请单号AO2018020512345678+ supplier_idString是64对应供应商id.对应供应商id, 比如生产商需要把货物配送至物流商仓库,

28、那么该id为对应物流供应商的id.+ supplier_nameString是64对应供应商名称和supplier_id对应+ gmt_assignString是-配送指令生成日期, 格式:yyyy-MM-dd HH：mm:ss2017-05-01 19:12:57+ item_idString是-物料id+ item_nameString是-物料名称+ amountString是-配送数量+ from_addressAssetDeliveryAddress是-发送地址+ + provinceString是256省浙江省+ + cityString是256市杭州市+ districtStrin

29、g是256区西湖区+ + addressString 是256地址黄龙时代小邮局2楼+ + contact_nameString是64联系人赵四+ + contact_phoneString是64联系电 + zip_codeString否64邮编31000+ to_addressAssetDeliveryAddress是-接收地址+ + provinceString是256省浙江省+ + cityString是256市杭州市+ districtString是256区余杭区+ + addressString 是256地址青青花园302楼+ + contact_nameS

30、tring是64联系人闲林baby+ + contact_phoneString是64联系电 + zip_codeString否64邮编31000+ logistics_infoLogisticsInfo否-物流信息+ + logistics_noString是64物流单号400012131+ + logistics_nameString是64物流公司名称顺丰速运+ + logistics_codeString是64物流公司codeSF+ memoString否256+ biz_tagString是500业务渠道"ch_tag07":"红

31、包码套装-天猫销售"+ print_dataString否5000菜鸟电子面单信息(仅供对接了菜鸟的供应商)“encryptedData”:”AES:bQclwcq3VsNGgrVAW5dqQ1T0HpsJjLiRgbD+3Y5mwJsHb”,”signature”:”MD:t5.=”,”templateURL”:”http:/cloudprint.cainia “+ action_typeString否128SEND,RECEIVESEND - 发货指令(执行向目的地进行发货动作) , RECEIVE - 收货指令(执行从来源地进行收货动作)默认值为 SEND. (如果为空, 也应

32、该视为SEND, 发货指令.)- 错误码业务错误码错误描述解决方案PAGE_SIZE_ILLEGAL业务异常,请求配送指令数量有误设置正确的page_size, 范围为1, 200.PRODUCE_ORDER_QUERY_FAILED业务异常,配送指令获取异常需要联系物料平台排查具体原因.3.6 配送指令接收反馈- API名称：ant.merchant.expand.assetdelivery.assign.sync （配送指令接收反馈接口）- API应用场景说明：当调用方调用了配送指令下达接口(3.5)后，并且供应商系统处理成功后调用该接口，保证再次获取配送指令接口时不会拉取到重复数据。-

33、参数详细说明:- 入参参数类型是否必填最大长度描述示例delivery_resultsAssetResult 是-配送指令接收情况，最多200条-+ successBoolean是64接口处理结果true+ assign_item_idString是64配送订单明细ID2017031620076002000006742800+ error_codeString否64错误码error_code+ error_descString否128error_desc错误描述- 响应参数参数类型是否必填最大长度描述示例delivery_resultsAssetResult 是1000配送指令反馈结果-+ s

34、uccessBoolean是64接口处理结果true+ assign_item_idString是64订单明细ID2017031620076002000006742800+ error_codeString否64错误码HAS_NO_ASSIGN_ITEM+ error_descString否128error_desc供应商名下无此分配记录- 错误码业务错误码错误描述解决方案HAS_NO_ASSIGN_ITEM供应商名下无此分配记录确认订单明细ID是否正确;如果确实无误, 那么需要联系物料平台排查具体原因.注意:(1)接口返回结果code不是 ”10000” (比如”20000”, “40004

35、) 时表示接口调用出现异常, 商家需要对所有订单重新进行反馈.(2) 接口返回结果code是”10000”, 表示接口调用成功, 商家需要从接口返回的结果中判断每个生产单是否更新成功, 取DeliveryResult中的success判断该订单是否处理成功, 商家需要对success为false的订单重新反馈.3.7 配送完成反馈- API名称：plete.sync （物料配送完成反馈接口）- API应用场景说明：当物料配送已经完成时，调用该接口。空码类型，需要回传递物流单号，物流公司信息。- 参数详细说明:- 入参参数类型是否必须最大长度描述示例值asset_delivery_details

36、AssetDeliveryDetail 是-物料配送单完成后指定物流信息-+ assign_item_idString是64订单明细ID2017031620076002000006742800+ amountInteger是128配送量+ logistics_infosLogisticsInfo否-物流信息可以为多个物流单，若配送给用户则需要必须传+ + logistics_noString否64物流单号400012131+ + logistics_nameString否64物流公司名称顺丰速运（见附录6.3）+ + logistics_codeString否64物流公司codeSF（见附录6

37、.3）- 响应参数参数类型是否必须最大长度描述示例值delivery_resultsAssetResult是-物料订单更新结果信息-+ successBoolean是64truetrue+ error_codeString否64errorCodeHAS_NO_ASSIGN_ITEM+ error_descString否64错误描述供应商名下无此分配记录+assign_item_idString是64订单明细ID订单明细ID- 错误码业务错误码错误描述解决方案HAS_NO_ASSIGN_ITEM供应商名下无此分配记录确认订单明细ID是否正确;如果确实无误, 那么需要联系物料平台排查具体原因.AS

38、SET_DELIVERY_PROCESS_EXCEPTION配送反馈更新失败异常先进行重试, 如果仍然有问题, 需要联系物料平台排查具体原因.注意:(1)接口返回结果code不是 ”10000” (比如”20000”, “40004) 时表示接口调用出现异常, 商家需要对所有订单重新进行反馈.(2) 接口返回结果code是”10000”, 表示接口调用成功, 商家需要从接口返回的结果中判断每个生产单是否更新成功, 取AssetResult中的success判断该订单是否处理成功, 商家需要对success为false的订单重新反馈.(3) 该接口暂不支持分批反馈, 在一个配送指令完成之后, 调

39、该接口一次性反馈(供应商可自行分批发货, 分多个包裹, 然后把所有物流单号反馈上来. 数量不要超过35个. ). 3.8 物料信息反馈接口- API名称：ant.merchant.expand.assetinfo.sync （物料信息反馈接口）- API应用场景说明：该接口用于向物料平台同步生产或配送完成的物料信息, 包括但不限于序列号, mac地址等.- 参数详细说明:- 入参参数类型是否必须最大长度描述示例值asset_infosAssetInfoItem 是-传入需要反馈的物料信息对象列表.-+ assign_item_idString是64订单明细IDDI201703162007600

40、2, PI2018020412324552+ typeString是64PRODUCE或者DELIVERY生产资料或配送资料+ sub_typeString是128具体物料信息类型, 定义见附录6.4.MC_SN_NOS - 机具序列号.+ valueString是3000物料信息,长度限制为3000, 格式按照附录6.4约定.机具序列号:"SN12312312312321", "SN99988889FE898"- 响应参数参数类型是否必须最大长度描述示例值info_resultsAssetResult是-物料订单更新结果信息-+ successBool

41、ean是64truetrue+ error_codeString否64errorCodeHAS_NO_ASSIGN_ITEM+ error_descString否64错误描述供应商名下无此分配记录+assign_item_idString是64订单明细IDDI2017031620076002, PI2018020412324552- 错误码业务错误码错误描述解决方案HAS_NO_ASSIGN_ITEM供应商名下无此分配记录确认订单明细ID是否正确;如果确实无误, 那么需要联系物料平台排查具体原因.INFO_SYNC_INVALID_COUNT物料信息反馈数量非法或者超过指令数量.反馈不超过指令

42、中生产或配送数量的物料信息.INFO_SYNC_DUP_VALUE物料信息重复反馈.已经反馈过该物料信息, 修改重复反馈的信息, 然后重试.INFO_LENGTH_INVALID物料信息长度不合法, 为空或者长度超过3000.如果是反馈信息长度超过3000 , 需要进行分批反馈注意:(1)接口返回结果code不是 ”10000” (比如”20000”, “40004) 时表示接口调用出现异常, 商家需要对所有订单重新进行反馈.(2) 接口返回结果code是”10000”, 表示接口调用成功, 商家需要从接口返回的结果中判断每个生产单是否更新成功, 取AssetResult中的success判断

43、该订单是否处理成功, 商家需要对success为false的订单重新反馈.(3) 物料信息反馈接口可以支持多次反馈, 如果该指令需要上传的物料信息长度超过3000, 需要进行分配次反馈. 多次反馈的数量总数不能超过指令中生产或配送数量.(4) 物料信息反馈入参说明.type 是DELIVERY还是PRODUCE需要供应商和业务确认生产配送流程之后确定.sub_type 具体物料信息类型, 这个也是业务确定之后, 字段各方进行约定, 具体值参见6.4.4 资源下载- SDK下载：（SDK中封装了签名，链接的逻辑，仅需要提供数据即可，强烈推荐使用）支付宝提供的版本有: java(jdk1.5)版,

44、 java(jdk1.4)版, .net(2010)版, .net(2005)版, php版.- 秘钥生成：如果无法访问下载, 联系物料平台开发.5 FAQ5.1 openapi接口返回参数怎么理解?(1) 接口返回成功:比如下图是api:ant_merchant_expand_assetproduce_assign_query_response的返回结果, code为”10000”, msg为”Success”, 其余的(asset_produce_items, has_next_page)是业务返回. 外层的sign值给商户进行验签, 商家可用”支付宝公钥”进行验签, 确定是来自支付宝的返

45、回.(2) 接口返回失败:看下面两个失败的场景:上图是由于业务系统繁忙, openapi调用失败, 商家可以进行重试, 长时间不可用可联系我们.上图是sub_code为”PAGE_SIZE_ILLEGAL”, 可以在本文档1.3看到, 这是由我们业务系统返回的错误码, 因为我们业务系统做了限制, 每次只能最多请求200个, 不满足就报这个异常.5.2 openapi接口参数规范(1) 成功返回规范码code（返回码枚举值）：统一为10000msg （返回码类型）：统一为Successsub_code（子错误码）：统一为空sub_msg（错误描述）：统一为空(2) 业务失败返回规范码code（返回码枚举值）：统一为40004msg（返回码类型）：对于业务系统统一为Business F