### 金蝶云星空销售退货单与纷享销客退货单的系统对接集成案例分享
在企业管理系统中，数据集成和同步是保持业务连续性和信息准确的重要环节。在本次技术案例中，我们将聚焦如何通过轻易云数据平台，将金蝶云星空的销售退货单高效、准确地对接到纷享销客。此方案名为“金蝶销售退货单对接纷享销客退货单”，旨在解决多款软件之间的数据孤岛问题，确保各业务环节的信息无缝衔接。
首先，需要从金蝶云星空实时获取销售退货单的数据，这里我们使用了`executeBillQuery`接口进行数据抓取。由于涉及大量的订单数据，需要考虑API调用过程中的分页和限流问题，通过合理的请求调度机制来实现稳定、高效的数据提取。
拆解每个步骤来看：
1. **定时可靠的抓取机制**：通过计划任务设置定期调用`executeBillQuery`接口，使得新生成或变更的销售退货单能够被及时捕捉。这避免了漏掉任何一个需要处理的数据，从而保障整个流程的一致性。
2. **快速写入到纷享销客**：针对获取到的大量数据，我们采用批量处理方式，通过并行任务将多个销售退货单快速写入到纷享销客的平台。这里用到了纷享销客提供的API `/cgi/crm/v2/data/create`，该接口支持一次提交多个记录，在提高速度的同时也降低了服务器压力。
3. **错误重试及异常处理机制**：为了应对可能出现的数据传输异常，如网络波动或 API 接口临时不可用等情况，我们设计了一套完整的错误重试策略。当首次传输失败后，会自动进行多次重试，并记录详细日志以便于后续排查。这种机制有效提升了整体操作过程中的鲁棒性（稳定性）。
4. **格式差异处理与映射**：由于两者平台间存在一定的数据结构差异，例如字段名称不同或者某些字段在目标系统内需进行特殊转换，因此我们进行了细致的数据映射定义。确保每条记录都能成功匹配相对应的位置，并准确存储至目标数据库中，这是系统集成过程中关键的一步，也直接影响最终效果。
5. **实时监控与日志记录**：整个流水线参与执行期间均有明确可视化界面展示进度，同时所有重要节点均设有精准日志输出，包括但不限于 API 请求响应时间、状态码、错误信息等。一方面帮助及时定位潜在问题点，同时又为后续性能优化提供宝贵依据资料。
综上所述，本
### 调用金蝶云星空接口executeBillQuery获取并加工数据
在数据集成过程中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，获取销售退货单数据并进行初步加工。
#### 接口配置与请求参数
首先，我们需要配置元数据，以便正确调用金蝶云星空的API接口。以下是元数据配置的关键部分：
```json
{
"api": "executeBillQuery",
"method": "POST",
"number": "FBillNo",
"id": "FEntity_FENTRYID",
"pagination": {
"pageSize": 100
},
"idCheck": true,
"request": [
{"field":"FID","label":"实体主键","type":"string","value":"FID"},
{"field":"FBillNo","label":"单据编号","type":"string","value":"FBillNo"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","value":"FSaleOrgId"},
{"field":"FStockOrgId","label":"库存组织","type":"string","value":"FStockOrgId"},
{"field":"FSettleOrgId","label":"结算组织","type":"string","value":"FSettleOrgId"},
{"field":"FApproveDate","label":"日期","type":"string","value":"FApproveDate"},
{"field":"FRetcustId","label":"客户","type":"string","value":"FRetcustId.FNumber"},
{"field":"FMaterialId_FNumber","label":"物料","type":"string","value":"FMaterialId.FNumber"},
{"field":"FOwnerIdHead","label":"货主","type":"string","value":"FOwnerIdHead"},
{"field":"FRealQty","label":"实发数量","type":"string","value":"FRealQty"},
{"field":"FStockId_FNumber","label":"仓库id","type":"string","value":"FStockId.FNumber"},
{"field":"FTaxPrice","label":"含税单价","type":"string","value":"FTaxPrice"},
{"field\":\"FRetcustId_FNumber\",\"label\":\"投诉对应客户\",\"type\":\"string\",\"value\":\"FRetcustId.FNumber\"},
{"field\":\"FSrcBillNo\",\"label\":\"源单编号\",\"type\":\"string\",\"value\":\"FSrcBillNo\"},
{"field\":\"FSalesManId_FName\",\"label\":\"销售员\",\"type\":\"string\",\"value\":\"FSalesManId.FName\"},
{"field\":\"FEntity_FENTRYID\",\"label\":\"FEntity_FENTRYID\",\"type\":\"string\",\"value\":\"FEntity_FENTRYID\"},
{"field\":\"FPrice\",\"label\":\"单价\",\"type\":\"string\",\"value\":\"FPrice\"},
{"field\":\"FBillTypeID\",\"label\":\"单据类型\",\"type\":\"string\",\"value\":\"FBillTypeID\"},
{"field\":\"FDate\",\"label\":\"日期\",\"type\":\"string\",\"value\":\"FDate\"},
{"field\": \"FilterString\", \"label\": \"过滤条件\", \"type\": \"string\", \"describe\": \"示例写法 FSupplierId.FNumber = 'VEN00010' and FApproveDate>=\", \"value\": \"FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and F_PRSH_FROM = '纷享销客'\"}
],
"otherRequest": [
{
"field": "Limit",
"label": "最大行数",
"type": "string",
"describe": "金蝶的查询分页参数",
"value": "{PAGINATION_PAGE_SIZE}"
},
{
"field": "StartRow",
"label": "开始行索引",
"type": "string",
"describe": "金蝶的查询分页参数",
"value": "{PAGINATION_START_ROW}"
}
]
}
```
#### 数据请求与清洗
在调用`executeBillQuery`接口时，我们需要发送一个POST请求，并附带必要的请求参数。这些参数包括实体主键、单据编号、销售组织、库存组织等。以下是一个示例请求体：
```json
{
"FormId": "SAL_RETURNSTOCK",
"FieldKeys": [
"FID",
"FBillNo",
"FSaleOrgId",
"FStockOrgId",
"FSettleOrgId",
"FApproveDate",
"FRetcustId.FNumber",
"FMaterialId.FNumber",
"FOwnerIdHead",
"FRealQty",
"FTaxPrice"
],
"FilterString": "'2023-01-01' <= FApproveDate and F_PRSH_FROM = '纷享销客'",
"Limit": 100,
"StartRow": 0
}
```
在这个请求体中，`FormId`指定了业务对象表单ID为`SAL_RETURNSTOCK`，即销售退货单。`FieldKeys`定义了我们需要查询的字段集合，而`FilterString`则用于过滤条件，确保只获取符合条件的数据。
#### 数据转换与写入
获取到原始数据后，我们需要对其进行清洗和转换，以便后续处理。例如，将日期格式化，将数值字段转换为标准单位等。以下是一个简单的数据清洗示例：
```python
def clean_data(raw_data):
cleaned_data = []
for record in raw_data:
cleaned_record = {
'实体主键': record['FID'],
'单据编号': record['FBillNo'],
'销售组织': record['FSaleOrgId'],
'库存组织': record['FStockOrgId'],
'结算组织': record['FSettleOrgId'],
'日期': format_date(record['FApproveDate']),
'客户': record['FRetcustId.FNumber'],
'物料': record['FMaterialId.FNumber'],
'货主': record['FOwnerIdHead'],
'实发数量': float(record['FRealQty']),
'含税单价': float(record['FTaxPrice'])
}
cleaned_data.append(cleaned_record)
return cleaned_data
def format_date(date_str):
# 假设日期格式为 YYYY-MM-DD
return datetime.strptime(date_str, '%Y-%m-%d').strftime('%Y/%m/%d')
```
通过上述代码，我们可以将原始数据中的日期格式化为标准格式，并将数值字段转换为浮点型，以便后续处理。
#### 实践案例
在实际应用中，我们可以将清洗后的数据写入目标系统，例如纷享销客退货单。以下是一个示例代码片段：
```python
def write_to_target_system(cleaned_data):
for record in cleaned_data:
response = requests.post('https://target-system-api.com/endpoint', json=record)
if response.status_code != 200:
print(f'Failed to write record: {record["实体主键"]}')
else:
print(f'Successfully wrote record: {record["实体主键"]}')
# 获取并清洗数据
raw_data = fetch_raw_data()
cleaned_data = clean_data(raw_data)
# 写入目标系统
write_to_target_system(cleaned_data)
```
通过以上步骤，我们实现了从金蝶云星空获取销售退货单数据，并将其清洗后写入目标系统的全过程。这不仅提高了数据处理效率，还确保了数据的一致性和准确性。
### 使用轻易云数据集成平台实现金蝶销售退货单对接纷享销客退货单
在数据集成生命周期的第二阶段，我们将已经从源平台（金蝶）提取并清洗的数据进行ETL转换，转为目标平台（纷享销客）API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何配置和使用元数据，以实现这一过程。
#### API接口配置
我们使用的目标API接口是`/cgi/crm/v2/data/create`，通过POST方法提交数据。为了确保数据的准确性和一致性，我们需要对数据进行多层次的转换和映射。
#### 数据请求与转换
首先，我们来看一下请求体结构：
```json
{
"api": "/cgi/crm/v2/data/create",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{
"field": "data",
"label": "数据map",
"type": "object",
"children": [
{
"field": "object_data",
"label": "表头",
"type": "object",
"children": [
{"field":"dataObjectApiName","label":"对象的api_name","type":"string","value":"ReturnedGoodsInvoiceObj"},
{"field":"name","label":"单号","type":"string","value":"{FBillNo}"},
{"field":"returned_goods_time","label":"退货日期","type":"string","value":"_function ROUND((TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', STR_TO_DATE('{FDate}', '%Y-%m-%dT%H:%i:%s')) \/ 1000),0)"},
{"field":"account_id","label":"客户","type":"string","value":"{FRetcustId_F_PBLH_FXID}"},
{"field":"owner","label":"负责人","type":"string","value":"FSUID_0F98BFB5E97E53ECE2E9666E1CACFE7B",
"parser":{"name":"StringToArray", "params": ","},
"default":"_findCollection find user_id from ad096beb-313f-340a-b153-cdf7fdf9b6d7 where name={FSalesManId_FName}"},
{"field":"field_find_association__c","label":"退货申请单id","type":"string","value":"{F_PBLH_order_id}"},
{"field":"return_mode","label":"退货模式","type":"string","value":"NonNoteReturn"},
{"field":"field_NPOrm__c","label":"金蝶单据编号","type":"string","value":"{FBillNo}"}
]
},
{
"field": "details",
"label": "明细行",
"type": "object",
"children": [
{
"field": "ReturnedGoodsInvoiceProductObj",
"label": "明细行",
"type": "array",
"value": "list",
"children":[
{"field":"product_id", "label" :"产品id", "type" :"string", "value" :"{{list.FMaterialID_F_PBLH_FXXKID}}"},
{"field" :"quantity", "label" :"数量", "type" :"string", "value" :"{{list.FRealQty}}"},
{"field" :"field_return_application_detail_id__c", "label" :"退货申请单明细行id", "type" :"string", "value" :"{{list.F_PBLH_order_Entryid}}"},
{"field" :"returned_product_price", "label" :"退货单价", "type" :"string", "value" :"{{list.FTaxPrice}}"}
]
}
]
}
]
}
],
...
}
```
#### 表头数据转换
在表头部分，我们需要将金蝶系统中的字段映射到纷享销客系统中相应的字段。例如：
- `FBillNo` 映射为 `name`
- `FDate` 转换为 `returned_goods_time`
- `FRetcustId_F_PBLH_FXID` 映射为 `account_id`
- `FSalesManId_FName` 映射为 `owner`
特别地，`returned_goods_time` 的转换需要将时间戳从字符串格式转换为Unix时间戳，这里使用了 `_function ROUND((TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', STR_TO_DATE('{FDate}', '%Y-%m-%dT%H:%i:%s')) / 1000),0)` 函数来实现。
#### 明细行数据转换
对于明细行部分，我们需要处理多个产品信息，每个产品信息包含以下字段：
- 产品ID (`product_id`)
- 数量 (`quantity`)
- 明细行ID (`field_return_application_detail_id__c`)
- 退货单价 (`returned_product_price`)
这些字段通过遍历列表中的每一项来填充，例如：
```json
{"field": "{{list.FMaterialID_F_PBLH_FXXKID}}"}
```
#### 操作人信息
此外，我们还需要传递当前操作人的用户ID，这里直接使用预定义的用户ID：
```json
{"currentOpenUserId", "FSUID_F56CEEA6EDDBFE10681577526DF83326"}
```
#### 数据写入操作
最后，通过配置元数据中的操作部分，我们可以定义如何合并和处理这些数据。在这里，我们指定了合并方法、主键字段、以及需要合并的表头和明细字段：
```json
{
...
,"operation":{
...
,"method:"merge"
,"bodyName:"list"
,"bodySum":["FRealQty"]
,"header":["FRetcustId_F_PBLH_FXID",..."FBillNo"]
,"body":["FMaterialId_FNumber"...]
}
}
```
通过以上配置，可以实现将金蝶销售退货单的数据无缝对接到纷享销客系统中。这不仅简化了跨系统的数据集成流程，还提高了业务处理效率。
