马上赢开放平台

马上赢开放平台的API是基于HTTP协议来调用的。

请求地址

环境	URL
测试环境	https://api.yikuaigao.com/rest
正式环境	https://api.banmahui.cn/rest

公共参数

调用任何一个API都必须传入的参数，目前支持的公共参数有：

参数名称	必填	类型	示例	说明
version	是	String(32)	1.0.0	接口版本
method	是	String(32)	item.product.get	接口名称(根据请求的接口决定)
charset	否	String(8)	UTF-8	字符集，可选值，默认为 UTF-8
sign_type	否	String(8)	MD5	签名类型，取值：MD5，默认：MD5
sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名结果，详见“签名算法”
appid	是	String(32)	13682463	我方分配的应用ID
nonce_str	是	String(32)	5K8264ILTKCH16CQ	随机字符串，不长于 32 位

业务参数

API调用除了必须包含公共参数外，如果API本身有业务级的参数也必须传入，每个API的业务级参数请考API文档说明。

签名算法

为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。数字签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。一般失败的结果不签名。

无论是请求还是应答，签名原始串按以下方式组装成字符串：

除 sign 字段外，所有参数按照字段名的 ascii 码从小到大排序后使用 QueryString 的格式（即 key1=value1&key2=value2…）拼接而成，空值和数组不传递，不参与签名组串。
签名原始串中，字段名和字段值都采用原始值，不进行 URL 编码。
返回的应答或通知消息可能会由于升级增加参数，请验证应答签名时注意允许这种情况。

通过在签名原始串后加上通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。注意：签名时将字符串转化成字节流时指定的编码字符集应与参数charset一致。

MD5签名计算公式为

sign = md5(原字符串&key=应用密钥).toUpperCase()

签名工具

调用示例：

调用某个接口，接口有如下字段

<xml>
  <version>1.0.0</version>
  <method>item.product.get</method>
  <appid>13682463</appid>
  <nonce_str>58feb19886422</nonce_str>
  <product_id>6934522809831</product_id>
</xml>

签名字段排序后签名原始串为：

appid=13682463&method=item.product.get&nonce_str=58feb19886422&product_id=6934522809831&version=1.0.0

计算签名为：

md5("appid=13682463&method=item.product.get&nonce_str=58feb19886422&product_id=6934522809831&version=1.0.0&key=e1cf0ddcf6b47b59c351565d8ad717af")
.toUpperCase()
= "DB1FCAA31660653116955BF13230A912"

数据格式

接口请求采用 HTTP 标准的 POST 协议。请求和应答数据可使用标准 XML 格式或 JSON 格式，所有参数只存在一级节点中，不采用多级节点嵌套。

XML 格式示例

接口请求数据格式：

<xml>
  <version>1.0.0</version>
  <method>item.product.get</method>
  <appid>13682463</appid>
  <nonce_str>58feb19886422</nonce_str>
  <sign>DB1FCAA31660653116955BF13230A912</sign>
  <product_id>6934522809831</product_id>
</xml>

正确返回数据：

<xml>
  <return_code>SUCCESS</return_code>
  <return_msg><![CDATA[OK]]></return_msg>
  <nonce_str><![CDATA[FvYSnPuFFPkAr77M]]></nonce_str>
  <sign><![CDATA[63238039D6E43634297CF2A6EB5F3B72]]></sign>
  <result_code>SUCCESS</result_code>
  <product_id>6934522809831</product_id>
  <title><![CDATA[农心吸汗巾NX-9831]]></title>
  <price>20.0</price>
</xml>

业务级错误返回：

<xml>
  <err_code><![CDATA[PRODUCT_NOT_FOUND]]></err_code>
  <err_code_des><![CDATA[条码 ‘6934522809831' 未找到]]></err_code_des>
  <return_code>SUCCESS</return_code>
  <return_msg><![CDATA[OK]]></return_msg>
  <nonce_str><![CDATA[FvYSnPuFFPkAr77M]]></nonce_str>
  <sign><![CDATA[6277A96D7875D4FF23AA7B6A4C3046AB]]></sign>
  <result_code>FAIL</result_code>
</xml>

协议级错误返回：

<xml>
  <err_code>APP_NOT_FOUND</err_code>
  <err_code_des>appid 不存在</err_code_des>
  <return_code>FAIL</return_code>
  <return_msg>appid 不存在</return_msg>
  <charset>UTF-8</charset>
  <version>1.0.0</version>
  <sign_type>MD5</sign_type>
  <nonce_str>5cd3a82138054</nonce_str>
</xml>

JSON 格式

使用 json 格式需要在请求时添加 http 头 Content-Type: application/json 。

接口请求数据格式：

{
  "version": "1.0.0",
  "method": "item.product.get",
  "appid": "13682463",
  "nonce_str": "58feb19886422",
  "sign": "DB1FCAA31660653116955BF13230A912",
  "product_id": "6934522809831"
}

正确返回数据：

{
  "return_code": "SUCCESS",
  "return_msg": "OK",
  "nonce_str": "FvYSnPuFFPkAr77M",
  "sign": "63238039D6E43634297CF2A6EB5F3B72",
  "result_code": "SUCCESS",
  "product_id": "6934522809831",
  "title": "农心吸汗巾NX-9831",
  "price": "20.0"
}

业务级错误返回：

{
  "err_code": "PRODUCT_NOT_FOUND",
  "err_code_des": "条码 6934522809831 未找到",
  "return_code": "SUCCESS",
  "return_msg": "OK",
  "nonce_str": "FvYSnPuFFPkAr77M",
  "sign": "6277A96D7875D4FF23AA7B6A4C3046AB",
  "result_code": "FAIL"
}

协议级错误返回：

{
  "err_code": "APP_NOT_FOUND",
  "err_code_des": "appid 不存在",
  "return_code": "FAIL",
  "return_msg": "appid 不存在",
  "charset": "UTF-8",
  "version": "1.0.0",
  "sign_type": "MD5",
  "nonce_str": "5cd3a82138054"
}

错误码说明

err_code	err_code_des
METHOD_NOT_ALLOW	请使用POST方法访问
XML_PARSE_FAIL	XML 格式错误
DATA_PARSE_FAIL	数据格式错误
INVALID_REQUEST	请求参数错误
APP_NOT_FOUND	appid 不存在
SERVER_ERROR	服务器错误
APP_DOES_NOT_HAVE_SCOPE	app 没有相应权限
SIGNATURE_MISMATCH	签名不匹配
PRODUCT_NOT_FOUND	条码未找到
REPORT_NOT_FOUNE	报表未找到