**生产平台 Matrix** 是生产者定义发行 Token 的平台，该平台提供商品及其 Token 定义、信息查询、物流信息同步等服务。具体接口如下：
[TOC]
## 演示环境
演示环境：https://matrixdemo.stringon.com
接口地址：https://matrixdemo.stringon.com/api/……
请在演示环境注册测试账号，登录后通过访问：账户 > 安全设置，获取 apiKey 和 apiSecret。
> **注**：以下接口可使用统一的api_key + api_secret签名方式访问，如：
>* api_key: 1c2966df9ea7480ebb29dc863404a7af
>* api_secret: 780221dac2634d7b9a3aba1ebe97f0b4
**假设传送以下参数：**
api_key: 1c2966df9ea7480ebb29dc863404a7af
spu\_ids: 13,14
origins: 0t5e209wv04tmymw
nonce_str: bFC253c29116D8f3 // nonce_str: 是一个随机数，长度在8~32位之间，主要是为保证签名不可预测
> **签名过程如下**
> 1. 参数按字典序排列，拼成URL键值对的格式（key1=value1&key2=value2… ），参数的值为空不参与签名，拼接成字符串stringA；
stringA = "api_key=1c2966df9ea7480ebb29dc863404a7af&nonce_str=bFC253c29116D8f3&origins=0t5e209wv04tmymw&spu_ids=13,14"
>**(请注意：如果参数值中存在特殊字符，如：空格、=、/ 等，不需做URL Encoder)**
> 2. 在stringA最后拼接上apiSecret得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到signature值
stringSignTemp = stringA + api_secret;
最终：stringSignTemp = "api_key=1c2966df9ea7480ebb29dc863404a7af&nonce_str=bFC253c29116D8f3&origins=0t5e209wv04tmymw&spu_ids=13,14780221dac2634d7b9a3aba1ebe97f0b4"
> 3. signature = MD5(stringSignTemp).toUpperCase();
经MD5运算，再转大写，将得到：signature=316AE3E43E6BB3D6196F298CE99B5195
> 4. 最终得到最终发送的数据：
>* **GET请求参数：**
api_key=1c2966df9ea7480ebb29dc863404a7af&spu\_ids=13,14&origins=0t5e209wv04tmymw&nonce_str=bFC253c29116D8f3&signature=316AE3E43E6BB3D6196F298CE99B5195
>* **POST请求：**
**Content-Type: application/x-www-form-urlencoded**
api_key=1c2966df9ea7480ebb29dc863404a7af
spu\_ids=13,14
origins=0t5e209wv04tmymw
nonce_str=bFC253c29116D8f3
signature=316AE3E43E6BB3D6196F298CE99B5195
> **Content-Type: application/json**
{
"api_key": "1c2966df9ea7480ebb29dc863404a7af",
"spu_ids": "13,14",
"origins": "0t5e209wv04tmymw",
"nonce_str": "bFC253c29116D8f3",
"signature": "316AE3E43E6BB3D6196F298CE99B5195"
}
## 1. 商品接口
### 1.1 获取商品类目
接口名称：获取商品类目
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：获取所有商品类目信息
~~~[api]
get:/api/v2/prod/category/list
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"id": 2,
"parent_id": 0,
"cat_name": "男人",
"sort": 20000,
"status": 1,
"created_at": "2019-04-11T18:55:43.000Z",
"updated_at": "2019-04-11T18:55:43.000Z",
"children": [],
"root": true
},
{
"id": 3,
"parent_id": 0,
"cat_name": "食品",
"sort": 30000,
"status": 1,
"created_at": "2019-04-11T18:55:43.000Z",
"updated_at": "2019-04-11T18:55:43.000Z",
"children": [],
"root": true
},
...
]
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | array(object) | 返回数据 |
| id | integer | 分类ID |
| cat_name | string | 分类名称 |
| parent_id | integer | 父分类ID |
| sort | integer | 显示顺序 |
| status | integer | 状态：1=可用; 2=停用 |
| created_at | integer | 创建时间 |
| updated_at | integer | 更新时间 |
| children | array | 子分类数组 |
| root | boolean | 是否为根结点 |
### 1.2 获取商品 ID
接口名称： 获取 Token 的商品 ID（spu_id、sku_id）
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：根据 Token origin，获取商品 spu_id 和 sku_id，多个 Token origin 之间用逗号分隔
~~~[api]
post:/api/v2/prod/spu/find
origins#原始Token标识，多个Token之间逗号分隔，如：0t5e209wv04tmymw,ap4ac9rae3tedvh0
producer_ids#按生产商ID查询，多个生产商ID之间用逗号分隔，如：190417552262,190417969915
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"origin": "0t5e209wv04tmymw", // 原始Token标识
"sku_id": 54, // Matrix平台SKU ID
"spu_id": 15 // Matrix平台SPU ID
},
{
"origin": "ap4ac9rae3tedvh0",
"sku_id": 140,
"spu_id": 25
}
]
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功，600: 参数不正确；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | array(object) | 返回数据 |
| origin | string | 原始Token标识 |
| sku_id | integer | Matrix平台SKU ID |
| spu_id | integer | Matrix平台SPU ID |
### 1.3 获取商品 SKU 信息
接口名称： 获取商品 SKU 信息
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：根据原始Token标识，获取商品 SKU 信息
~~~[api]
get:/api/v2/prod/sku/get
*origin#Token原始标识
<<<
success
{
"code": 0,
"msg": "成功"
"data": {
"spu_id": 25,
"uid": 190420811977,
"caption": "女子运动鞋 Nike Air Max 720",
"unit_name": "双",
"subcaption": "Nike Air Max 720 女子运动鞋搭载 Nike 革命性的大型 Air 气垫，为足下注入许多空气，带来非凡舒适脚感。Air Max 的大体积设计让你耳目一新？当然是大体积的好。",
"shortcaption": null,
"type": 1,
"belongs": [
1
],
"keywords": [
"Nike Air Max 720 女子运动鞋搭载 Nike 革命性的大型 Air 气垫",
"为足下注入许多空气",
"带来非凡舒适脚感。Air Max 的大体积设计让你耳目一新？当然是大体积的好。"
],
"specs": [
{
"key": "1555904570707",
"name": "颜色",
"values": [
{
"key": "1555904570718",
"name": "金属银/深藏青",
"image": {
"res_key": "http://img.stringon.com/33b033dfcc8e4effa78fcf0ead8716cd"
}
},
{
"key": "1555905697622",
"name": "白金色/氧气紫/太空紫/氧气紫",
"image": {
"res_key": "http://img.stringon.com/83c767fbb4f14f359e8e483f6a9896b3"
}
},
{
"key": "1555905824401",
"name": "白色/激光紫红/上升粉",
"image": {
"res_key": "http://img.stringon.com/c7134860c9df4a869f3a92559a00f78b"
}
}
]
},
{
"key": "1555905923663",
"name": "尺码",
"values": [
{
"key": "1555905923669",
"name": "35.5"
},
{
"key": "1555906332700",
"name": "36"
},
{
"key": "1555906335480",
"name": "36.5"
},
{
"key": "1555906349430",
"name": "37.5"
},
{
"key": "1555906353155",
"name": "38"
},
{
"key": "1555906361917",
"name": "38.5"
},
{
"key": "1555906367509",
"name": "39"
},
{
"key": "1555906374495",
"name": "40.5"
},
{
"key": "1555906378208",
"name": "41"
},
{
"key": "1555906380537",
"name": "42"
}
]
}
],
"params": [],
"slideshow": [
{
"res_key": "http://img.stringon.com/e3f1ad6569a7407ea4b14bb3c59b433d"
},
{
"res_key": "http://img.stringon.com/f54e3dd9fdbb4ccfb740f9f05f76b39d"
},
{
"res_key": "http://img.stringon.com/ee6de0839a6942cba7a0672e0fcef8d3"
}
],
"intro_imgs": [
{
"res_key": "http://img.stringon.com/40330b6c3bfb4294b1b57ad3546ecc3b"
},
{
"res_key": "http://img.stringon.com/4dac8935730e411898621ef8ee1c4e18"
},
{
"res_key": "http://img.stringon.com/3cfc2c09dc3649849a4bcc6846acc8cb"
}
],
"brand_id": null,
"group_id": null,
"delivery_type": 1,
"delivery_start": 3,
"delivery_end": null,
"status": 1,
"created_at": "2019-04-22T04:13:23.000Z",
"updated_at": "2019-04-22T04:16:03.000Z",
"sku_list": [
{
"sku_id": 140,
"spu_id": 25,
"uid": 190420811977,
"specs": {
"image": {
"res_key": "http://img.stringon.com/c7134860c9df4a869f3a92559a00f78b",
},
"尺码": "37.5",
"颜色": "白色/激光紫红/上升粉"
},
"spe_code": null,
"bar_code": null,
"cost": "300.00",
"status": 0,
"created_at": "2019-04-22T04:13:23.000Z",
"updated_at": "2019-04-22T04:13:23.000Z"
}
]
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功，600: 参数不正确; 602: origin不存在；500: 系统内部错误 |
| message | string | 错误原因 |
| data | array | sku信息 |
| spu_id | integer | supID |
| uid | integer | 生产商id |
| caption | string | 商品名称 |
| unit_name | string | 单位 |
| subcaption | string | 商品副标题 |
| shortcaption | string | 商品短标题 |
| type | string | 商品类型 0: 实物商品, 1: 虚拟商品 |
| belongs | array(string) | 所属分类数组 |
| keywords | array(string) | 搜索关键字数组 |
| specs | array(object ) | 规格项数组 |
| params | array(object) | 参数数组 |
| slideshow | array(object) | 轮播图url数组 |
| intro_imgs | array(string) | 商品详情图url数组 |
| brand_id | integer | 品牌商id |
| group_id | integer | 分组id |
| delivery_type | integer | 发货类型：1=提货申请后x天发货; 2=固定时段 |
| delivery_start | date | 发货起始时间 |
| delivery_end | date | 发货结止时间 |
| status | integer | 状态：0=维护中; 1=待发布; 2=已发布; |
| created_at | date | 创建时间 |
| updated_at | date | 修改时间 |
| sku_list | array(object) | sku信息 |
| sku_id | integer | skuID |
| spu_id | integer | supID |
| uid | integer | 生产商id |
| specs | array(object ) | 规格项数组 |
| spe_code | string | 规格编码 |
| bar_code | string | 条码 |
| cost | string | 成本 |
| status | integer | 状态：0=未发布; 1=已发布; |
| created_at | date | 创建时间 |
| updated_at | date | 修改时间 |
### 1.4 获取商品 SPU 信息
接口名称：获取商品 SPU 信息
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：获取指定商品 spu_ids 的完整商品信息，内容包括：商品信息、全部 SKU 信息
参数：spu_ids、origins 至少一项不为空
~~~[api]
post:/api/v2/prod/sync/spu
spu_ids#一个或多个商品SPU ID，多个之间用逗号分隔
origins#一个或多个合约名称,多个之间用逗号分隔
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"spu_id": 64,
"caption": "钢笔",
"unit_name": "支",
"subcaption": "描述描述",
"shortcaption": null,
"type": 1,
"belongs": [
21
],
"keywords": [
"钢笔关键字"
],
"specs": [
{
"key": "1557210984839",
"name": "规格1",
"values": [
{
"key": "1557210984854",
"name": "规格1111",
"image": {
"res_key": "http://img.stringon.com/00cec074eef64a25b1f289b8ec4ef2a3",
}
},
{
"key": "1557211054760",
"name": "规格222",
"image": {
"res_key": "http://img.stringon.com/638c9045c89a45eea8244e0c2cba3697",
}
}
]
}
],
"params": [],
"slideshow": [
{
"res_key": "http://img.stringon.com/00cec074eef64a25b1f289b8ec4ef2a3",
},
{
"res_key": "http://img.stringon.com/3529218792ec4c6e9ed9da5737eb18dd",
}
],
"intro_imgs": [
{
"res_key": "http://img.stringon.com/587973ee57874669bac38b9ac0163098",
},
{
"res_key": "http://img.stringon.com/638c9045c89a45eea8244e0c2cba3697",
}
],
"brand_id": null,
"group_id": 18,
"delivery_type": 2,
"delivery_start": 1557215077,
"delivery_end": 1557215077,
"status": 2,
"created_at": "2019-05-07T06:38:07.000Z",
"updated_at": "2019-05-07T07:54:51.000Z",
"sku_list": [
{
"sku_id": 279,
"spu_id": 64,
"specs": {
"image": {
"res_key": "http://img.stringon.com/00cec074eef64a25b1f289b8ec4ef2a3",
},
"规格1": "规格1111"
},
"spe_code": "22",
"bar_code": "11",
"cost": "11.00",
"status": 1,
"created_at": "2019-05-07T06:38:07.000Z",
"updated_at": "2019-05-07T06:44:01.000Z",
"contract_list": [
{
"contract_id": 874,
"origin": "39079a1p8t8gt0ky",
"sku_id": 279
}
]
},
{
"sku_id": 280,
"spu_id": 64,
"specs": {
"image": {
"res_key": "http://img.stringon.com/638c9045c89a45eea8244e0c2cba3697",
},
"规格1": "规格222"
},
"spe_code": "22",
"bar_code": "11",
"cost": "11.00",
"status": 1,
"created_at": "2019-05-07T06:38:07.000Z",
"updated_at": "2019-05-07T06:44:01.000Z",
"contract_list": [
{
"contract_id": 875,
"origin": "rp78an19238me8eg",
"sku_id": 280
}
]
}
]
}
]
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功，600: 参数不正确；500: 系统内部错误 |
| message | string | 错误原因 |
| data | array | 返回数据 |
| spu_id | integer | spuid |
| caption | string | 商品名称 |
| subcaption | string | 商品副标题 |
| shortcaption| string | 商品短标题 |
| type | string | 商品类型 0: 实物商品, 1: 虚拟商品 |
| belongs | array(string) | 所属分类数组 |
| keywords | array(string) | 搜索关键字数组 |
| specs | array(object ) | 规格项数组 |
| params | array(object) | 参数数组 |
| slideshow | array(string) | 轮播图url数组 |
| intro_imgs | array(string) | 商品详情图url数组 |
| brand_id | string | 品牌商id |
| status | integer | 0:维护中, 1:待发布, 2:已发布 |
| created_at | date | 创建时间 |
| updated_at | date | 修改时间 |
| sku_list | array(object) | sku信息 |
| sku_id | integer | sku_id |
| spu_id | integer | spu_id |
| specs | array(object ) | 规格项数组 |
| spe_code | string | 规格编码 |
| bar_code | string | 条码 |
| cost | string | 成本 |
| status | integer | 0=未流通; 1=已流通（处理锁定状态） |
| created_at | date | 创建时间 |
| updated_at | date | 修改时间 |
| batch_list | array(object) | 批次信息 |
| symbol | string | token标识 |
| sku_id | integer | sku_id |
| spu_id | integer | spu_id |
| uid | integer | 生产商id |
| publish_id | integer | 流水号 |
| total_supply | integer | 发行量 |
| status | integer | 1=待发行; 2=已发行; 3=已作废; 4=已流通 |
| created_at | date | 创建时间 |
| updated_at | date | 修改时间 |
| transfer_to_add | string | 生产商token回收地址 |
### 1.5 获取已变更商品列表
接口名称：获取已变更商品列表
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：根据指定同步时间，获取该时间之后的变更商品列表
~~~[api]
post:/api/v2/prod/sync/list
*last_time#上次同步时间，格式为：1552361703000，单位：毫秒
int:producer_id#可空，生产商ID，查询指定生产商的商品变更信息
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
"spu_id":8
]
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600: 参数不正确；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | object | 返回数据 |
| spu_id | integer | 商品id |
### 1.6 查询简单商品SKU信息
接口名称：简单商品SKU信息
请求数据类型：X-WWW-FORM-URLENCODED 或 JSON
响应类型：JSON
状态：有效
接口描述：根据凭证名称(origin)和sku id查询简单商品信息
请求参数说明：
origins和sku_ids：至少一项不为空；
**请求类型为：application/x-www-form-urlencoded**
origins[0]=hfh1ukjr1hxmxdfg
origins[1]=hfh1ukjr1hxmxdfg
sku_ids[0]=392
sku_ids[1]=393
**请求类型为：application/json**
{
"origins":["hfh1ukjr1hxmxdfg","gp0ymumbmmq42fty"],
"sku_ids": [392,393]
}
~~~[api]
post:/api/v2/prod/sku/find
array:origins#凭证名称，数组类型，如："origins":["hfh1ukjr1hxmxdfg","gp0ymumbmmq42fty"]
array:sku_ids#商品SKU ID，数组类型，如："sku_ids": [392,393]
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"sku_id": 392,
"specs": {
"image": {
"res_key": "http://img.stringon.com/587973ee57874669bac38b9ac0163098"
},
"规格名": "规格值1"
},
"spu_id": 82,
"caption": "海淘商品",
"unit_name": "个",
"origins": [
"hfh1ukjr1hxmxdfg"
]
},
{
"sku_id": 393,
"specs": {
"image": {
"res_key": "http://img.stringon.com/76c194c37f48472d8ef1d566e34d055f"
},
"规格名": "规格值2"
},
"spu_id": 82,
"caption": "海淘商品",
"unit_name": "个",
"origins": [
"gp0ymumbmmq42fty"
]
}
]
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600: 参数不正确；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | object | 返回数据 |
| spu_id | integer | 商品id |
## 2. 提货接口
### 2.1 获取提货商家回收地址
接口名称: 获取提货商家回收地址
请求数据类型：X-WWW-FORM-URLENCODED
响应类型: JSON
状态：有效
接口描述： 获取提货商家回收地址
~~~[api]
post:/api/v2/pickup/fetchAddr
*origin#token原始标识
<<<
success
{
code：0
msg: '成功'
data:{
address: 'OX0DGGSDFFDG'
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；2102: 提货商品不存在；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | object| 返回数据 |
| address | string | 地址 |
### 2.2 提货申请
接口名称：提货申请
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：客户提货申请
~~~[api]
post:/api/v2/pickup/apply
*txid#交易id
*out_pickup_no#商城提货单号
int:amount#提货数量
*consignee#收货人
*cellphone#收货人手机号
area#地区
*address#收货地址
zipcode#邮编
*notify_url#处理结果，通知商城
<<<
success
{
"code": 0,
"msg": "提货申请成功",
"data": {
pickup_no:生产平台提货单号,
out_pickup_no:商城提货单号,
txid: 交易ID,
status: 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败,
amount: 提货数量（从链上查询得到）
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0:成功；405: 无权访问 ；1021: 用户被禁用；2700: 提货单Txid已存在；2600：txid校验失败；2601：提货数量与链上不一致；2701：未查到对应的商品；2702：发行地址与链上地址不一致 ；2000：提货失败|
| msg| string | 错误原因 |
| data | object | 返回数据 |
| pickup_no | string | 生产平台提货单号 |
| out_pickup_no | string | 商城提货单号 |
| txid | string | 交易ID |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败 |
| amount | integer | 提货数量(从链上查询得到) |
### 2.3 发货通知
接口名称：发货通知
请求数据类型：APPLICATION/JSON
响应类型：JSON
状态：有效
接口描述：由生产商ERP系统调用，真实发货后，通知生产平台提货单状态变化
**请求参数**
~~~
{
"pickup_no": "11001904028341836781", // 生产平台提货单唯一编号
"out_delivery_no": "1001201112", // ERP发货单唯一编号
"receipt_list": [ // 生产商发货信息及Token信息
{
"txid": "0C697F48392907A015959A00DB1CC6AF", // 交易ID
"waybill_no": "01203131231231", // 运单号
"serial_no": "01203131231231", // 商品编码，可空
"logistic_no": "01203131231231", // 物流商编号，可空
"logistic_name": "顺风" // 物流商名称，可空
}
]
}
~~~
~~~[api]
post:/api/v2/pickup/delivered
headers:[
{"egg_matrix_api_key":"aa"},
{"egg_matrix_sign":"bb"},
{"ts":4323435}
]
body:{
"pickup_no": "11001904028341836781",
"out_delivery_no": "1001201112",
"receipt_list": [
{
"txid": "0C697F48392907A015959A00DB1CC6AF",
"waybill_no": "01203131231231",
"serial_no": "01203131231231",
"logistic_no": "01203131231231",
"logistic_name": "顺风"
}
]
}
<<<
success
{
"code": 0,
"msg": "发货通知成功",
"data": {
"pickup_no": "11001904195198261193", // 生产平台提货单唯一编号
"out_delivery_no": "1001201112", // ERP发货单唯一编号
"status": 6, // 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败
"amount": 1 // 发货数量（从链上查询得到）
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0:成功；405: 无权访问 ；1021: 用户被禁用；2100: 提货单不存在；2600：txid校验失败；2706：发货Txid已存在；2701：未查到对应的商品；2702：发行地址与链上地址不一致 ；2703：提货数量与发货数量不一致；2704：提货生产商与发货商不一致；2705：提货凭证转入地址与客户地址不一致；2300：提货单状态有误；2010：发货通知保存失败 |
| msg| string | 信息 |
| data | object | 返回结果 |
pickup_no | string | 生产平台提货单号 |
| out_delivery_no | string | ERP发货单唯一编号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败 |
| amount | integer | 提货数量(从链上查询得到) |
### 2.4 商城提货单查询
接口名称：商城提货单查询
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：请求参数：pickup\_no：生产平台提货单号、out\_pickup\_no：商城平台提货单号，二选一查询
~~~[api]
post:/api/v2/pickup/findForMall
pickup_no#生产平台提货单号
out_pickup_no#商城平台提货单号
txid#提货上链交易ID
delivered_txid#发货上链交易ID
waybill_no#发货运单号
time_range#查询时间段，格式为：[1552060800000,1552147200000]，单位：毫秒
page_no#查询页
page_size#每页条数
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"pickup_no": "11001904181154785525",
"out_pickup_no": "111119",
"txid": "8866CB397916001E1595995158C40D76",
"tx_type": "astro.token.exchange",
"symbol": "Victor1",
"symbol_child": "Victor1_ex_36688a66-2805-4798-98eb-62c13914b0fb,Victor1_ex_366d1ce7-0fb2-4ddb",
"from_addr": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q",
"to_addr": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A",
"amount": 1,
"status": 6,
"created_at": "2019-04-18T06:49:09.000Z",
"updated_at": "2019-04-18T06:51:04.000Z",
"receipt_list": [
{
"txid": "0C697F48392907A015959A00DB1CC6AF",
"tx_type": "astro.token.deliver",
"symbol": "Victor1",
"symbol_child": "Victor1_ex_36688a66-2805-4798-98eb-62c13914b0fb",
"from_addr": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A",
"to_addr": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q",
"amount": 1,
"serial_no": "01203131231231",
"waybill_no": "01203131231231",
"logistic_no": "01203131231231",
"logistic_name": "顺风",
"created_at": "2019-04-18T06:51:04.000Z",
"updated_at": "2019-04-18T06:51:04.000Z"
}
]
}
]
"pagination": {
"current": 1,
"pageSize": 10,
"total": 3
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600：参数不正确；500：系统内部错误 |
| msg | string | 错误原因 |
| data | array | 返回数据 |
| pickup_no | string | 生产平台提货单号 |
| out_pickup_no | string | 商城提货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败 |
| txid | string | 商城提货单号 |
| tx_type | string | 合约分类: astro.token.offer=增发; astro.token.create=发行; astro.token.exchange=提货; astro.token.deliver=发货; astro.token.change=换货; astro.token.refund=退货 |
| symbol | string | token名称 |
| symbol_child | string | 新token名称 |
| from_addr | string | 用户转出Token A地址,也做为A''接收地址 |
| to_addr | string | 生产商接收Token A地址 |
| amount | integer | 数量 |
| created_at | date | 订单时间 |
| updated_at | date | 修改时间 |
| receipt_list | array(object) | |
| txid | string | 商城提货单号 |
| tx_type | string | 合约分类: astro.token.offer=增发; astro.token.create=发行; astro.token.exchange=提货; astro.token.deliver=发货; astro.token.change=换货; astro.token.refund=退货 |
| symbol | string | token名称 |
| symbol_child | string | 新token名称 |
| from_addr | string | 用户转出Token A地址,也做为A''接收地址 |
| to_addr | string | 生产商接收Token A地址 |
| amount | integer | 数量 |
| serial_no | string | 商品序列号 |
| waybill_no | string | 物流运单号(获取运单号后，改状态为已发货) |
| logistic_no | string | 物流商编号 |
| logistic_name | string | 物流商名称 |
| pagination| object | 分页信息 |
| current | integer | 当前页 |
| total | integer | 总条数 |
### 2.5 ERP 发货单查询
接口名称：ERP发货单查询
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：发货单查询，请求参数：pickup\_no、out_delivery_no，二选一查询
~~~[api]
post:/api/v2/pickup/findForErp
pickup_no#生产平台提货单号
out_delivery_no#ERP平台发货单号
txid#提货上链交易ID
delivered_txid#发货上链交易ID
waybill_no#发货运单号
time_range#查询时间段，格式为：[1552060800000,1552147200000]，单位：毫秒
page_no#查询页
page_size#每页条数
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": {
"status": 0,
"message": "操作成功",
"data": [
{
"pickup_no": "11001904194136563266",
"out_pickup_no": "111119",
"txid": "8866CB397916001E1595995158C40D76",
"tx_type": "astro.token.exchange",
"symbol": "Victor1",
"symbol_child": "Victor1_ex_36688a66-2805-4798-98eb-62c13914b0fb",
"from_addr": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q",
"to_addr": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A",
"amount": 1,
"consignee": "张三",
"cellphone": "13912345678",
"area": "北京/北京市/朝阳区",
"address": "望京SOHO",
"zipcode": "",
"erp_notify_url": "http://localhost:6001/api/v1/mockup/erpreceiver",
"caption": "牙膏",
"specs": {
"image": null,
"颜色": "白"
},
"status": 6,
"created_at": "2019-04-19T03:04:45.000Z",
"updated_at": "2019-04-19T03:17:32.000Z"
}
],
"pagination": {
"current": 1,
"pageSize": 10,
"total": 1
}
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600：参数不正确；500：系统内部错误 |
| msg | string | 错误原因 |
| data | array | 提货数据 |
| pickup_no | string | 生产平台提货单号 |
| out_pickup_no | string | 商城提货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城待发货成功;5=通知商城待发货失败;6=已发货(厂商受理成功);7=已发货通知商城成功;8=已发货通知商城失败 |
| txid | string | 商城提货单号 |
| tx_type | string | 合约分类: astro.token.offer=增发; astro.token.create=发行; astro.token.exchange=提货; astro.token.deliver=发货; astro.token.change=换货; astro.token.refund=退货 |
| symbol | string | token名称 |
| symbol_child | string | 新token名称 |
| from_addr | string | 用户转出Token A地址,也做为A''接收地址 |
| to_addr | string | 生产商接收Token A地址 |
| amount | integer | 数量 |
| area | string | 地区 |
| address | string | 地址 |
| zipcode | string |邮编 |
| mail_notify_url | string | 回调地址 |
| specs | array | 商品规格 |
| caption | string | 商品名称 |
| consignee | string | 消费者姓名 |
| cellphone | string | 电话 |
| created_at | date | 订单时间 |
| updated_at | date | 修改时间 |
| pagination| object | 分页信息 |
| current | integer | 当前页 |
| total | integer | 总条数 |
## 3. 提货进度通知
### 3.1 待发货 | 已发货通知商城平台
接口名称： 待发货|已发货通知商城平台
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：商城平台指定的回调URL 。
*注意：请求参数只有 apiKey 和 ciphertext，ciphertext 包含的参数为解密后结果。*
**生产平台加密过程：**
1. 参数按字典序排列，拼成URL键值对的格式（key1=value1&key2=value2… ），参数的值为空不参与加密，拼接成字符串 stringA，如：
```
待发货stringA
stringA="pickup_no=xxx&out_pickup_no=xxx&status=3&txid=xxx&msg_ts=1552361701472&ts=1552361703000"
已发货stringA
stringA="pickup_no=xxx&out_pickup_no=xxx&status=3&txid=xxx&receipts=[{xxx:xxx}]&msg_ts=1552361701472&ts=1552361703000"
注：receipts为JSON字符串
```
2. 在stringA 最后拼接上 apiSecret 得到 stringSignTemp 字符串, 并对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign 值，如：
```
stringSignTemp = stringA + apiSecret;
sign = MD5(stringSignTemp).toUpperCase();
```
3. 生成 ciphertext：采用AES-256加密方式，加密内容为：params = stringA + "&sign=" + sign，如：
```
apiSecret=65b9477712dc43c8a899dfb69729c600
iv = apiSecret.substr(0,16)
cipher = crypto.createCipheriv('aes-256-cbc', apiSecret, iv);
encrypted = cipher.update(params);
ciphertext = Buffer.concat(\[encrypted,cipher.final()\]).toString('hex')
```
**解密过程：**
1. 根据参数 apiKey 获得对应的 apiSecret;
2. 解密 ciphertext：采用 AES-256 加密方式，加密内容为：data = stringA + "&sign=" + sign， 如：
```
apiSecret = "65b9477712dc43c8a899dfb69729c600"
iv = apiSecret.substr(0,16)
encrypted =newBuffer(ciphertext,'hex')
decipher =crypto.createDecipheriv('aes-256-cbc', apiSecret,iv);
decrypted =decipher.update(encrypted);
params = Buffer.concat([decrypted,decipher.final()]).toString();
```
3. 从 params 字符串中去掉末尾参数，&sign=xxx，获得字符串 stringA；
4. 在 stringA 最后拼接上 apiSecret 得到 stringSignTemp 字符串，并对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 tempSign 值；
5. 比对 tempSign 与 sign 一致，表示数据有效。
**ciphertext密文内容包括：**
```
待发货通知：
pickup_no: Matrix平台提货单唯一编号；
out_pickup_no: 商城平台提货单唯一编号；
txid：发起提货交易ID；
status: 提货单状态；
notify_ts：通知创建时间；
ts：通知发送时间。
```
```
已发货通知：
pickup_no: Matrix平台提货单唯一编号；
out_pickup_no: 商城平台提货单唯一编号；
txid：发起提货交易ID；
status: 提货单状态；
receipts: 发货单票据，JSON字符串数据，包括：
pickup_no：Matrix平台提货单唯一编号；
tx_type：合约类型，astro.token.exchange=提货; astro.token.deliver=发货; astro.token.refund=退货；
origin：原始Token标识；
origin_child：新Token标识；
from_addr：转出地址；
to_addr：转入地址；
amount：转出数量；
waybill_no：发货运单号；
logistic_no：物流商编号；
logistic_name：物流商名称；
serial_no：商品唯一编号
```
~~~[api]
post:商城平台指定的回调URL
*apiKey#apiKey
*ciphertext#密文
<<<
success
{
"code": 0表示成功, 非0表示失败
"msg"
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功，非0：请求错误 |
| msg | string | 信息 |
### 3.2 待发货通知 ERP 平台
接口名称： 待发货通知ERP平台
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：生产商ERP系统指定的回调URL
注意：请求参数只有apiKey和ciphertext，ciphertext包含的参数为解密后结果。
加解密过程参考：「待发货|已发货通知商城平台」
**ciphertext密文内容包括：**
```
pickup_no：Matrix平台提货单唯一编号；
txid：发起提货交易ID；
origin: 原始Token标识；
origin_child: 提货Token标识；
sku_id: Matrix平台商品SKU ID；
caption: Matrix平台商品名称；
spce: Matrix平台商品规格；
consignee: 提货人姓名；
cellphone: 提货人手机号；
area: 提货人所在区域；
address: 提货人地址；
zipcode: 邮编；
notify_ts：通知创建时间戳（1970到生成时的毫秒数）；
ts：通知发送时间戳（1970到生成时的毫秒数）。
```
~~~[api]
post:生产商ERP系统指定的回调URL
*apiKey#apiKey
*ciphertext#密文
<<<
success
{
"code": 0表示成功, 非0表示失败
"msg"
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功，非0：请求错误 |
| msg | string | 信息 |
## 4. 退货接口
### 4.1 获取退货商家回收地址
接口名称: 获取退货商家回收地址
请求数据类型：X-WWW-FORM-URLENCODED
响应类型: JSON
状态：有效
接口描述：获取退货商家回收地址
~~~[api]
post:/api/v2/pickup/fetchAddr
*uid#生产商id
*symbol#token标识
*sku_id#sku_id
<<<
success
{
code：0
msg: '成功'
data:{
address: 'OX0DGGSDFFDG'
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；2102: 退货商品不存在；500: 系统内部错误 |
| msg | string | 错误原因 |
| data | object| 返回数据 |
| address | string | 地址 |
### 4.2 退货申请
接口名称：退货申请
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：客户退货申请
~~~[api]
post:/api/v2/refund/apply
*txid#交易id
*out_refund_no#商城退货单号
*notify_url#处理结果，通知商城
int:amount#提货数量
consignee#收货人
cellphone#收货人手机号
area#地区
address#收货地址
zipcode#邮编
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": {
refund_no:生产平台退货单号,
out_refund_no:商城退货单号,
status: 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城退货成功;5=通知商城退货失败;6=已退货(厂商受理成功);7=已退货通知商城成功;8=已退货通知商城失败,
amount: 退货数量(从链上查询得到)
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0:成功；405: 无权访问 ；1021: 用户被禁用；2801: 退货Txid已存在；2600：txid校验失败；2803：退货数量与链上不一致；2701：未查到对应的商品；2702：发行地址与链上地址不一致 ；2800：退货申请失败 |
| msg | string | 错误原因 |
| data | object | 返回数据 |
| refund_no | string | 生产平台退货单号 |
| out_refund_no | string | 商城退货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城退货成功;5=通知商城退货失败;6=已退货(厂商受理成功);7=已退货通知商城成功;8=已退货通知商城失败 |
| amount | integer | 退货数量(从链上查询得到) |
### 4.3 退货通知
接口名称：退货通知
请求数据类型：APPLICATION/JSON
响应类型：JSON
状态：有效
接口描述：由生产商ERP系统调用，真实退货后，通知生产平台退货单状态变化
<!-- **请求参数**
~~~
{
"pickup_no": "11001904028341836781", // 生产平台退货单唯一编号
"out_delivery_no": "1001201112", // ERP发货单唯一编号
"receipt_list": [ // 生产商发货信息及Token信息
{
"txid": "0C697F48392907A015959A00DB1CC6AF", // 交易ID
"waybill_no": "01203131231231", // 运单号
"serial_no": "01203131231231", // 商品编码，可空
"logistic_no": "01203131231231", // 物流商编号，可空
"logistic_name": "顺风" // 物流商名称，可空
}
]
}
~~~ -->
~~~[api]
post:/api/v2/refund/refunded
txid#交易id
*out_refund_no#商城退货单号
*refund_no#生产平台退货单号
<<<
success
{
"code": 0,
"msg": "退货通知成功",
"data": {
"refund_no": "12001904199498821447",
"out_refunded_no": "3223422342",
"status": 6,
"amount": 1
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0:成功；405: 无权访问 ；1021: 用户被禁用；2902: 退货单不存在；2600：txid校验失败；2804：退货单编号已存在；2701：未查到对应的商品；2702：发行地址与链上地址不一致 ；2806：退货数量与返还数量不一致；2807：生产商ID不一致；2805：转入地址与客户地址不一致；2808：退货单状态有误；2809：退货通知保存失败 |
| msg | string | 信息 |
| data | object | 返回数据 |
| refund_no | string | 生产平台退货单号 |
| out_refund_no | string | 商城退货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城退货成功;5=通知商城退货失败;6=已退货(厂商受理成功);7=已退货通知商城成功;8=已退货通知商城失败 |
| amount | integer | 退货数量(从链上查询得到) |
### 4.4 商城退货单查询
接口名称：退货单商城查询
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：商城查询退货单
~~~[api]
post:/api/v2/refund/findForMall
refund_no#生产平台退货单号
out_refund_no#商城退货单号
txid#交易id
refund_txid#退货交易id
time_range#查询时间段，格式为：[1552060800000,1552147200000]，单位：毫秒
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"refund_no": "119030814581566011699905",
"out_refund_no": "1001007",
"txid": "8866CB397916001E1595995158C40D76",
"tx_type": "astro.token.exchange",
"symbol": "Victor1",
"symbol_child": "Victor1_ex_36688a66-2805-4798-98eb-62c13914b0fb"
"from_addr": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q",
"to_addr": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A",
"amount": 1,
"notify_url": "http://localhost/pickup/callback",
"status": "待退货",
"created_at": "2019-03-08T13:00:36.000Z",
"updated_at": "2019-03-14T09:23:08.000Z"
}
],
"pagination": {
"current": 1,
"pageSize": 10,
"total": 3
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600：参数不正确；500：系统内部错误 |
| msg | string | 错误原因 |
| data | array | 返回数据 |
| refund_no | string | 生产平台退货单号 |
| out_refund_no | string | 商城退货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城退货成功;5=通知商城退货失败;6=已退货(厂商受理成功);7=已退货通知商城成功;8=已退货通知商城失败 |
| txid | string | 商城退货单号 |
| tx_type | string | 合约分类: astro.token.offer=增发; astro.token.create=发行; astro.token.exchange=提货; astro.token.deliver=发货; astro.token.change=换货; astro.token.refund=退货 |
| symbol | string | token名称 |
| symbol_child | string | 新token名称 |
| from_addr | string | 用户转出Token A地址,也做为A''接收地址 |
| to_addr | string | 生产商接收Token A地址 |
| amount | integer | 数量 |
| notify_url | string | 回调地址 |
| created_at | date | 订单时间 |
| updated_at | date | 修改时间 |
| pagination| object | 分页信息 |
| current | integer | 当前页 |
| total | integer | 总条数 |
### 4.5 ERP 退货单查询
接口名称：退货单ERP查询
请求数据类型：X-WWW-FORM-URLENCODED
响应类型：JSON
状态：有效
接口描述：退货单ERP查询
~~~[api]
post:/api/v2/refound/findForErp
refund_no#生产平台退货单号
out_refunded_no#ERP退货单号
txid#退货申请交易id
refunded_txid#退货id
time_range#查询时间段，格式为：[1552060800000,1552147200000]，单位：毫秒
<<<
success
{
"code": 0,
"msg": "操作成功",
"data": [
{
"refund_no": "11001904181154785525",
"out_refunded_no": "111119",
"txid": "8866CB397916001E1595995158C40D76",
"tx_type": "astro.token.exchange",
"symbol": "Victor1",
"symbol_child": "Victor1_ex_36688a66-2805-4798-98eb-62c13914b0fb,Victor1_ex_366d1ce7-0fb2-4ddb",
"from_addr": "AfmAE1K-T8V-y4ObshuwV2faNMOdNMYW0Q",
"to_addr": "ARJtq6Q46oTnxDwvVqMgDtZeNxs7Ybt81A",
"amount": 1,
"status": 6,
"notify_url": "http://localhost/pickup/callback",
"created_at": "2019-04-18T06:49:09.000Z",
"updated_at": "2019-04-18T06:51:04.000Z",
"consignee": "张三",
"cellphone": "13912345678",
"area": "北京/北京市/朝阳区",
"address": "望京SOHO",
"zipcode": "",
"caption": "牙膏",
"specs": {
"image": null,
"颜色": "白"
},
}
]
"pagination": {
"current": 1,
"pageSize": 10,
"total": 3
}
}
<<<
error
~~~
**返回值**
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| code | integer | 0：成功；600：参数不正确；500：系统内部错误 |
| msg | string | 错误原因 |
| data | array | 返回数据 |
| fefund_no | string | 生产平台退货单号 |
| out_refunded_no | string | ERP退货单号 |
| status | integer | 状态：1=待通知厂商;2=通知厂商成功;3=通知厂商失败;4=通知商城退货成功;5=通知商城退货失败;6=已退货(厂商受理成功);7=已退货通知商城成功;8=已退货通知商城失败 |
| txid | string | 商城提货单号 |
| tx_type | string | 合约分类: astro.token.offer=增发; astro.token.create=发行; astro.token.exchange=提货; astro.token.deliver=发货; astro.token.change=换货; astro.token.refund=退货 |
| symbol | string | token名称 |
| symbol_child | string | 新token名称 |
| from_addr | string | 用户转出Token A地址,也做为A''接收地址 |
| to_addr | string | 生产商接收Token A地址 |
| amount | integer | 数量 |
| area | string | 地区 |
| address | string | 地址 |
| zipcode | string |邮编 |
| notify_url | string | 回调地址 |
| specs | array | 商品规格 |
| caption | string | 商品名称 |
| consignee | string | 消费者姓名 |
| cellphone | string | 电话 |
| created_at | date | 订单时间 |
| updated_at | date | 修改时间 |
| pagination| object | 分页信息 |
| current | integer | 当前页 |
| total | integer | 总条数 |
