YonyouBip_README.md 9.08 KB

用友BIP集成使用说明

功能概述

本模块实现了与用友BIP云平台的数据集成,主要功能包括:

  1. 销售订单同步:将CRM系统中的销售订单同步到用友BIP
  2. 销售订单发货同步:将销售订单的发货信息同步到用友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();

使用流程

首次使用步骤

  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