# 用友BIP API对接指南 ## 一、认证信息获取 ### 1. 必需信息 - **AppKey**:应用标识(您已有) - **AppSecret**:应用密钥(需要从用友开发者中心获取) - **租户ID**:企业租户标识 - **租户动态域名**:企业专属的API访问域名(格式如:`https://yourcompany.yonyoucloud.com`) ### 2. 获取方式 1. 登录用友开发者中心:https://developer.yonyou.com 2. 进入"我的应用" → 选择您的应用 3. 查看应用详情,获取 AppKey 和 AppSecret 4. 在用友BIP后台获取租户ID和租户动态域名 ## 二、API认证方式 用友BIP采用 **OAuth2.0** 客户端凭证模式(Client Credentials)进行认证。 ### 认证流程 1. **获取访问令牌(Access Token)** ``` POST https://{租户动态域名}/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials client_id={AppKey} client_secret={AppSecret} ``` 2. **使用Token调用API** ``` GET/POST https://{租户动态域名}/api/... Authorization: Bearer {AccessToken} Content-Type: application/json tenant-id: {租户ID} ``` ## 三、配置步骤 ### 1. 环境变量配置 在项目根目录的 `.env` 文件中添加: ```env # 用友BIP配置 YONYOU_BIP_BASE_URL=https://yourcompany.yonyoucloud.com YONYOU_BIP_APP_KEY=你的AppKey YONYOU_BIP_APP_SECRET=你的AppSecret YONYOU_BIP_TENANT_ID=你的租户ID YONYOU_BIP_ENABLED=true ``` ### 2. 租户动态域名说明 - **公有云**:格式为 `https://{企业标识}.yonyoucloud.com` - **私有云**:格式为 `https://{企业标识}.yonyoucloud.com` 或自定义域名 - **本地部署**:格式为 `https://{IP或域名}:{端口}` ## 四、API调用示例 ### 1. 获取访问令牌 ```php // 自动在 YonyouBipClient 中处理 $client = new YonyouBipClient($config); $token = $client->getAccessToken(); // 自动获取并缓存 ``` ### 2. 调用业务API ```php // 创建销售订单 $orderData = [ 'orderCode' => 'SO20240101001', 'orderDate' => '2024-01-01', 'salesOrgCode' => 'ORG001', // ... 其他字段 ]; $result = $client->createSalesOrder($orderData); ``` ## 五、常见API端点 根据用友BIP实际API文档,常见端点包括: ### 基础数据API - `/api/base/sales/organization/list` - 获取销售组织列表 - `/api/base/transaction/type/list` - 获取交易类型列表 - `/api/base/sales/department/list` - 获取销售部门列表 - `/api/base/sales/person/list` - 获取销售业务员列表 - `/api/base/customer/list` - 获取客户列表 ### 销售订单API - `/api/sales/order/create` - 创建销售订单 - `/api/sales/order/update` - 更新销售订单 - `/api/sales/order/list` - 查询销售订单列表 - `/api/sales/order/detail/{id}` - 获取销售订单详情 ### 销售发货API - `/api/sales/delivery/create` - 创建销售发货单 - `/api/sales/delivery/list` - 查询销售发货单列表 **注意**:实际API端点路径可能因版本而异,请参考用友BIP官方API文档。 ## 六、错误处理 ### 常见错误码 | 错误码 | 说明 | 解决方案 | |--------|------|----------| | 401 | 认证失败 | 检查AppKey、AppSecret是否正确 | | 403 | 权限不足 | 检查应用权限配置 | | 404 | 接口不存在 | 检查API端点路径是否正确 | | 500 | 服务器错误 | 联系用友技术支持 | ### 错误响应格式 ```json { "code": 400, "message": "错误信息", "data": null } ``` ## 七、注意事项 1. **Token有效期**:访问令牌通常有效期为2小时,代码会自动刷新 2. **请求频率限制**:注意API调用频率限制,避免触发限流 3. **数据格式**:请求和响应数据格式为JSON 4. **字符编码**:统一使用UTF-8编码 5. **时间格式**:日期时间格式通常为 `YYYY-MM-DD HH:mm:ss` 或 `YYYY-MM-DD` 6. **必填字段**:创建订单时,销售组织、交易类型、客户等为必填字段 ## 八、测试建议 1. **先测试Token获取**:确保认证信息正确 2. **测试基础数据接口**:先同步基础数据 3. **测试单个订单**:先同步一个订单验证数据格式 4. **批量同步**:确认无误后再批量同步 ## 九、技术支持 - 用友开发者中心:https://developer.yonyou.com - API文档中心:https://developer.yonyou.com/openAPI - 技术支持:联系用友BIP技术支持团队