Blame view

application/admin/controller/antis/YonyouBip_API_Guide.md 4.31 KB
2db47680   hexiaodong   chore: 初始提交 php 遗...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
  # 用友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技术支持团队