# 用友BIP集成使用说明 ## 功能概述 本模块实现了与用友BIP云平台的数据集成,主要功能包括: 1. **销售订单同步**:将CRM系统中的销售订单同步到用友BIP 2. **销售订单发货同步**:将销售订单的发货信息同步到用友BIP ## 安装配置 ### 1. 数据库配置 执行SQL文件创建相关表: ```bash # 创建同步记录表 mysql -u用户名 -p数据库名 < application/database/yonyou_bip_sync_log.sql # 创建基础数据表 mysql -u用户名 -p数据库名 < application/database/yonyou_bip_base_data.sql ``` ### 2. 环境变量配置 在项目根目录的 `.env` 文件中添加以下配置: ```env # 用友BIP配置 YONYOU_BIP_BASE_URL=https://api.yonyoucloud.com YONYOU_BIP_APP_KEY=你的应用Key YONYOU_BIP_APP_SECRET=你的应用Secret YONYOU_BIP_TENANT_ID=你的租户ID YONYOU_BIP_ENABLED=true ``` ### 3. 配置文件 配置文件位于 `application/extra/yonyou_bip.php`,可以根据实际情况修改API端点。 ### 4. 同步基础数据 在创建销售订单之前,需要先从用友BIP同步基础数据: **同步所有基础数据:** ```bash POST /antis/yonyou_bip/sync_all_base_data ``` **同步指定类型的基础数据:** ```bash POST /antis/yonyou_bip/sync_base_data { "type": "organization" // organization-销售组织, transaction_type-交易类型, department-销售部门, person-销售业务员, customer-客户 } ``` **设置本地数据与用友BIP数据的映射关系:** ```bash POST /antis/yonyou_bip/set_data_mapping { "type": "department", "local_id": 1, // 本地部门ID "bip_code": "DEPT001" // 用友BIP部门编码 } ``` ## API接口说明 ### 基础数据接口 #### 1. 获取销售组织列表 **接口地址:** `GET /antis/yonyou_bip/get_sales_organizations` **返回示例:** ```json { "code": 1, "msg": "获取成功", "data": [ { "id": 1, "data_type": "organization", "bip_code": "ORG001", "bip_name": "销售组织1", "local_id": null } ] } ``` #### 2. 获取交易类型列表 **接口地址:** `GET /antis/yonyou_bip/get_transaction_types` #### 3. 获取销售部门列表 **接口地址:** `GET /antis/yonyou_bip/get_sales_departments` #### 4. 获取销售业务员列表 **接口地址:** `GET /antis/yonyou_bip/get_sales_persons` #### 5. 同步基础数据 **接口地址:** `POST /antis/yonyou_bip/sync_base_data` **请求参数:** ```json { "type": "organization" // organization, transaction_type, department, person, customer } ``` #### 6. 批量同步所有基础数据 **接口地址:** `POST /antis/yonyou_bip/sync_all_base_data` #### 7. 设置数据映射关系 **接口地址:** `POST /antis/yonyou_bip/set_data_mapping` **请求参数:** ```json { "type": "department", "local_id": 1, "bip_code": "DEPT001" } ``` ### 订单同步接口 #### 1. 同步销售订单 **接口地址:** `POST /antis/yonyou_bip/sync_sales_order` **请求参数:** ```json { "order_id": 123 } ``` **返回示例:** ```json { "code": 1, "msg": "销售订单同步成功", "data": { "orderId": "BIP123456", "orderCode": "SO20240101001" } } ``` ### 2. 同步销售订单发货单 **接口地址:** `POST /antis/yonyou_bip/sync_sales_delivery` **请求参数:** ```json { "order_id": 123 } ``` **返回示例:** ```json { "code": 1, "msg": "销售订单发货单同步成功", "data": { "deliveryId": "DEL123456", "deliveryCode": "SO20240101001_DELIVERY" } } ``` ### 3. 批量同步销售订单 **接口地址:** `POST /antis/yonyou_bip/batch_sync_sales_order` **请求参数:** ```json { "order_ids": [123, 124, 125] } ``` **返回示例:** ```json { "code": 1, "msg": "同步完成:成功 2 条,失败 1 条", "data": { "success": 2, "fail": 1, "errors": [ "订单ID 125: 订单不存在" ] } } ``` ### 4. 查询同步状态 **接口地址:** `GET /antis/yonyou_bip/get_sync_status?order_id=123` **返回示例:** ```json { "code": 1, "msg": "查询成功", "data": { "order_id": 123, "order_code": "SO20240101001", "sync_status": 1, "bip_order_id": "BIP123456", "sync_time": "2024-01-01 10:00:00", "sync_log": { "id": 1, "sync_type": "sales_order", "sync_status": 1, "sync_time": 1704067200 } } } ``` ## 数据映射说明 ### 销售订单字段映射 | CRM字段 | 用友BIP字段 | 说明 | 必填 | |---------|------------|------|------| | purchase_code | orderCode | 订单编号 | 是 | | purchase_time | orderDate | 订单日期 | 是 | | - | salesOrgCode | 销售组织编码 | 是 | | - | salesOrgName | 销售组织名称 | 是 | | - | transactionTypeCode | 交易类型编码 | 是 | | - | transactionTypeName | 交易类型名称 | 是 | | customers.customer_code | customerCode | 客户编码 | 是 | | customers.customer_name | customerName | 客户名称 | 是 | | sale_user(部门) | salesDeptCode | 销售部门编码 | 是 | | sale_user(部门) | salesDeptName | 销售部门名称 | 是 | | sale_user | salesPersonCode | 销售业务员编码 | 是 | | sale_user | salesPersonName | 销售业务员名称 | 是 | | all_money | totalAmount | 订单总金额 | 是 | | tax_money | taxAmount | 税额 | 否 | | money_tax_price | totalAmountWithTax | 含税总金额 | 是 | ### 订单明细字段映射 | CRM字段 | 用友BIP字段 | 说明 | |---------|------------|------| | goods_code | goodsCode | 商品编码 | | goods_name | goodsName | 商品名称 | | goods_attr | specification | 规格 | | number | quantity | 数量 | | price | unitPrice | 单价 | | all_money | amount | 金额 | | tax_rate | taxRate | 税率 | | tax_money | taxAmount | 税额 | | money_tax_price | amountWithTax | 含税金额 | | stores_id | warehouseCode | 仓库编码 | ## 使用示例 ### JavaScript调用示例 ```javascript // 同步单个订单 $.ajax({ url: '/antis/yonyou_bip/sync_sales_order', type: 'POST', data: { order_id: 123 }, success: function(res) { if (res.code == 1) { layer.msg('同步成功'); } else { layer.msg('同步失败:' + res.msg); } } }); // 批量同步订单 $.ajax({ url: '/antis/yonyou_bip/batch_sync_sales_order', type: 'POST', data: { order_ids: [123, 124, 125] }, success: function(res) { layer.msg(res.msg); } }); ``` ### PHP调用示例 ```php use app\admin\controller\antis\YonyouBip; $controller = new YonyouBip(); // 同步订单 $result = $controller->syncSalesOrder(); ``` ## 使用流程 ### 首次使用步骤 1. **配置API参数**:在 `.env` 文件中配置用友BIP的API参数 2. **同步基础数据**:调用 `sync_all_base_data` 接口同步所有基础数据 3. **设置数据映射**:为本地数据(部门、业务员、客户)设置与用友BIP数据的映射关系 4. **配置默认值**:在 `.env` 中配置默认的销售组织和交易类型(如果订单中没有指定) 5. **同步订单**:开始同步销售订单 ### 数据映射说明 在创建销售订单时,系统会按以下优先级获取基础数据: 1. **销售组织**:优先使用配置的默认值 `YONYOU_BIP_DEFAULT_SALES_ORG_CODE` 2. **交易类型**:优先使用配置的默认值 `YONYOU_BIP_DEFAULT_TRANSACTION_TYPE_CODE` 3. **销售部门**:从订单的销售业务员(`sale_user`)获取其所属部门,然后查找对应的用友BIP部门;如果没有则使用默认值 4. **销售业务员**:从订单的 `sale_user` 字段查找对应的用友BIP业务员 5. **客户**:从订单的 `customers_id` 查找对应的用友BIP客户 ## 注意事项 1. **API端点配置**:根据用友BIP实际API文档调整 `application/extra/yonyou_bip.php` 中的API端点路径 2. **数据格式**:根据用友BIP实际要求调整 `convertOrderToBipFormat` 和 `convertDeliveryToBipFormat` 方法中的数据格式 3. **认证方式**:如果用友BIP使用其他认证方式,需要修改 `YonyouBipClient` 类中的 `getAccessToken` 方法 4. **错误处理**:同步失败时会记录错误日志,可以在同步记录表中查看详细错误信息 5. **同步状态**:订单同步成功后,会在订单表中更新 `bip_sync_status`、`bip_order_id` 和 `bip_sync_time` 字段 6. **基础数据同步**:建议定期同步基础数据,确保数据一致性 7. **数据映射**:在同步订单前,务必完成本地数据与用友BIP数据的映射关系设置 8. **必填字段**:销售组织、交易类型、客户、销售部门、销售业务员都是必填字段,如果缺少会导致同步失败 ## 扩展开发 如果需要扩展其他功能,可以: 1. 在 `YonyouBipClient` 类中添加新的API方法 2. 在 `YonyouBip` 控制器中添加对应的处理方法 3. 根据实际业务需求调整数据转换逻辑 ## 技术支持 如有问题,请查看日志文件: - 应用日志:`runtime/log/` - 同步记录:数据库表 `ats_yonyou_bip_sync_log`