# shopkeeper-opendoc

**Repository Path**: isboy2021/juhebei-opendoc

## Basic Information

- **Project Name**: shopkeeper-opendoc
- **Description**: 聚合呗开放平台接口文档 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2023-03-13
- **Last Updated**: 2023-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# shopkeeper-opendoc

## 介绍

聚合呗开放平台接口相关文档 

- [配送OpenApi doc](https://gitee.com/jhbopenapi/juhebei-opendoc/tree/master/delivery)
- [打印OpenApi doc](https://gitee.com/jhbopenapi/juhebei-opendoc/tree/master/printer)
- [云音箱OpenApi doc](https://gitee.com/jhbopenapi/juhebei-opendoc/tree/master/spoker)

## 快速开始

<img src="https://file-static.juhesaas.com/image/%E5%9B%BE%E7%89%87.png" title="" alt="图片.png" data-align="center">

1. 注册聚合呗开放平台账号。**请用微信扫描上面的企微二维码联系开放平台小助手**，向平台小助手交相关信息后，相关凭据信息`appid`与`appsecret`会以短信的形式下发到注册手机上（48小时内会有人工审核并下发）；

2. 阅读[接口调用协议约定](#接口调用协议约定)，熟悉签名规则，在http header准备好相关通用参数，也可以参考签名样例：[JAVA](https://gitee.com/jinwu/juhebei-opendoc/blob/master/demo/Java%E7%AD%BE%E5%90%8D%E4%B8%8E%E8%AF%B7%E6%B1%82Demo.md) [PHP](https://gitee.com/jinwu/juhebei-opendoc/blob/master/demo/PHP%E7%AD%BE%E5%90%8D%E4%B8%8E%E8%AF%B7%E6%B1%82Demo.md)；

3. 完成上面的步骤后，就可以按需对接其它接口了；

**_PS: __对JSON不熟悉的同学，建议先使用Postman, fiddler之类的http请求工具先调通，帮助理清传参规则_**

---

## 接口调用协议约定

1. 协议：`https`;

2. 所有请求方法都用 `POST`;

3. 请求与响应内容都是json;

4. **Http header**通用固定传参：
   
   | Http Header参数 | 类型     | 备注                                                                             |
   | ------------- | ------ | ------------------------------------------------------------------------------ |
   | Content-Type  | string | 固定为 `application/json;charset=UTF-8`                                           |
   | appid         | string | 应用ID                                                                           |
   | uid           | string | 请求唯一ID，只能用来请求一次，不可以重复（例如: Java可以使用UUID，其它没有UUID实现的语言，可以采用时间戳+随机串的方式生成，保证不重复限可） |
   | stime         | long   | timestamp，请求时间戳，精确秒(UTC+8)                                                     |
   | sign          | string | 签名 md5(uid+appid+stime+appsecrect+请求Json内容)                                    |

**示例**：

```javascript
 POST https://printer.juhesaas.com/openapi/addPrinter
 Content-Type: application/json
 uid: {uid}
 appid: {appid}
 stime: 1617332013      # timestamp（秒）
 sign: {sign}           # 签名算法 md5(uid+appid+stime+appsecrect+请求Json内容)

 {你的http请求json body在这里}
```

5. 响应标准结构，包括平台响应外部请求与开发者应用对平台异步通知打印结果的响应

```json
  {
    "code": 0,            # 响应码，成功时响应 0；异常时，API将返回相应错误码
    "message":"ok",  # 响应消息，成功时响应 "ok"；异常时返回错误消息
    "data":               # 可选，对于列表返回空[]，对于空对象不返回属性
  }
```

---

## 异步消息回调

#### 回调业务类型：

| 业务类型 | 备注         |
| ---- | ---------- |
| 1    | 打印机状态变化消息  |
| 4    | 配送单状态变更事件  |
| 5    | 打票请求状态变化消息 |

响应示例：

```json
{
    "type": 4, // 见附录回调业务类型
    "rtime": 1662459209, // 回调时间
    "data": "{\"shopId\":6308559984,\"salesOrderNo\":\"A00062\",\"status\":60,\"deliverymanName\":\"甜甜田超辉\",\"deliverymanMobile\":\"18521736087\",\"distance\":1,\"deliveryAmount\":100,\"couponAmount\":0,\"tipsAmount\":300,\"insuranceAmount\":0,\"payAmount\":100,\"deductAmount\":0,\"timestamp\":1637720013}"
}
```