View the English version

一、发起请求

字符集:utf-8

Headers 的 Content-Type:"application/json"


通过发送POST报文到请求地址,以获取或提交特定业务数据。以下以获取订单列表数据为例:


该业务的示例请求地址:

  http://专用业务域名/api/orders 贵公司的专用业务域名请联系技术服务人员获得。

点击此处可查看接口调试演示页面(注意:该页仅用于演示,如需调试贵公司的接口,请直接访问您的专用业务域名即可进入调试页)


请求报文:

{

  "app_id": 1000012965,
  "data": {
    "page_number": 1,
    "page_size": 10,
    "include_details": false,
    "timestamp": 9876543210123
  },
  "nonce_str": "ABCDE0123456789ABCDE0123456789",
  "sign": "123456789ABCDE0123456789ABCDE0"
}

字段说明:

参数 作用

app_id

贵公司使用的启网用户号

data

关于查询业务的扩展数据,

page_number:页码

page_size:分页大小

include_details:指示返回的数据是否同时包含明细数据(这里指的是订单的商品明细),

timestamp:时间戳

nonce_str

32位随机字符串

sign

MD5签名


响应报文(application/json,仅在Response Code为200时表示服务器成功响应,这时才需继续后续判断):

{
  "app_id": 1000012965,
  "result_code": 0,
  "result_msg": "",
  "data": {
    "page_number": 1,
    "page_size": 1,
    "total_count": 43,
    "total_pages": 43,
    "results": [
      {
        "id": 1,
        "code": "SD0011611-000001",
        "create_time": "2016-11-23T11:23:49",
        "amount": 6,
        "customer_id": 2,
        "dept_id": 1,
        "stock_id": 1,
        "invoice_type": 3001,
        "delivery_address": "广东省 广州市 启网软件公司",
        "consignee_name": "启网软件",
        "consignee_mobile": "12345678901",
        "delivery_date": "2016-11-23T11:23:49",
        "memo": "",
        "quantity": 1,
        "approved_amount": 6,
        "approved_quantity": 1,
        "modify_time": "2016-11-23T11:23:49",
        "is_scrap": false
        "details": null,
      }
    ],
    "include_details": false,
    "timestamp": 637638692306895600
  },
  "nonce_str": "89D7E709ED265D977084ECD9D7CD9762",
  "sign": "B3EF586E690F01D25524EDFA84459CA3"
}

字段说明:

参数 作用

app_id

贵公司使用的启网用户号

result_code

错误代码,0表示操作成功,其它值表示的意思详见贵公司实际的接口调试页面

result_msg

错误描述

data

返回的查询数据,

page_number:页码,

page_size:分页大小,

total_count:总项数,

total_pages:总页数,

results:表示订单列表(其中字段解释详见接口调试页),

include_details:指示返回的数据是否同时包含明细数据(这里指的是订单的商品明细),

timestamp:时间戳

nonce_str:

32位随机字符串

sign

MD5签名


二、签名

在提交到服务器的JSON格式请求报文中的字段'sign'的生成算法:

  MD5(app_id + '_' + AppKey + '_' + JSON(data) + '_' + nonce_str),其中:

参数 作用

AppKey

用于访问启网API接口的唯一标识码,由启网软件公司向贵公司提供(请联系技术服务人员获得)

JSON(data)

将'data'字段转换为JSON字符串形式,格式:无缩进,无空白格式字符(即最小化压缩)

例如,使用这些方法:

  JSON.stringify(data) 或 

  Newtonsoft.Json.JsonConvert.SerializeObject(data, Newtonsoft.Json.Formatting.None)

MD5(params)

使用MD5算法计算params值的十六进制的哈希码,

其中params为将所有值按顺序用字符'_'(不包括引号)连接后的字符串参数,确保参数中的字符串为UTF-8编码。


其他字段的注释:

参数 作用

app_id

请求体的模型类'ApiRequest'的字段'app_id'

data

请求体的模型类'ApiRequest'的字段'data'

请严格遵循相关请求体模型类的字段定义:包括名称和顺序,即使值是null也必须包含在JSON请求体中。

如果您定义的模型类与要求的不匹配或某一字段丢失,将会导致签名验证失败。

nonce_str

请求体的模型类'ApiRequest'的字段'nonce_str'


三、验签

使用以下算法为服务器端返回的JSON格式响应报文的相关字段生成签名。

生成算法:

  MD5(app_id + '_' + AppKey + '_' + JSON(data) + '_' + result_code + '_' + result_msg + '_' + nonce_str),其中:

参数 作用

AppKey

用于访问启网API接口的唯一标识码,由启网软件公司向贵公司提供(请联系技术服务人员获得)

JSON(data)

将'data'字段转换为JSON字符串形式,格式:无缩进,无空白格式字符(即最小化压缩)

例如,使用这些方法:

  JSON.stringify(data) 或 

  Newtonsoft.Json.JsonConvert.SerializeObject(data, Newtonsoft.Json.Formatting.None)

MD5(params)

使用MD5算法计算params值的十六进制的哈希码,

其中params为将所有值按顺序用字符'_'(不包括引号)连接后的字符串参数,确保参数中的字符串为UTF-8编码。


然后将上述签名值与响应体模型类'ApiResponse'的字段'sign'的值进行比较。

如果两个值相等,则签名通过,否则必须丢弃所返回的响应数据。


其他字段的注释:

参数 作用

app_id

响应体的模型类'ApiResponse'的字段'app_id'

data

响应体的模型类'ApiResponse'的字段'data' 

请严格遵循相关响应体模型类的字段定义:包括名称和顺序,即使值是null也必须包含在JSON响应体中。

如果您定义的模型类与要求的不匹配或某一字段丢失,将会导致签名验证失败。

result_code

响应体的模型类‘ApiResponse’的字段‘result_code’

result_msg

响应体的模型类‘ApiResponse’的字段‘result_msg’

nonce_str

响应体的模型类'ApiResponse'的字段'nonce_str'。


四、响应体的模型类'ApiResponse'的字段'result_code'的值说明:

代码 解析

0

操作成功

1

参数'app_id'错误(包括丢失或无效)

2

参数'nonce_str'错误

3

参数'sign'错误

4

签名失败

5

验证签名失败

6

'nonce_str'不能重复使用

7

数据资源关联错误

8

数据库访问失败

400

无效请求(包括以下参数:path、query或body)

404

找不到数据资源。


五、其它文档:

 演示代码(C#)

 下载相关类库 (.NET Framework)

  MD5签名Demo(C#)