YonyouBip_API_Guide.md 4.31 KB

用友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. 获取访问令牌

// 自动在 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
}

七、注意事项

  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. 批量同步:确认无误后再批量同步

九、技术支持