食品和食用农产品追溯系统接口服务功能示例.docxVIP

食品和食用农产品追溯系统接口服务功能示例

授权接口

接口地址

接口地址示例：https://{域名}:{端口}/api/v1/auth。

功能说明

系统认证接口，验证调用方的appKey和签名，验证通过后，返回数字令牌。

参数说明

提交方法(Method)：提交（Post）。

请求头(Header)：如表A.1所示。

授权接口请求头(Header)表

参数名称

数据类型

是否必填

描述

Content-Type

String

是

请求数据的内容类型字符串，固定为：application/json;charset=utf-8

请求参数以JSON格式消息体(Body)传输，如表A.2所示。

授权接口请求参数表

参数名称

数据类型

是否必填

描述

appKey

String

是

服务端提供给调用者的凭证，用于标识服务接口调用者的身份

timestamp

Timestamp

是

接口调用时间

signature

String

是

请求签名，用于验证此次请求的合法性，由调用者根据实际的输入参数，并凭密钥（appSecret）和约定的签名算法生成的签名

返回内容类型(Content-Type)：application/json;charset=utf-8。

返回数据的参数说明，如表A.3所示。

授权接口返回参数表

参数名称

数据类型

是否必填

描述

success

Boolean

是

接口调用结果，包括以下两种结果：

True=接口调用成功；

False=接口调用失败。

code

Number

是

接口响应码，见A.11

表A.3授权接口返回参数表（续）

参数名称

数据类型

是否必填

描述

message

String

否

接口提示信息

result

Object

是

接口调用成功后，返回的数据对象

token

String

是

接口调用成功后，返回的数字令牌

expired

Timestamp

是

数字令牌的过期时间

code

Number

是

接口响应码，见A.11

请求示例

授权接口请求的消息示例如下所示。

请求方法：Post

URL：/api/v1/auth

请求头:

Content-Type:application/json;charset=utf-8

请求消息体：

{

appKey:ak00001,

timestamp:1711001391000,

signature:xxxxxxxxxxx

}

返回示例

授权接口返回的解密后的消息明文示例如下所示。

{

success:true,

code:200,

result:

{

token:xxxxxxxx.xxxxxxxxxxxxxxxxxx.xxxxxxxx,

expired:1711011391000

}

}

上传接口

接口地址

接口地址示例：https://{域名}:{端口}/api/v1/{数据元标识}。

{数据元标识}为上传的追溯信息数据集的唯一标识，例如product表示产品信息。具体可参考DB31/T1110.2。

功能说明

追溯信息的上传接口。

参数说明

提交方法(Method)：提交（Post）。

请求头(Header)：如表A.4所示。

上传接口请求头(Header)表

参数名称

数据类型

是否必填

描述

Content-Type

String

是

请求数据的内容类型字符串，固定为：application/json;charset=utf-8

Authorization

String

是

调用者的认证凭据，由固定字符串Bearer+数字令牌字符串拼接而成

请求参数以JSON格式消息体(Body)传输，如表A.5所示。

上传接口请求参数表

参数名称

数据类型

是否必填

描述

data

Array

是

按照数据元的标识和数据元的值，构造数据元的JSON对象，并可将多条数据元JSON组合为一个Array放入该参数值中，实现批量上传。

返回内容类型(Content-Type)：application/json;charset=utf-8。

返回数据的参数说明，如表A.6所示。

上传接口返回参数表

参数名称

数据类型

是否必填

描述

success

Boolean

是

接口调用结果，包括以下两种结果：

True=接口调用成功；

False=接口调用失败。

code

Number

是

接口响应码，见A.11

message

String

否

接口提示信息

请求示例

上传接口请求的消息示例如下所示。

请求头:

Content-Type:application/json;charset=