金蝶数据转换并同步到纷享销客API接口的实现方法

  • 轻易云集成顾问-冯潇

金蝶云星空销售退货单与纷享销客退货单的系统对接集成案例分享

在企业管理系统中，数据集成和同步是保持业务连续性和信息准确的重要环节。在本次技术案例中，我们将聚焦如何通过轻易云数据平台，将金蝶云星空的销售退货单高效、准确地对接到纷享销客。此方案名为“金蝶销售退货单对接纷享销客退货单”，旨在解决多款软件之间的数据孤岛问题，确保各业务环节的信息无缝衔接。

首先，需要从金蝶云星空实时获取销售退货单的数据，这里我们使用了executeBillQuery接口进行数据抓取。由于涉及大量的订单数据，需要考虑API调用过程中的分页和限流问题，通过合理的请求调度机制来实现稳定、高效的数据提取。

拆解每个步骤来看：

  1. 定时可靠的抓取机制：通过计划任务设置定期调用executeBillQuery接口，使得新生成或变更的销售退货单能够被及时捕捉。这避免了漏掉任何一个需要处理的数据，从而保障整个流程的一致性。

  2. 快速写入到纷享销客：针对获取到的大量数据，我们采用批量处理方式，通过并行任务将多个销售退货单快速写入到纷享销客的平台。这里用到了纷享销客提供的API /cgi/crm/v2/data/create，该接口支持一次提交多个记录，在提高速度的同时也降低了服务器压力。

  3. 错误重试及异常处理机制：为了应对可能出现的数据传输异常，如网络波动或 API 接口临时不可用等情况，我们设计了一套完整的错误重试策略。当首次传输失败后，会自动进行多次重试，并记录详细日志以便于后续排查。这种机制有效提升了整体操作过程中的鲁棒性（稳定性）。

  4. 格式差异处理与映射：由于两者平台间存在一定的数据结构差异，例如字段名称不同或者某些字段在目标系统内需进行特殊转换，因此我们进行了细致的数据映射定义。确保每条记录都能成功匹配相对应的位置，并准确存储至目标数据库中，这是系统集成过程中关键的一步，也直接影响最终效果。

  5. 实时监控与日志记录：整个流水线参与执行期间均有明确可视化界面展示进度，同时所有重要节点均设有精准日志输出，包括但不限于 API 请求响应时间、状态码、错误信息等。一方面帮助及时定位潜在问题点，同时又为后续性能优化提供宝贵依据资料。

综上所述，本 用友与外部系统接口集成开发

调用金蝶云星空接口executeBillQuery获取并加工数据

在数据集成过程中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用金蝶云星空的executeBillQuery接口，获取销售退货单数据并进行初步加工。

接口配置与请求参数

首先，我们需要配置元数据，以便正确调用金蝶云星空的API接口。以下是元数据配置的关键部分：

{
  "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请求，并附带必要的请求参数。这些参数包括实体主键、单据编号、销售组织、库存组织等。以下是一个示例请求体：

{
  "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则用于过滤条件，确保只获取符合条件的数据。

数据转换与写入

获取到原始数据后，我们需要对其进行清洗和转换，以便后续处理。例如，将日期格式化，将数值字段转换为标准单位等。以下是一个简单的数据清洗示例：

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')

通过上述代码，我们可以将原始数据中的日期格式化为标准格式，并将数值字段转换为浮点型，以便后续处理。

实践案例

在实际应用中，我们可以将清洗后的数据写入目标系统，例如纷享销客退货单。以下是一个示例代码片段：

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)

通过以上步骤，我们实现了从金蝶云星空获取销售退货单数据，并将其清洗后写入目标系统的全过程。这不仅提高了数据处理效率，还确保了数据的一致性和准确性。 金蝶与MES系统接口开发配置

使用轻易云数据集成平台实现金蝶销售退货单对接纷享销客退货单

在数据集成生命周期的第二阶段，我们将已经从源平台（金蝶）提取并清洗的数据进行ETL转换，转为目标平台（纷享销客）API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何配置和使用元数据，以实现这一过程。

API接口配置

我们使用的目标API接口是/cgi/crm/v2/data/create，通过POST方法提交数据。为了确保数据的准确性和一致性，我们需要对数据进行多层次的转换和映射。

数据请求与转换

首先，我们来看一下请求体结构：

{
  "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)

这些字段通过遍历列表中的每一项来填充，例如：

{"field": "{{list.FMaterialID_F_PBLH_FXXKID}}"}

操作人信息

此外，我们还需要传递当前操作人的用户ID，这里直接使用预定义的用户ID：

{"currentOpenUserId",   "FSUID_F56CEEA6EDDBFE10681577526DF83326"}

数据写入操作

最后，通过配置元数据中的操作部分，我们可以定义如何合并和处理这些数据。在这里，我们指定了合并方法、主键字段、以及需要合并的表头和明细字段：

{
  ...
  ,"operation":{
    ...
    ,"method:"merge"
    ,"bodyName:"list"
    ,"bodySum":["FRealQty"]
    ,"header":["FRetcustId_F_PBLH_FXID",..."FBillNo"]
    ,"body":["FMaterialId_FNumber"...]
  }
}

通过以上配置，可以实现将金蝶销售退货单的数据无缝对接到纷享销客系统中。这不仅简化了跨系统的数据集成流程，还提高了业务处理效率。 如何开发用友BIP接口

版权声明

该文章《金蝶云星空销售退货单与纷享销客的数据对接解决方案》为原创内容，版权归 广东轻亿云软件科技有限公司 所有。 未经本公司书面授权，严禁转载、引用、复制或建立镜像等行为。 若需转载或引用本文内容，请联系本公司获取授权，并在显著位置注明作者姓名、文章出处（包括原文链接）等信息。

金蝶云星辰与旺店通无缝集成
更多系统对接方案