金蝶云星辰V2接口数据转换与写入实战指南

  • 轻易云集成顾问-谢楷斌

汤臣倍健营销云数据集成到金蝶云星辰V2案例分享：新版订单-出库单(杭州佰健盛吉)

在汤臣倍健的营销与运营过程中，如何高效、可靠地将营销云数据无缝对接至金蝶云星辰V2系统，是提升业务效率和透明度的重要环节。本文将深入探讨“新版订单-出库单(杭州佰健盛吉)”方案的实际操作与实现过程，重点关注API接口调用、数据处理策略以及异常处理机制。

为了确保此次系统集成的顺利实施，我们部署了一套成熟且灵活的数据抓取及写入解决方案。首先，通过定时任务可靠地从汤臣倍健营销云获取最新的订单信息。这一过程通过调用 /api/openapi/v1/erp/order/honour/agreement/header 接口实现，该接口支持分页和限流，因此，我们設计了精细化的数据抓取逻辑以应对这些限制。同时，为了避免漏单情況发生，在每一次数据获取后都会进行日志记录和状态标记，确保每条记录都能被完整捕获。

其次，对于大量订单数据，需要快速、高效地批量写入到金蝶云星辰V2中，这里我们使用了 /jdy/v2/scm/sal_out_bound API。在此过程中，不仅需要考虑数据格式转换问题，还要处理好网络请求中的异常恢复和错误重试机制。为此，我们设计了一套自动化错误检测与重试框架，当遇到提交失败或响应超时等状况时，可立即触发补偿机制，保证数据交互的一致性。

此外，在整个系统运行周期中，对实时监控与日志记录进行了全面覆盖，每一个关键节点上的操作均可视化呈现，并能够及时预警潜在风险。这种全生命周期管理方式大幅提升了业务透明度，有助于快速定位并解决问题，从而使得整个集成流程更加高效稳定。

下一步内容我们会详细解析具体技术实现，包括API接口参数配置、分页限流处理、格式转换方法等，以期为业内相关系统集成提供有价值的参考经验。 用友与外部系统接口集成开发

调用汤臣倍健营销云接口获取并加工数据的技术案例

在数据集成过程中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用汤臣倍健营销云接口 /api/openapi/v1/erp/order/honour/agreement/header 获取并加工数据。

接口调用配置

首先，我们需要配置元数据以便正确调用接口。以下是元数据配置的关键字段及其含义：

  • api: /api/openapi/v1/erp/order/honour/agreement/header
  • effect: QUERY
  • method: POST
  • idCheck: true

请求参数如下：

