用友BIP集成使用说明
功能概述
本模块实现了与用友BIP云平台的数据集成,主要功能包括:
- 销售订单同步:将CRM系统中的销售订单同步到用友BIP
- 销售订单发货同步:将销售订单的发货信息同步到用友BIP
安装配置
1. 数据库配置
执行SQL文件创建相关表:
# 创建同步记录表
mysql -u用户名 -p数据库名 < application/database/yonyou_bip_sync_log.sql
# 创建基础数据表
mysql -u用户名 -p数据库名 < application/database/yonyou_bip_base_data.sql
2. 环境变量配置
在项目根目录的 .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同步基础数据:
同步所有基础数据:
POST /antis/yonyou_bip/sync_all_base_data
同步指定类型的基础数据:
POST /antis/yonyou_bip/sync_base_data
{
"type": "organization" // organization-销售组织, transaction_type-交易类型, department-销售部门, person-销售业务员, customer-客户
}
设置本地数据与用友BIP数据的映射关系:
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
返回示例:
{
"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
请求参数:
{
"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
请求参数:
{
"type": "department",
"local_id": 1,
"bip_code": "DEPT001"
}
订单同步接口
1. 同步销售订单
接口地址: POST /antis/yonyou_bip/sync_sales_order
请求参数:
{
"order_id": 123
}
返回示例:
{
"code": 1,
"msg": "销售订单同步成功",
"data": {
"orderId": "BIP123456",
"orderCode": "SO20240101001"
}
}
2. 同步销售订单发货单
接口地址: POST /antis/yonyou_bip/sync_sales_delivery
请求参数:
{
"order_id": 123
}
返回示例:
{
"code": 1,
"msg": "销售订单发货单同步成功",
"data": {
"deliveryId": "DEL123456",
"deliveryCode": "SO20240101001_DELIVERY"
}
}
3. 批量同步销售订单
接口地址: POST /antis/yonyou_bip/batch_sync_sales_order
请求参数:
{
"order_ids": [123, 124, 125]
}
返回示例:
{
"code": 1,
"msg": "同步完成:成功 2 条,失败 1 条",
"data": {
"success": 2,
"fail": 1,
"errors": [
"订单ID 125: 订单不存在"
]
}
}
4. 查询同步状态
接口地址: GET /antis/yonyou_bip/get_sync_status?order_id=123
返回示例:
{
"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调用示例
// 同步单个订单
$.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调用示例
use app\admin\controller\antis\YonyouBip;
$controller = new YonyouBip();
// 同步订单
$result = $controller->syncSalesOrder();
使用流程
首次使用步骤
- 配置API参数:在
.env文件中配置用友BIP的API参数 - 同步基础数据:调用
sync_all_base_data接口同步所有基础数据 - 设置数据映射:为本地数据(部门、业务员、客户)设置与用友BIP数据的映射关系
- 配置默认值:在
.env中配置默认的销售组织和交易类型(如果订单中没有指定) - 同步订单:开始同步销售订单
数据映射说明
在创建销售订单时,系统会按以下优先级获取基础数据:
- 销售组织:优先使用配置的默认值
YONYOU_BIP_DEFAULT_SALES_ORG_CODE - 交易类型:优先使用配置的默认值
YONYOU_BIP_DEFAULT_TRANSACTION_TYPE_CODE - 销售部门:从订单的销售业务员(
sale_user)获取其所属部门,然后查找对应的用友BIP部门;如果没有则使用默认值 - 销售业务员:从订单的
sale_user字段查找对应的用友BIP业务员 - 客户:从订单的
customers_id查找对应的用友BIP客户
注意事项
- API端点配置:根据用友BIP实际API文档调整
application/extra/yonyou_bip.php中的API端点路径 - 数据格式:根据用友BIP实际要求调整
convertOrderToBipFormat和convertDeliveryToBipFormat方法中的数据格式 - 认证方式:如果用友BIP使用其他认证方式,需要修改
YonyouBipClient类中的getAccessToken方法 - 错误处理:同步失败时会记录错误日志,可以在同步记录表中查看详细错误信息
- 同步状态:订单同步成功后,会在订单表中更新
bip_sync_status、bip_order_id和bip_sync_time字段 - 基础数据同步:建议定期同步基础数据,确保数据一致性
- 数据映射:在同步订单前,务必完成本地数据与用友BIP数据的映射关系设置
- 必填字段:销售组织、交易类型、客户、销售部门、销售业务员都是必填字段,如果缺少会导致同步失败
扩展开发
如果需要扩展其他功能,可以:
- 在
YonyouBipClient类中添加新的API方法 - 在
YonyouBip控制器中添加对应的处理方法 - 根据实际业务需求调整数据转换逻辑
技术支持
如有问题,请查看日志文件:
- 应用日志:
runtime/log/ - 同步记录:数据库表
ats_yonyou_bip_sync_log