### 金蝶-采购退料单 --> 聚水潭-采购退货单 数据集成案例分享
在企业的日常运营中，数据集成是保障系统间信息流通和业务协同的重要环节。本篇文章将重点探讨如何使用轻易云数据集成平台实现金蝶云星空（Kingdee Cloud）与聚水潭（Jushuitan）之间的数据对接。具体场景为将金蝶云星空中的采购退料单无缝集成到聚水潭平台，并生成相应的采购退货单。
首先，我们需要可靠地抓取金蝶云星空系统中的采购退料单数据。通过调用executeBillQuery API接口，可以按需获取相应的数据。这一步骤尤为重要，需要确保没有漏单情况发生，因此我们选择定时抓取方式，以提高数据获取的稳定性和完整性。此外，为高效处理大规模的数据，还要考虑到API接口的分页和限流问题，通过合适的策略加以解决。
成功获取所需数据后，下一步是将这些数据批量写入至聚水潭平台。在这一过程中，需要特别注意两点：一是两系统间的数据格式差异；二是如何快速且准确地进行大量数据写入。针对前者，我们可以通过定制化的数据映射机制，将金蝶云星空返回的JSON数据结构转换为聚水潭可接受的格式。而对于后者，则利用聚水潭提供的/open/jushuitan/purchaseout/upload API接口，实现大批量、高效率的数据上传。
此外，考虑到实际运行环境中可能遇到各种异常情况，如网络波动、接口响应超时等，不可忽视的是异常处理与错误重试机制。例如，当一次上传请求失败时，可以自动重试一定次数或记录日志报警，从而保证整个流程更加健壮可靠。
总之，通过合理配置执行周期、优化API调用策略以及建立稳健可靠的数据传输与监控机制，在本案例中我们有效实现了金蝶云星空与聚水潭之间的信息交互，为企业内部不同业务系统提供了可信赖的数据支持。在接下来的部分，我们将详细分步骤介绍该方案具体实施细节及技术要点。
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在轻易云数据集成平台中，调用源系统的API接口是数据集成生命周期的第一步。本文将详细探讨如何通过调用金蝶云星空的`executeBillQuery`接口获取采购退料单数据，并进行初步加工。
#### 接口配置与调用
首先，我们需要配置并调用金蝶云星空的`executeBillQuery`接口。该接口主要用于查询业务单据信息，支持多种查询条件和分页参数。以下是元数据配置中的关键字段及其描述：
- **api**: `executeBillQuery`
- **method**: `POST`
- **number**: `FBillNo`
- **id**: `FPURMRBENTRY_FEntryID`
- **request**: 包含具体的请求字段，如单据编号、单据状态、退料组织等。
#### 请求参数配置
根据元数据配置，我们需要设置请求参数，以确保能够准确地获取所需的数据。以下是一些关键请求字段及其描述：
- **FPURMRBENTRY_FEntryID**: 明细信息ID
- **FID**: 实体主键
- **FBillNo**: 单据编号
- **FDocumentStatus**: 单据状态（暂存：Z，创建：A，审核中：B，已审核：C）
- **FStockOrgId_FNumber**: 退料组织
- **FDate**: 退料日期
- **FBillTypeID_FNumber**: 单据类型（如标准退料单、零散采购退料单等）
- **FSupplierID_FNumber**: 供应商
此外，还可以设置分页参数和过滤条件，例如：
```json
{
"Limit": 100,
"StartRow": 0,
"FilterString": "FApproveDate>='2023-01-01T00:00:00' and FSTOCKID.FNumber in ('CK007','CK011')",
"FieldKeys": ["FBillNo", "FDocumentStatus", "FDate", "FSupplierID_FNumber"]
}
```
#### 数据处理与转换
在获取到原始数据后，需要对其进行初步加工，以便后续的数据转换与写入。以下是一些常见的数据处理步骤：
1. **数据清洗**：去除无效或重复的数据。例如，可以根据`FDocumentStatus`过滤出已审核（C）的记录。
2. **字段映射**：将金蝶云星空中的字段映射到目标系统（如聚水潭）的字段。例如，将`FBillNo`映射为目标系统中的采购退货单编号。
3. **格式转换**：将日期格式从ISO标准转换为目标系统所需的格式。
#### 示例代码
以下是一个简单的Python示例代码，用于调用`executeBillQuery`接口并处理返回的数据：
```python
import requests
import json
# 设置请求URL和头部信息
url = "https://api.kingdee.com/executeBillQuery"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
# 设置请求参数
payload = {
"FormId": "PUR_MRB",
"FieldKeys": ["FBillNo", "FDocumentStatus", "FDate", "FSupplierID_FNumber"],
"FilterString": "FApproveDate>='2023-01-01T00:00:00' and FSTOCKID.FNumber in ('CK007','CK011')",
"Limit": 100,
"StartRow": 0
}
# 发起POST请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
# 处理响应数据
if response.status_code == 200:
data = response.json()
for record in data:
bill_no = record["FBillNo"]
document_status = record["FDocumentStatus"]
date = record["FDate"]
supplier_id = record["FSupplierID_FNumber"]
# 数据清洗与转换逻辑
if document_status == 'C':
print(f"Bill No: {bill_no}, Date: {date}, Supplier ID: {supplier_id}")
else:
print(f"Error: {response.status_code}, {response.text}")
```
通过上述步骤，我们可以高效地从金蝶云星空获取采购退料单数据，并进行初步加工，为后续的数据转换与写入做好准备。这一过程不仅提高了数据处理的透明度和效率，也为实现不同系统间的数据无缝对接奠定了基础。
### 使用轻易云数据集成平台进行ETL转换并写入聚水潭API接口
在数据集成生命周期的第二步，我们需要将已经从源平台（如金蝶）获取的数据进行ETL（提取、转换、加载）处理，并将其转换为目标平台（如聚水潭）所能接收的格式。本文将详细探讨如何使用轻易云数据集成平台完成这一过程，特别是通过配置元数据，将采购退料单数据转换为聚水潭采购退货单格式并写入目标平台。
#### API接口配置
根据提供的元数据配置，我们需要调用聚水潭的`/open/jushuitan/purchaseout/upload` API接口。该接口使用POST方法，主要字段包括外部单号（external_id）、分仓编号（wms_co_id）、供应商编号（supplier_id）、采购单号（po_id）、备注（remark）和商品集合（items）。以下是具体的配置细节：
```json
{
"api": "/open/jushuitan/purchaseout/upload",
"effect": "EXECUTE",
"method": "POST",
"number": "external_id",
"id": "external_id",
"name": "external_id",
"idCheck": true,
"operation": {
"method": "merge",
"field": "FBillNo",
"bodyName": "details",
"header": ["FBillNo"],
"body": ["FMATERIALID_FNumber", "FMRAPPQTY", "FBILLALLAMOUNT", "FLot"]
},
"request": [
{
"field": "is_confirm",
"label": "是否自动确认",
"type": "string",
"describe": "是否自动确认",
"value": false
},
{
"field": "wms_co_id",
"label": "分仓编号",
"type": "string",
"describe": "分仓编号",
"value": "{FSTOCKID_FNumber}",
...
```
#### 数据提取与转换
在ETL过程中，首先需要从金蝶系统中提取采购退料单的数据。这些数据包括订单头信息和明细信息。提取后的数据需要根据业务需求进行清洗和转换，以符合聚水潭API接口的要求。
1. **订单头信息**：包括外部单号、分仓编号、供应商编号、采购单号和备注等字段。
2. **订单明细信息**：包括商品编码、数量等字段。
例如，从金蝶系统中提取到的原始数据如下：
```json
{
...
FBillNo: 'PO12345',
FSTOCKID_FNumber: 'WH001',
FSupplierID_FNumber: 'SUP001',
FDESCRIPTION: '退货原因',
details: [
{ FMATERIALID_FNumber: 'MAT001', FMRAPPQTY: 10, FBILLALLAMOUNT: 100, FLot: 'LOT001' },
{ FMATERIALID_FNumber: 'MAT002', FMRAPPQTY: 5, FBILLALLAMOUNT: 50, FLot: 'LOT002' }
]
}
```
#### 数据映射与加载
根据元数据配置，我们需要将上述提取到的数据映射到聚水潭API接口所需的格式。映射规则如下：
- `wms_co_id` 映射到 `FSTOCKID_FNumber`
- `supplier_id` 映射到 `FSupplierID_FNumber`
- `external_id` 映射到 `FBillNo`
- `remark` 映射到 `FDESCRIPTION`
- 商品集合中的 `sku_id` 映射到 `FMATERIALID_FNumber`
- 商品集合中的 `qty` 映射到 `FMRAPPQTY`
最终生成的请求体如下：
```json
{
is_confirm: false,
wms_co_id: 'WH001',
supplier_id: '_findCollection find supplier_id from eb3ade50-c56a-34da-8afe-deb6dfd0dd7a where supplier_code=SUP001',
po_id: '',
external_id: 'PO12345',
remark: '退货原因',
items: [
{ sku_id: '_findCollection find F_CNB_Text from 046c6ba0-144d-3f00-bde4-8532a52d4073 where FNumber=MAT001', qty: '10' },
{ sku_id: '_findCollection find F_CNB_Text from 046c6ba0-144d-3f00-bde4-8532a52d4073 where FNumber=MAT002', qty: '5' }
]
}
```
#### 数据写入目标平台
最后一步是将转换后的数据通过API接口写入聚水潭系统。使用POST方法发送请求，并确保所有字段都符合API文档要求。
```javascript
const axios = require('axios');
const data = {
is_confirm: false,
wms_co_id: 'WH001',
supplier_id: '_findCollection find supplier_id from eb3ade50-c56a-34da-8afe-deb6dfd0dd7a where supplier_code=SUP001',
po_id:'',
external_id:'PO12345',
remark:'退货原因',
items:[
{ sku_id:'_findCollection find F_CNB_Text from046c6ba0-144d-3f00-bde4-8532a52d4073 where FNumber=MAT001', qty:'10'},
{ sku_id:'_findCollection find F_CNB_Text from046c6ba0-144d-3f00-bde4-8532a52d4073 where FNumber=MAT002', qty:'5'}
]
};
axios.post('https://api.jushuitan.com/open/jushuitan/purchaseout/upload', data)
.then(response => {
console.log('Data successfully uploaded:', response.data);
})
.catch(error => {
console.error('Error uploading data:', error);
});
```
通过上述步骤，我们成功实现了从金蝶系统到聚水潭系统的数据集成过程。这一过程充分利用了轻易云数据集成平台提供的全异步、多种异构系统支持以及强大的ETL功能，实现了不同系统间的数据无缝对接。
