# 概述与接入指南

## 简介

企得宝ERP开放API，供外部系统对接企得宝ERP系统使用。所有API基于HTTP POST协议，采用JSON格式进行数据交互。

---

## 请求地址

| 环境 | URL |
|------|-----|
| **正式环境** | `https://api.7debao.com/router/api` |
| **测试环境** | `https://apitest.7debao.com/router/api` |

- 请求方式：**POST**
- Content-Type：**application/json**

---

## 签名算法

为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。

支持的签名算法为：**MD5（sign_method=md5）**

### 签名步骤

1. 将所有**公共参数**按照参数名的首字母先后顺序排列
2. 把排序后的结果按照参数名+参数值的方式拼接
3. 拼装好的字符串首尾拼接 `client_secret` 进行 md5（小写32位）
4. secret 的值是开放平台后台分配的 `client_secret`

### 签名示例

假设 `client_secret` 为 `secret`，公共参数如下：

```
client_id=tfs20000
format=json
method=foonsu.erp.warehouse.list
partner_id=foonsu-sdk-java-httpdns-20191113
timestamp=1599095989
v=1.0
```

排序后拼装（首尾加secret）：

```
secretclient_idtfs20000formatjsonmethodfoonsu.erp.warehouse.listpartner_idfoonsu-sdk-java-httpdns-20191113timestamp1599095989v1.0secret
```

对该字符串进行MD5加密（小写32位）得到签名。

### URL拼接示例

```
https://api.7debao.com/router/api?timestamp=1624870813&client_id=tfs20000&format=json&method=foonsu.erp.warehouse.list&partner_id=foonsu-sdk-java-httpdns-20191113&v=1.0&sign=43a35d0d3dc9a37e8095082101dda33
```

请求时，URL拼接公共参数，body传入业务参数（JSON格式）。

---

## 公共请求参数

所有API调用都必须携带以下公共参数：

| 参数名 | 必选 | 类型 | 说明 |
|--------|------|------|------|
| client_id | 是 | String | 分配给应用的 clientId |
| method | 是 | String | 接口名称 |
| partner_id | 是 | String | 默认 `foonsu-sdk-java-httpdns-20191113` |
| timestamp | 是 | String | 时间戳 |
| v | 是 | String | 版本，默认 `1.0` |
| format | 是 | String | 默认 `json` |
| sign | 是 | String | 签名（由签名算法生成） |

---

## 基本返回参数

所有API统一返回以下格式：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| errorCode | String | 错误编码 |
| msg | String | 提示信息 |
| data | Object | 成功时返回数据，失败为 null |
| date | Date | 响应时间 |
| version | Integer | 版本信息 |
| success | Boolean | 成功为 true，失败为 false |

### 返回示例（成功）

```json
{
    "errorCode": null,
    "msg": "操作成功",
    "data": { ... },
    "date": null,
    "version": null,
    "success": true
}
```

### 返回示例（失败）

```json
{
    "errorCode": "19140001",
    "msg": "必填参数未填",
    "data": null,
    "date": null,
    "version": null,
    "success": false
}
```

---

## 接口列表总览

| 分类 | API数量 | 文档 |
|------|---------|------|
| 基础资料 | 9 | [01-基础资料.md](./01-基础资料.md) |
| 商品管理 | 6 | [02-商品管理.md](./02-商品管理.md) |
| 平台商品管理（个性） | 19 | [03-平台商品管理(个性).md](./03-平台商品管理(个性).md) |
| 订单管理 | 16 | [04-订单管理.md](./04-订单管理.md) |
| 采购管理 | 5 | [05-采购管理.md](./05-采购管理.md) |
| 调拨管理 | 2 | [06-调拨管理.md](./06-调拨管理.md) |
| 其他出入库管理 | 3 | [07-其他出入库管理.md](./07-其他出入库管理.md) |
| 盘点管理 | 2 | [08-盘点管理.md](./08-盘点管理.md) |
| 库存管理 | 2 | [09-库存管理.md](./09-库存管理.md) |
| 消息推送 | 8 | [10-消息推送.md](./10-消息推送.md) |
| 路由管理 | 1 | [11-路由管理.md](./11-路由管理.md) |
| **合计** | **73** | - |