### 案例分享：金蝶销售出库单对接纷享销客发货单
在本文中，介绍一个具体的系统对接集成案例，即将金蝶云星空中的销售出库单数据集成到纷享销客的发货单模块。该方案旨在实现两个不同系统之间的数据同步和业务流程联动，有效提升企业在订单处理和发货管理上的效率。
#### 集成挑战与解决方案概述
该集成过程中，我们遇到了多个技术性挑战，包括如何确保数据不漏单、大量数据快速写入、定时可靠抓取接口数据以及分页限流处理等。在这个示例中，借助executeBillQuery API从金蝶云星空获取销售出库单数据，并通过/cgi/crm/v2/data/create API将其写入到纷享销客。
1. **确保数据不漏单**：使用轻易云平台提供的全生命周期管理功能，每个环节都进行实时监控，确保任何异常情况都能及时发现并重试。
2. **大量数据快速写入**：为了应对大批量订单的数据处理需求，我们采用了多线程并发写入的方法，并针对纷享销客API进行了性能优化，以最大程度减少请求耗时。
3. **调用executeBillQuery接口抓取金蝶云星空数据**：根据业务需求设定定时任务，通过executeBillQuery接口抓取最新的销售出库单信息，在保证准实时性的基础上有效减轻系统负担。
4. **分页和限流的问题处理**：由于API接口有访问频率限制，我们设计了智能限流机制，对每次查询进行合理分配，同时采用分页策略分批获取大规模数据，从而避免因为超频率访问导致的数据丢失或服务器压力过大问题。
5. **跨系统间的数据格式差异转换**：针对金蝶云星空与纷享销客之间存在的数据格式差异，我们设计了一套灵活的映射规则，将原始字段转化为目标字段，并保证所有关键业务逻辑的一致性。
6. **错误重试机制与日志记录**：集成过程还涉及复杂的异常捕获及重试机制，如若发生错误，该机制可自动重新尝试操作，同时所有过程均有详细日志记录以便后续追溯分析。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将深入探讨如何使用轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口来获取销售出库单数据，并对其进行初步加工。
#### 接口配置与请求参数
首先，我们需要了解`executeBillQuery`接口的基本配置和请求参数。根据提供的元数据配置，以下是关键字段及其描述：
- **API**: `executeBillQuery`
- **Method**: `POST`
- **Effect**: `QUERY`
- **FormId**: `SAL_OUTSTOCK`
请求参数包括单据类型、单据编号、日期、销售组织等多个字段。这些字段在请求体中以JSON格式传递。
```json
{
"FormId": "SAL_OUTSTOCK",
"FieldKeys": "FBillNo,FDate,FSaleOrgId.FNumber,FCustomerID.FNumber,FMaterialID.FNumber,FRealQty,FPrice",
"FilterString": "FApproveDate>='2023-01-01' and F_PRSH_FROM = '纷享销客'",
"Limit": 100,
"StartRow": 0
}
```
#### 请求示例
为了调用`executeBillQuery`接口，我们需要构建一个HTTP POST请求。以下是一个示例请求：
```http
POST /k3cloud/api/executeBillQuery HTTP/1.1
Host: api.kingdee.com
Content-Type: application/json
Authorization: Bearer <token>
{
"FormId": "SAL_OUTSTOCK",
"FieldKeys": [
"FBillNo",
"FDate",
"FSaleOrgId.FNumber",
"FCustomerID.FNumber",
"FMaterialID.FNumber",
"FRealQty",
"FPrice"
],
"FilterString": "FApproveDate>='2023-01-01' and F_PRSH_FROM = '纷享销客'",
"Limit": 100,
"StartRow": 0
}
```
#### 数据处理与清洗
在接收到金蝶云星空返回的数据后，需要对其进行初步处理和清洗，以便后续的数据转换和写入。假设返回的数据格式如下：
```json
[
{
"FBillNo": "SO202301010001",
"FDate": "2023-01-01",
"FSaleOrgId_FNumber": "ORG001",
"FCustomerID_FNumber": "CUST001",
"FMaterialID_FNumber": "MAT001",
"FRealQty": 10,
"FPrice": 100.0
},
...
]
```
我们可以使用轻易云平台提供的数据处理工具，对这些数据进行清洗。例如，将日期格式化，将数量和价格转换为统一的单位等。
```python
def clean_data(data):
for record in data:
record['FDate'] = format_date(record['FDate'])
record['FRealQty'] = convert_quantity(record['FRealQty'])
record['FPrice'] = convert_price(record['FPrice'])
return data
def format_date(date_str):
# 假设日期格式为YYYY-MM-DD，将其转换为其他所需格式
return datetime.strptime(date_str, '%Y-%m-%d').strftime('%d/%m/%Y')
def convert_quantity(quantity):
# 转换数量单位，例如从件转换为箱
return quantity / 10
def convert_price(price):
# 转换价格单位，例如从元转换为美元
return price * 0.15
cleaned_data = clean_data(raw_data)
```
#### 数据验证与错误处理
在数据处理过程中，还需要进行数据验证和错误处理。例如，确保所有必填字段都有值，数值字段没有负值等。如果发现错误，可以记录日志或抛出异常，以便后续排查。
```python
def validate_data(data):
for record in data:
if not record['FBillNo']:
raise ValueError("单据编号不能为空")
if record['FRealQty'] < 0:
raise ValueError("实发数量不能为负")
if record['FPrice'] < 0:
raise ValueError("单价不能为负")
validate_data(cleaned_data)
```
通过上述步骤，我们可以高效地调用金蝶云星空的`executeBillQuery`接口获取销售出库单数据，并对其进行初步加工，为后续的数据转换和写入做好准备。
### 金蝶销售出库单对接纷享销客发货单的ETL转换与写入
在数据集成生命周期的第二步，我们将重点讨论如何将已经集成的源平台数据进行ETL转换，并转为目标平台纷享销客API接口所能够接收的格式，最终写入目标平台。本文将详细探讨元数据配置及其在实际操作中的应用。
#### API接口及请求方法
我们使用的纷享销客API接口路径为`/cgi/crm/v2/data/create`，请求方法为`POST`。该接口用于创建新的数据记录。为了确保数据唯一性和完整性，我们启用了ID检查功能（`idCheck: true`）。
#### 数据请求结构
请求体主要由两部分构成：表头（`object_data`）和明细行（`details`）。以下是详细的字段配置：
##### 表头字段
1. **对象的api_name** (`dataObjectApiName`)
- 类型：字符串
- 固定值：`DeliveryNoteObj`
2. **单号** (`name`)
- 类型：字符串
- 来源字段：`{FBillNo}`
3. **发货日期** (`delivery_date`)
- 类型：字符串
- 转换函数：将时间戳转换为毫秒数并四舍五入
```sql
_function ROUND((TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', STR_TO_DATE('{FDate}', '%Y-%m-%dT%H:%i:%s')) / 1000),0)
```
4. **客户** (`account_id`)
- 类型：字符串
- 来源字段：`{FCustomerID_F_PBLH_FXID}`
- 默认值查找：
```sql
_findCollection find _id from eee2cf57-51af-3eb4-bf10-f6950c7c315f where account_no={FCustomerID_FNumber}
```
5. **销售订单id** (`sales_order_id`)
- 类型：字符串
- 来源字段：`{F_PBLH_order_id}`
6. **负责人** (`owner`)
- 类型：字符串
- 固定值：`FSUID_0F98BFB5E97E53ECE2E9666E1CACFE7B`
- 解析器配置：
```json
{"name":"StringToArray","params":","}
```
- 默认值查找：
```sql
_findCollection find user_id from ad096beb-313f-340a-b153-cdf7fdf9b6d7 where name={FSalesManID_FName}
```
7. **金蝶单号** (`field_single_line_text__c`)
- 类型：字符串
- 来源字段：`{FBillNo}`
8. **仓库** (`field_1Z1c6__c`)
- 类型：字符串
- 来源字段：`{FStockID_FNumber}`
9. **物流单号** (`express_order_id`)
- 类型：字符串
- 来源字段：`{FCarryBillNo}`
10. **物流公司名称** (`new_logistics_company__c`)
- 类型：字符串
- 来源字段：`{FLogComId_FName}`
##### 明细行字段
1. **产品id** (`product_id`)
- 类型：字符串
- 来源字段：
```sql
{{list.FMaterialID_F_PBLH_FXXKID}}
```
- 默认值查找：
```sql
_findCollection find _id from 08c3b953-744a-34c4-a4cd-e47fece8d846 where product_code={{list.FMaterialID_FNumber}}
```
2. **本次发货数** (`delivery_num`)
- 类型：字符串
- 来源字段：
```sql
{{list.FRealQty}}
```
3. **销售订单id** (`sales_order_id`)
- 类型：字符串
- 来源字段：
```sql
{F_PBLH_order_id}
```
4. **订单产品行id** (`sales_order_product_id`)
- 类型：字符串
- 来源字段：
```sql
{{list.F_PBLH_order_Entryid}}
```
5. **销售单价** (`sales_price`)
- 类型：字符串
- 来源字段：
```sql
{{list.FTaxPrice}}
```
6. **含税单价** (`field_1xshQ__c`)
- 类型：字符串
- 来源字段：
```sql
{{list.FTaxPrice}}
```
7. **价税合计** (`field_l14VE__c`)
- 类型：字符串
- 来源字段：
```sql
{{list.FAllAmount}}
```
8. **发货单号** (`field_xnz1K__c`)
- 类型：字符串
- 来源字段：
```sql
{FBillNo}
```
#### 其他请求参数
除了上述表头和明细行的数据外，还需要传递当前操作人的用户ID：
```json
{"currentOpenUserId":"FSUID_F56CEEA6EDDBFE10681577526DF83326"}
```
#### 操作方法及合并策略
为了确保数据的一致性和完整性，我们采用了合并策略：
```json
{"method":"merge","field":"FBillNo","bodyName":"list","bodySum":["FRealQty"],"header":["FBillNo","FDate","FCustomerID_F_PBLH_FXID","F_PBLH_order_id"],"body":["FMaterialID_F_PBLH_FXXKID","FRealQty","F_PBLH_order_Entryid","FTaxPrice","FAllAmount"]}
```
该策略根据单号（FBillNo）进行合并，并对明细行中的发货数量（FRealQty）进行求和。
通过上述配置，我们能够实现从金蝶销售出库单到纷享销客发货单的数据转换与写入，确保每个环节的数据准确无误。
