API接口说明-CRM帮助文档(S1)帮助文档

# ERP系统API接口使用及说明文档

## 1. 概述

本文档详细说明了ERP系统的API接口规范和使用方法。所有API接口都遵循统一的设计规范，继承自[ErpApiBase](file:///E:/WebSite/OpenSource/FLY-BASE/base/app/erp/controller/api/ErpApiBase.php#L20-L97)基类，该基类继承自[ApiBase](file:///E:/WebSite/OpenSource/FLY-BASE/base/app/common/controller/ApiBase.php#L17-L62)。API接口采用统一的权限验证机制和数据返回格式。

## 2. 接口规范

### 2.1 认证机制

所有API接口都需要通过用户Token进行认证。Token通过参数中的`access_token`传递。

### 2.2 权限验证

接口会根据用户Token自动验证访问权限，确保用户只能访问其被授权的资源。

### 2.3 数据格式

接口统一使用JSON格式进行数据传输，请求和响应都采用UTF-8编码。

### 2.4 响应格式

所有接口返回的数据格式统一为：
```json
{
  "code": 1,        // 状态码，1表示成功，0表示失败
  "msg": "成功",     // 提示信息
  "data": {}        // 返回数据
}
```

### 2.5 基类说明

#### [ErpApiBase](file:///E:/WebSite/OpenSource/FLY-BASE/base/app/erp/controller/api/ErpApiBase.php#L20-L97)

所有ERP API控制器的基类，提供以下功能：
- 用户Token验证
- 权限检查
- 统一的返回格式处理

#### 请求参数

所有API接口都接收统一的参数格式，主要参数包括：
- `access_token`: 用户认证Token
- `matchObj`: 查询条件对象
- `sortObj`: 排序条件对象
- `req`: 请求数据对象

## 3. 接口列表

### 3.1 客户管理 (Customer Management)

控制器路径: `/erp/api.CstCustomer/`

#### 方法列表

##### 1. search_json
搜索客户列表

**请求方式**: GET/POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "keywords": "搜索关键词"
}
```

**响应数据**:
```json
{
  "code": 1,
  "msg": "成功",
  "data": [
    {
      "id": 1,
      "name": "客户名称",
      "linkman": "联系人",
      "mobile": "联系电话"
    }
  ]
}
```

**使用示例**:
```javascript
// jQuery示例
$.ajax({
  url: '/erp/api.CstCustomer/search_json',
  type: 'POST',
  data: {
    access_token: 'your_token',
    keywords: '客户关键词'
  },
  success: function(res) {
    console.log(res);
  }
});
```

##### 2. show_json
显示客户列表

**请求方式**: GET/POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "matchObj": {
    "字段名": "匹配值"
  },
  "sortObj": {
    "field": "排序字段",
    "order": "排序方式(asc/desc)"
  }
}
```

**响应数据**:
```json
{
  "code": 1,
  "msg": "成功",
  "data": [
    {
      "id": 1,
      "name": "客户名称",
      "linkman": "联系人",
      "mobile": "联系电话"
    }
  ]
}
```

##### 3. show_public
显示公海客户

**请求方式**: GET/POST

##### 4. detail
获取客户详情

**请求方式**: GET/POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "客户ID"
}
```

##### 5. add
添加客户

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "req": {
    "name": "客户名称",
    "linkman": "联系人",
    "mobile": "联系电话"
    // 其他客户字段
  }
}
```

##### 6. edit
编辑客户

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "req": {
    "id": "客户ID",
    "name": "客户名称",
    "linkman": "联系人",
    "mobile": "联系电话"
    // 其他客户字段
  }
}
```

##### 7. del
删除客户

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "客户ID"
}
```

##### 8. gotopublic
客户转为公海

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "客户ID"
}
```

##### 9. gotopersonal
客户转为个人

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "客户ID"
}
```

### 3.2 供应商管理 (Supplier Management)

控制器路径: `/erp/api.SupSupplier/`

#### 方法列表

##### 1. show_json
显示供应商列表

**请求方式**: GET/POST

##### 2. detail
获取供应商详情

**请求方式**: GET/POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "供应商ID"
}
```

##### 3. add
添加供应商

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "req": {
    "name": "供应商名称",
    "linkman": "联系人",
    "mobile": "联系电话"
    // 其他供应商字段
  }
}
```

