YonyouBip_API_Guide.md
4.31 KB
用友BIP API对接指南
一、认证信息获取
1. 必需信息
- AppKey:应用标识(您已有)
- AppSecret:应用密钥(需要从用友开发者中心获取)
- 租户ID:企业租户标识
- 租户动态域名:企业专属的API访问域名(格式如:
https://yourcompany.yonyoucloud.com)
2. 获取方式
- 登录用友开发者中心:https://developer.yonyou.com
- 进入"我的应用" → 选择您的应用
- 查看应用详情,获取 AppKey 和 AppSecret
- 在用友BIP后台获取租户ID和租户动态域名
二、API认证方式
用友BIP采用 OAuth2.0 客户端凭证模式(Client Credentials)进行认证。
认证流程
- 获取访问令牌(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. 获取访问令牌
// 自动在 YonyouBipClient 中处理
$client = new YonyouBipClient($config);
$token = $client->getAccessToken(); // 自动获取并缓存
2. 调用业务API
// 创建销售订单
$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 | 服务器错误 | 联系用友技术支持 |
错误响应格式
{
"code": 400,
"message": "错误信息",
"data": null
}
七、注意事项
- Token有效期:访问令牌通常有效期为2小时,代码会自动刷新
- 请求频率限制:注意API调用频率限制,避免触发限流
- 数据格式:请求和响应数据格式为JSON
- 字符编码:统一使用UTF-8编码
- 时间格式:日期时间格式通常为
YYYY-MM-DD HH:mm:ss或YYYY-MM-DD - 必填字段:创建订单时,销售组织、交易类型、客户等为必填字段
八、测试建议
- 先测试Token获取:确保认证信息正确
- 测试基础数据接口:先同步基础数据
- 测试单个订单:先同步一个订单验证数据格式
- 批量同步:确认无误后再批量同步
九、技术支持
- 用友开发者中心:https://developer.yonyou.com
- API文档中心:https://developer.yonyou.com/openAPI
- 技术支持:联系用友BIP技术支持团队