[
    {"field":"orgId","label":"组织ID","type":"string","describe":"111","value":"f786408568bd4629b2445e8235d5b495"},
    {"field":"page","label":"页码","type":"string","describe":"111","value":"1"},
    {"field":"id","label":"订单id","type":"string","describe":"111"},
    {"field":"applyerId","label":"要货方id","type":"string","describe":"111"},
    {"field":"supplierId","label":"供货方id","type":"string","describe":"111"},
    {"field":"no","label":"订单号","type":"string","describe":"111"},
    {"field":"distributionType","label":"分销类型","type":"string","describe":"111"},
    {"field":"distributorId","label":"分销商id","type":"string","describe":"111"},
    {"field":"orderStatus","label":"订单状态","type":"string","describe":"111",
     "value": "WAIT_FINANCE_AUDIT,WAIT_DELIVERY,PART_DELIVERY,ALL_DELIVERY,WAIT_OUT_STORAGE,PART_OUT_STORAGE,ALL_OUT_STORAGE,PART_CONFIRM,CONFIRM,AUDIT_SUCCESS,FINISH,CLOSE"},
    {"field": "createDt", "label": "创建时间", "type": "string", "describe": "111"},
    {"field": "orderTypeCode", "label": "订单类型,如普通订单、直运销售", "type": "string", "describe": "111"},
    {"field": "isDeliveryFreezed", "label": "是否暂停发货", "type": "string", "describe": "111"},
    {"field": "nature", "label": "单据类型1订单、2退货", "type": "string", 
     "describe": "111",     "value":    "1" },
    {"field":   "relatedApplyerId",     "label":    "关联交易经销商id",    "type":     "string",   "describe":     "111" },
    {"field":   "saleDistribution",     "label":    "销售渠道",     "type":     "string",   "describe":     "111" },
    {"field":   "disApplyerId",     "label":    "分销商id",    "type":     "string",   "describe":     "111" },
    {"field":

请求参数解析

在请求参数中，orgId、page、orderStatus 和 nature 是必填字段，其中 orgId 表示组织ID，page 表示页码，orderStatus 用于过滤订单状态，而 nature 固定为值 1 表示查询订单。

此外，时间相关的字段如 lastStartDt 和 lastEndDt 使用动态变量来表示上次同步时间和当前时间，这样可以确保每次调用都能获取到最新的数据变化。

数据清洗与转换

在获取到原始数据后，需要对数据进行清洗和转换。以下是一个简单的数据清洗与转换流程：

  1. 数据格式化：确保日期格式统一，将所有日期字段转换为标准的ISO8601格式。
  2. 字段映射：根据目标系统的需求，对字段进行重命名或映射。例如，将 applyerId 映射为目标系统中的 requester_id。
  3. 数据过滤：根据业务需求，过滤掉不必要的数据。例如，只保留状态为 CONFIRM 的订单。

实现代码示例

以下是一个简化的Python代码示例，用于展示如何通过API获取数据并进行基本的清洗和转换：

import requests
import json
from datetime import datetime

# 配置API请求参数
url = 'https://example.com/api/openapi/v1/erp/order/honour/agreement/header'
headers = {'Content-Type': 'application/json'}
payload = {
    'orgId': 'f786408568bd4629b2445e8235d5b495',
    'page': '1',
    'orderStatus': 'CONFIRM',
    'nature': '1',
    'lastStartDt': (datetime.now() - timedelta(days=1)).isoformat(),
    'lastEndDt': datetime.now().isoformat()
}

# 发起POST请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

# 数据清洗与转换
cleaned_data = []
for order in data['orders']:
    cleaned_order = {
        'requester_id': order['applyerId'],
        'supplier_id': order['supplierId'],
        'order_number': order['no'],
        # 更多字段映射...
        'created_at': datetime.strptime(order['createDt'], '%Y-%m-%dT%H:%M:%S').isoformat()
    }
    cleaned_data.append(cleaned_order)

# 输出清洗后的数据
print(json.dumps(cleaned_data, indent=2))

以上代码展示了如何通过API获取原始订单数据，并对其进行基本的清洗和转换。实际应用中，可以根据具体业务需求进一步扩展和优化清洗与转换逻辑。

通过这种方式，我们可以高效地从汤臣倍健营销云获取所需的数据，并将其加工成符合目标系统要求的格式，为后续的数据处理和分析奠定基础。 如何对接用友BIP接口

使用轻易云数据集成平台实现金蝶云星辰V2 API接口的数据转换与写入

在数据集成生命周期的第二步中，我们将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星辰V2 API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何通过轻易云数据集成平台配置元数据，实现这一过程。

元数据配置解析

以下是我们需要配置的元数据，用于将订单出库单的数据转换并写入金蝶云星辰V2：

{
  "api": "/jdy/v2/scm/sal_out_bound",
  "effect": "EXECUTE",
  "method": "POST",
  "number": "id",
  "id": "id",
  "name": "id",
  "idCheck": true,
  "request": [
    {"field":"bill_source","label":"单据来源，固定传入ISV","type":"string","describe":"单据来源，固定传入APP","value":"ISV"},
    {"field":"bill_date","label":"出库日期,格式：2019-01-01","type":"datetime","describe":"出库日期,格式：2019-01-01","value":"{{approveDt|date}}"},
    {"field":"bill_no","label":"单据编码","type":"string","value":"{no}"},
    {"field":"customer_id","label":"客户id","type":"string","describe":"客户信息","value":"_findCollection find id from b41660e7-fa00-318f-bbee-1395e229ee6b where number={clientAppNo}"},
    {"field":"remark","label":"单据备注","type":"string","value":"{remark}"},
    {"field":"contact_linkman","label":"联系信息-联系人","type":"string","value":"{contacts}"},
    {"field":"contact_phone","label":"联系信息-联系方式","type":"string","value":"{phone}"},
    {"field":"contact_address","label":"联系信息-详细地址","type":"string","value":"{shippingAddress}"},
    {"field":"dept_id","label":"部门","type":"string","value":"1320359454654379008"},
    {"field":"custom_field", "label": "自定义字段", "type": "object", 
      "children":[{"field": "custom_field__1__2xietiob41d0jia2", 
                   "label": "营销云备注", 
                   "type": "string", 
                   "value": "{no}"}
                 ]
    },
    {"field": "material_entity", 
     "label": "商品分录", 
     "type": "array", 
     "describe": "商品分录", 
     "value": "details", 
     "children":[
       {"field": "material_number", 
        "label": "商品", 
        "type": "string", 
        "describe": "商品", 
        "value": "{productNo}"
       },
       {"field": "stock_id", 
        "label": "仓库", 
        "type": "string", 
        ...
       }
     ]
    }
  ]
}

数据请求与清洗

在数据请求与清洗阶段，我们从源系统获取原始订单数据。这些数据可能包括订单编号、客户信息、商品明细等。通过轻易云的数据清洗功能，我们可以确保这些原始数据符合目标系统的要求。例如，将日期格式化为YYYY-MM-DD，或将客户编号转换为目标系统中的客户ID。

数据转换与写入

在这个阶段，我们将清洗后的数据按照金蝶云星辰V2 API接口的要求进行转换，并通过POST请求将其写入目标系统。以下是关键步骤和技术细节：

  1. 设置API端点和请求方法：

    • api: /jdy/v2/scm/sal_out_bound
    • method: POST

  2. 构建请求体：

    • 单据基础信息：
      • bill_source: 固定传入ISV
      • bill_date: 使用模板变量{{approveDt|date}}格式化日期
      • bill_no: 单据编码 {no}
      • customer_id: 客户ID，通过 _findCollection 方法查找
      • remark: 单据备注 {remark}
    • 联系信息：
      • contact_linkman: 联系人 {contacts}
      • contact_phone: 联系电话 {phone}
      • contact_address: 联系地址 {shippingAddress}
    • 部门信息：
      • dept_id: 固定值 1320359454654379008
    • 自定义字段：
      • 包含营销云备注 {no}

  3. 商品分录信息：

    • 每个商品分录包含多个字段，如商品编号、仓库ID、数量、单位ID等。
    • 使用模板变量和查找函数 _findCollection 获取具体值。例如，单位ID通过 _findCollection find base_unit_id from ... where number={{details.extNo}} 获取。

  4. 计算字段：

    • 对于需要计算的字段，例如折扣额，可以使用函数 _function ({basePrice} - {price}) * {quantity} 动态计算。

示例代码

以下是一个示例代码片段，用于生成POST请求体：

{
  ...
  {
    field: 'material_entity',
    label: '商品分录',
    type: 'array',
    value: details.map(detail => ({
      material_number: detail.productNo,
      stock_id: '1320319159514457088',
      qty: detail.quantity,
      unit_id: _findCollection('base_unit_id', '395d1591-aee0-3f10-ad09-d5593167af48', detail.extNo),
      tax_price: detail.basePrice,
      is_free: 'false',
      batch_no: detail._Flot,
      kf_date: detail._Fmfg,
      valid_date: detail._Fexp,
      kf_period: '730',
      kf_type: '1',
      dis_amount: _function(`${detail.basePrice} - ${detail.price}`) * detail.quantity,
      cess: ''
    }))
  }
}

通过以上配置和代码示例，我们可以高效地将源平台的数据转换为金蝶云星辰V2 API接口所需的格式，并顺利写入目标系统。这一过程不仅提升了数据处理的准确性和效率，也确保了不同系统间的数据无缝对接。 如何对接钉钉API接口

版权声明

该文章《高效整合：汤臣倍健订单数据集成到金蝶云星辰V2》为原创内容，版权归 广东轻亿云软件科技有限公司 所有。 未经本公司书面授权，严禁转载、引用、复制或建立镜像等行为。 若需转载或引用本文内容，请联系本公司获取授权，并在显著位置注明作者姓名、文章出处（包括原文链接）等信息。

金蝶云星辰与吉客云对接
更多系统对接方案