##### 4. edit
编辑供应商

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "req": {
    "id": "供应商ID",
    "name": "供应商名称",
    "linkman": "联系人",
    "mobile": "联系电话"
    // 其他供应商字段
  }
}
```

##### 5. del
删除供应商

**请求方式**: POST

**请求参数**:
```json
{
  "access_token": "用户访问令牌",
  "id": "供应商ID"
}
```

### 3.3 商品管理 (Goods Management)

#### 控制器: Goods

控制器路径: `/erp/api.Goods/`

##### 方法列表

1. `show_json`: 显示商品列表
2. `add`: 添加商品
3. `edit`: 编辑商品
4. `del`: 删除商品

#### 控制器: GoodsCategory

控制器路径: `/erp/api.GoodsCategory/`

##### 方法列表

1. `show_json`: 显示商品分类列表

#### 控制器: GoodsBrand

控制器路径: `/erp/api.GoodsBrand/`

##### 方法列表

1. `show_json`: 显示商品品牌列表
2. `add`: 添加商品品牌
3. `edit`: 编辑商品品牌
4. `del`: 删除商品品牌
5. `set_visible`: 设置可见性
6. `set_sort`: 设置排序

#### 控制器: GoodsSku

控制器路径: `/erp/api.GoodsSku/`

##### 方法列表

1. `show_json`: 显示商品SKU列表
2. `add`: 添加商品SKU
3. `edit`: 编辑商品SKU
4. `del`: 删除商品SKU

#### 控制器: GoodsSpec

控制器路径: `/erp/api.GoodsSpec/`

##### 方法列表

1. `show_json`: 显示商品规格列表
2. `add`: 添加商品规格
3. `edit`: 编辑商品规格
4. `del`: 删除商品规格

#### 控制器: GoodsSpecValue

控制器路径: `/erp/api.GoodsSpecValue/`

##### 方法列表

1. `show_json`: 显示商品规格值列表
2. `add`: 添加商品规格值
3. `edit`: 编辑商品规格值
4. `del`: 删除商品规格值

### 3.4 财务管理 (Financial Management)

#### 控制器: FinBankAccount

控制器路径: `/erp/api.FinBankAccount/`

##### 方法列表

1. `show_json`: 显示银行账户列表

#### 控制器: FinPayPlan

控制器路径: `/erp/api.FinPayPlan/`

##### 方法列表

1. `show_json`: 显示付款计划列表
2. `add`: 添加付款计划
3. `edit`: 编辑付款计划
4. `del`: 删除付款计划
5. `sure`: 确认付款

#### 控制器: FinRecePlan

控制器路径: `/erp/api.FinRecePlan/`

##### 方法列表

1. `show_json`: 显示收款计划列表
2. `add`: 添加收款计划
3. `edit`: 编辑收款计划
4. `del`: 删除收款计划
5. `sure`: 确认收款

#### 控制器: FinPayRecord

控制器路径: `/erp/api.FinPayRecord/`

##### 方法列表

1. `show_json`: 显示付款记录列表
2. `add`: 添加付款记录
3. `edit`: 编辑付款记录
4. `del`: 删除付款记录

#### 控制器: FinReceRecord

控制器路径: `/erp/api.FinReceRecord/`

##### 方法列表

1. `show_json`: 显示收款记录列表
2. `add`: 添加收款记录
3. `edit`: 编辑收款记录
4. `del`: 删除收款记录

#### 控制器: FinInvoicePay

控制器路径: `/erp/api.FinInvoicePay/`

##### 方法列表

1. `show_json`: 显示付款发票列表
2. `add`: 添加付款发票
3. `edit`: 编辑付款发票
4. `del`: 删除付款发票

#### 控制器: FinInvoiceRece

控制器路径: `/erp/api.FinInvoiceRece/`

##### 方法列表

1. `show_json`: 显示收款发票列表
2. `add`: 添加收款发票
3. `edit`: 编辑收款发票
4. `del`: 删除收款发票

#### 控制器: FinExpensesRecord

控制器路径: `/erp/api.FinExpensesRecord/`

##### 方法列表

1. `show_json`: 显示费用支出记录列表
2. `add`: 添加费用支出记录
3. `edit`: 编辑费用支出记录
4. `del`: 删除费用支出记录

#### 控制器: FinIncomeRecord

控制器路径: `/erp/api.FinIncomeRecord/`

##### 方法列表

1. `show_json`: 显示费用收入记录列表
2. `add`: 添加费用收入记录
3. `edit`: 编辑费用收入记录
4. `del`: 删除费用收入记录

#### 控制器: FinExpensesType

控制器路径: `/erp/api.FinExpensesType/`

##### 方法列表

1. `show_json`: 显示费用支出类型列表

#### 控制器: FinIncomeType

控制器路径: `/erp/api.FinIncomeType/`

##### 方法列表

1. `show_json`: 显示费用收入类型列表

#### 控制器: FinReimburse

控制器路径: `/erp/api.FinReimburse/`

##### 方法列表

1. `show_json`: 显示报销单列表
2. `add`: 添加报销单
3. `edit`: 编辑报销单
4. `del`: 删除报销单
5. `audit`: 审核报销单
6. `detail`: 获取报销单详情

### 3.5 库存管理 (Stock Management)

#### 控制器: StockStore

控制器路径: `/erp/api.StockStore/`

##### 方法列表

1. `show_json`: 显示仓库列表
2. `add`: 添加仓库
3. `edit`: 编辑仓库
4. `del`: 删除仓库

#### 控制器: StockInto

控制器路径: `/erp/api.StockInto/`

##### 方法列表

1. `show_json`: 显示入库单列表
2. `add`: 添加入库单
3. `edit`: 编辑入库单
4. `del`: 删除入库单
5. `sure`: 确认入库
6. `cancel`: 取消入库
7. `detail`: 获取入库单详情
8. `audit_send`: 提交审批
9. `audit_cancel`: 取消审核

#### 控制器: StockOut

控制器路径: `/erp/api.StockOut/`

##### 方法列表

1. `show_json`: 显示出库单列表
2. `add`: 添加出库单
3. `edit`: 编辑出库单
4. `del`: 删除出库单
5. `sure`: 确认出库
6. `cancel`: 取消出库
7. `detail`: 获取出库单详情
8. `audit_send`: 提交审批
9. `audit_cancel`: 取消审核

#### 控制器: StockCheck

控制器路径: `/erp/api.StockCheck/`

##### 方法列表

1. `show_json`: 显示盘点单列表
2. `add`: 添加盘点单
3. `edit`: 编辑盘点单
4. `del`: 删除盘点单
5. `sure`: 确认盘点
6. `cancel`: 取消盘点
7. `detail`: 获取盘点单详情

#### 控制器: StockChange

控制器路径: `/erp/api.StockChange/`

##### 方法列表

1. `show_json`: 显示变更单列表
2. `add`: 添加变更单
3. `edit`: 编辑变更单
4. `del`: 删除变更单
5. `sure`: 确认变更
6. `cancel`: 取消变更
7. `detail`: 获取变更单详情

#### 控制器: StockAssemble

控制器路径: `/erp/api.StockAssemble/`

##### 方法列表

1. `show_json`: 显示组装单列表
2. `add`: 添加组装单
3. `edit`: 编辑组装单
4. `del`: 删除组装单
5. `sure`: 确认组装
6. `cancel`: 取消组装
7. `detail`: 获取组装单详情

#### 控制器: StockInitial

控制器路径: `/erp/api.StockInitial/`

##### 方法列表

1. `show_json`: 显示初始化单列表
2. `add`: 添加初始化单
3. `edit`: 编辑初始化单
4. `del`: 删除初始化单
5. `sure`: 确认初始化
6. `cancel`: 取消初始化
7. `detail`: 获取初始化单详情

#### 控制器: StockGoodsSku

控制器路径: `/erp/api.StockGoodsSku/`

##### 方法列表

1. `show_json`: 显示商品SKU库存列表
2. `add`: 添加商品SKU库存
3. `edit`: 编辑商品SKU库存
4. `del`: 删除商品SKU库存

### 3.6 销售管理 (Sales Management)

#### 控制器: SalOrder

控制器路径: `/erp/api.SalOrder/`

##### 方法列表

1. `show_json`: 显示销售订单列表
2. `add`: 添加销售订单
3. `edit`: 编辑销售订单
4. `del`: 删除销售订单

#### 控制器: SalContract

控制器路径: `/erp/api.SalContract/`

##### 方法列表

1. `show_json`: 显示销售合同列表
2. `add`: 添加销售合同
3. `edit`: 编辑销售合同
4. `del`: 删除销售合同

#### 控制器: SalOrderList

控制器路径: `/erp/api.SalOrderList/`

##### 方法列表

1. `show_json`: 显示销售订单明细列表
2. `add`: 添加销售订单明细
3. `edit`: 编辑销售订单明细
4. `del`: 删除销售订单明细

#### 控制器: SalContractList

控制器路径: `/erp/api.SalContractList/`

##### 方法列表

1. `show_json`: 显示销售合同明细列表
2. `add`: 添加销售合同明细
3. `edit`: 编辑销售合同明细
4. `del`: 删除销售合同明细

### 3.7 采购管理 (Purchase Management)

#### 控制器: PosContract

控制器路径: `/erp/api.PosContract/`

##### 方法列表

1. `show_json`: 显示采购合同列表
2. `add`: 添加采购合同
3. `edit`: 编辑采购合同
4. `del`: 删除采购合同

#### 控制器: PosContractList

控制器路径: `/erp/api.PosContractList/`

##### 方法列表

1. `show_json`: 显示采购合同明细列表
2. `add`: 添加采购合同明细
3. `edit`: 编辑采购合同明细
4. `del`: 删除采购合同明细

### 3.8 系统管理 (System Management)

#### 控制器: SysAuth

控制器路径: `/erp/api.SysAuth/`

##### 方法列表

1. `show_json`: 显示权限列表
2. `detail`: 获取权限详情

#### 控制器: CstDict

控制器路径: `/erp/api.CstDict/`

##### 方法列表

1. `show_json`: 显示字典列表

#### 控制器: CstDictType

控制器路径: `/erp/api.CstDictType/`

##### 方法列表

1. `show_json`: 显示字典类型列表
2. `add`: 添加字典类型
3. `edit`: 编辑字典类型
4. `del`: 删除字典类型
5. `set_visible`: 设置可见性
6. `set_sort`: 设置排序

#### 控制器: CstFieldExt

控制器路径: `/erp/api.CstFieldExt/`

##### 方法列表

1. `show_json`: 显示扩展字段列表
2. `add`: 添加扩展字段
3. `edit`: 编辑扩展字段
4. `del`: 删除扩展字段

### 3.9 市场营销 (Marketing Management)

#### 控制器: CstChance

控制器路径: `/erp/api.CstChance/`

##### 方法列表

1. `show_json`: 显示商机列表
2. `add`: 添加商机
3. `edit`: 编辑商机
4. `del`: 删除商机

#### 控制器: CstQuoted

控制器路径: `/erp/api.CstQuoted/`

##### 方法列表

1. `show_json`: 显示报价单列表
2. `add`: 添加报价单
3. `edit`: 编辑报价单
4. `del`: 删除报价单

#### 控制器: CstQuotedList

控制器路径: `/erp/api.CstQuotedList/`

##### 方法列表

1. `show_json`: 显示报价单明细列表
2. `add`: 添加报价单明细
3. `edit`: 编辑报价单明细
4. `del`: 删除报价单明细
5. `set_visible`: 设置可见性
6. `set_sort`: 设置排序

#### 控制器: MkKpi

控制器路径: `/erp/api.MkKpi/`

##### 方法列表

1. `show_json`: 显示市场KPI列表
2. `add`: 添加市场KPI
3. `edit`: 编辑市场KPI
4. `del`: 删除市场KPI

### 3.10 联系人管理 (Contact Management)

#### 控制器: CstLinkman

控制器路径: `/erp/api.CstLinkman/`

##### 方法列表

1. `show_json`: 显示客户联系人列表
2. `add`: 添加客户联系人
3. `edit`: 编辑客户联系人
4. `del`: 删除客户联系人

#### 控制器: SupLinkman

控制器路径: `/erp/api.SupLinkman/`

##### 方法列表

1. `show_json`: 显示供应商联系人列表
2. `add`: 添加供应商联系人
3. `edit`: 编辑供应商联系人
4. `del`: 删除供应商联系人

### 3.11 其他功能

#### 控制器: Workbench

控制器路径: `/erp/api.Workbench/`

##### 方法列表

1. `show_json`: 显示工作台数据

#### 控制器: CstTrace

控制器路径: `/erp/api.CstTrace/`

##### 方法列表

1. `show_json`: 显示客户跟进列表
2. `add`: 添加客户跟进
3. `edit`: 编辑客户跟进
4. `del`: 删除客户跟进

#### 控制器: CstWebsite

控制器路径: `/erp/api.CstWebsite/`

##### 方法列表

1. `show_json`: 显示客户网站列表
2. `add`: 添加客户网站
3. `edit`: 编辑客户网站
4. `del`: 删除客户网站

#### 控制器: CstConfRecover

控制器路径: `/erp/api.CstConfRecover/`

##### 方法列表

1. `show_json`: 显示客户回收列表
2. `add`: 添加客户回收
3. `edit`: 编辑客户回收
4. `del`: 删除客户回收

#### 控制器: CstConfRecoverCustomer

控制器路径: `/erp/api.CstConfRecoverCustomer/`

##### 方法列表

1. `show_json`: 显示客户回收客户列表
2. `add`: 添加客户回收客户
3. `edit`: 编辑客户回收客户
4. `del`: 删除客户回收客户

#### 控制器: CstConfRecoverUser

控制器路径: `/erp/api.CstConfRecoverUser/`

##### 方法列表

1. `show_json`: 显示客户回收用户列表
2. `add`: 添加客户回收用户
3. `edit`: 编辑客户回收用户
4. `del`: 删除客户回收用户

## 4. 通用使用示例

### 4.1 获取数据列表示例

```javascript
// 使用jQuery获取客户列表
$.ajax({
  url: '/erp/api.CstCustomer/show_json',
  type: 'POST',
  dataType: 'json',
  data: {
    access_token: 'your_access_token',
    matchObj: {
      name: '客户名称'
    },
    sortObj: {
      field: 'id',
      order: 'desc'
    }
  },
  success: function(response) {
    if (response.code === 1) {
      console.log('获取客户列表成功:', response.data);
    } else {
      console.error('获取客户列表失败:', response.msg);
    }
  },
  error: function(xhr, status, error) {
    console.error('请求出错:', error);
  }
});
```

### 4.2 添加数据示例

```javascript
// 使用jQuery添加客户
$.ajax({
  url: '/erp/api.CstCustomer/add',
  type: 'POST',
  dataType: 'json',
  data: {
    access_token: 'your_access_token',
    req: {
      name: '新客户',
      linkman: '联系人',
      mobile: '13800138000',
      address: '客户地址'
    }
  },
  success: function(response) {
    if (response.code === 1) {
      console.log('添加客户成功:', response.data);
    } else {
      console.error('添加客户失败:', response.msg);
    }
  },
  error: function(xhr, status, error) {
    console.error('请求出错:', error);
  }
});
```

### 4.3 编辑数据示例

```javascript
// 使用jQuery编辑客户
$.ajax({
  url: '/erp/api.CstCustomer/edit',
  type: 'POST',
  dataType: 'json',
  data: {
    access_token: 'your_access_token',
    req: {
      id: 1,
      name: '更新后的客户名称',
      linkman: '新联系人',
      mobile: '13900139000'
    }
  },
  success: function(response) {
    if (response.code === 1) {
      console.log('编辑客户成功:', response.data);
    } else {
      console.error('编辑客户失败:', response.msg);
    }
  },
  error: function(xhr, status, error) {
    console.error('请求出错:', error);
  }
});
```

### 4.4 删除数据示例

```javascript
// 使用jQuery删除客户
$.ajax({
  url: '/erp/api.CstCustomer/del',
  type: 'POST',
  dataType: 'json',
  data: {
    access_token: 'your_access_token',
    id: 1
  },
  success: function(response) {
    if (response.code === 1) {
      console.log('删除客户成功');
    } else {
      console.error('删除客户失败:', response.msg);
    }
  },
  error: function(xhr, status, error) {
    console.error('请求出错:', error);
  }
});
```

## 5. 错误处理

所有接口在发生错误时都会返回统一的错误格式：
```json
{
  "code": 0,
  "msg": "错误信息",
  "data": {}
}
```

常见的错误码：
- 0: 操作失败
- 1: 操作成功
- 其他特定业务错误码根据具体接口定义

## 6. 注意事项

1. 所有接口都需要通过`access_token`进行身份验证
2. 参数传递时需要注意数据类型匹配
3. 删除操作需要谨慎，部分删除操作可能是物理删除
4. 涉及金额的字段需要特别注意精度问题
5. 分页查询时注意页码和每页数量的合理设置
6. 某些操作可能需要特定权限，请确保用户具有相应权限