### PACKAGE-吉客云采购入库单对接：从API调用到数据流设计
在现代企业的数据管理中，系统的集成与数据互通显得尤为重要，其中，如何将吉客云中的采购入库单高效、准确地集成至金蝶云星辰V2成为不少企业面临的一大挑战。本文将详细解析使用轻易云数据集成平台，通过API接口实现两者间的数据无缝对接。
首先，我们需要明确涉及的两个关键API接口：吉客云获取数据的`erp.storage.goodsdocin.v2`和金蝶云星辰V2写入数据的`/jdy/v2/scm/pur_inbound`。这两个接口分别负责采集与存储操作，是整个流程中的核心环节。
为确保采购入库单不漏单且能实时同步至目标系统，我们采用了定时抓取策略，同时结合高吞吐量的数据写入能力，使得大量数据能够迅速而安全地注入到金蝶云星辰V2中。此外，通过轻易云提供的可视化数据流设计工具，我们不仅能直观配置和监控每一个步骤，还可以自定义复杂的数据转换逻辑，以适应两套系统可能存在的数据结构差异。
在实际操作过程中，对异常处理机制及分页、限流问题也进行了充分考量。例如，在处理吉客云分页返回的大量订单时，设置了合理的抓取频率和限流控制；对于网络波动引发的偶发错误，则部署了重试机制以保证任务稳定运行。而集中监控和告警系统则能实时跟踪各个任务状态，一旦出现异常情况会立即通知相关人员进行处理，从而保障整个过程顺畅无阻。
通过这种方式，不仅实现了两套系统间平稳、高效的数据交换，也极大提升了业务透明度，帮助企业掌握整体运营动态。在后续章节中，将深入探讨具体配置步骤及其技术细节。
### 调用源系统吉客云接口erp.storage.goodsdocin.v2获取并加工数据
在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用吉客云的`erp.storage.goodsdocin.v2`接口，并对获取的数据进行初步加工。
#### 接口调用配置
首先，我们需要配置元数据以便正确调用吉客云的接口。以下是元数据配置的关键参数：
- **api**: `erp.storage.goodsdocin.v2`
- **effect**: `QUERY`
- **method**: `POST`
- **number**: `goodsdocNo`
- **id**: `goodsdocNo`
- **idCheck**: `true`
这些参数定义了我们要调用的API名称、操作类型（查询）、请求方法（POST），以及用于标识记录的字段（`goodsdocNo`）。
#### 请求参数
在请求体中，我们需要传递以下字段：
1. **pageIndex**: 分页页码
2. **pageSize**: 分页页数，默认值为50
3. **startDate**: 创建时间的起始时间，使用占位符`{{LAST_SYNC_TIME|datetime}}`表示上次同步时间
4. **endDate**: 创建时间的结束时间，使用占位符`{{CURRENT_TIME|datetime}}`表示当前时间
5. **selelctFields**: 返回字段列表，包括多个字段如`goodsdocNo`, `inOutDate`, `gmtCreate`, 等等
6. **inouttype**: 入库类型，默认值为101
7. **vendCode**: 往来供应商
以下是请求参数的JSON格式示例：
```json
{
"pageIndex": "1",
"pageSize": "50",
"startDate": "{{LAST_SYNC_TIME|datetime}}",
"endDate": "{{CURRENT_TIME|datetime}}",
"selelctFields": "goodsdocNo,inOutDate,gmtCreate,inouttype,vendCustomerCode,warehouseCode,redStatus,financeBillStatus,goodsDocDetailList.goodsNo,goodsDocDetailList.estCost,goodsDocDetailList.quantity,goodsDocDetailList.transHasTaxPrice",
"inouttype": "101",
"vendCode": ""
}
```
#### 数据清洗与加工
在成功获取数据后，需要对数据进行清洗和初步加工。轻易云平台提供了自动填充响应（autoFillResponse）功能，可以简化这一过程。
例如，对于返回的数据，我们可以自动填充到目标数据库中，同时确保数据的一致性和完整性。具体操作包括：
1. **字段映射与转换**：将API返回的数据字段映射到目标系统中的相应字段，并进行必要的类型转换。
2. **异常处理与重试机制**：如果某些记录由于网络或其他原因未能成功写入，可以通过配置定时任务（crontab）来定期重试。例如，设置每天凌晨2点重试：
```json
{
"crontab": "1 2 * * *",
"takeOverRequest": [
{
"field": "startDate",
"value": "_function FROM_UNIXTIME( unix_timestamp() -259200 , '%Y-%m-%d %H:%i:%s' )"
}
]
}
```
#### 实践案例
假设我们需要从吉客云获取过去三天内所有采购入库单的数据，并将其写入我们的目标数据库。我们可以按照以下步骤进行操作：
1. 配置元数据，如上所述。
2. 调用API并获取数据。
3. 对返回的数据进行清洗和转换。
4. 将清洗后的数据写入目标数据库。
通过上述步骤，我们可以实现不同系统间的数据无缝对接，并确保数据的一致性和完整性。这不仅提升了业务透明度，还极大地提高了工作效率。
以上就是关于如何调用吉客云接口并对数据进行初步加工的技术案例，希望能为您的实际操作提供参考和帮助。
### 轻易云数据集成平台：ETL转换与金蝶云星辰V2API接口对接
在数据集成生命周期的第二步，关键任务是将已经集成的源平台数据进行ETL（提取、转换、加载）转换，并转为目标平台金蝶云星辰V2 API接口所能够接收的格式，最终写入目标平台。本文将深入探讨这一过程中的技术细节和实现方法。
#### 数据请求与清洗
在ETL流程中，首先需要从源系统（如吉客云）提取数据，并进行必要的清洗操作。假设我们已经完成了这一阶段，接下来重点关注如何将这些清洗后的数据转换为金蝶云星辰V2 API接口所需的格式。
#### 数据转换与写入
为了将数据成功写入金蝶云星辰V2，我们需要根据其API规范进行相应的数据格式转换。以下是具体的元数据配置：
```json
{
"api": "/jdy/v2/scm/pur_inbound",
"effect": "EXECUTE",
"method": "POST",
"number": "1",
"id": "1",
"name": "1",
"idCheck": true,
"request": [
{"field":"bill_date","label":"单据日期","type":"string","describe":"单据日期","value":"{inOutDate}"},
{"field":"bill_no","label":"单据编码","type":"string","describe":"单据编码","value":"{goodsdocNo}"},
{"field":"trans_type","label":"业务类型","type":"string","describe":"业务类型,1：限购，2：赊购，3：直运采购，4：受托入库","value":"1"},
{"field":"supplier_number","label":"供应商编码","type":"string","describe":"供应商编码","value":"{vendCustomerCode}"},
{"field":"operation_key","label":"操作类型","type":"string","describe":"操作类型，审核audit、提交submit","value":"audit"},
{
"field": "material_entity",
"label": "商品分录",
"type": "array",
"describe": "含税单价",
"value": "goodsDocDetailList",
"children": [
{"field":"material_number","label":"商品编码","type":"string","describe":"商品编码","value":"{{goodsDocDetailList.goodsNo}}"},
{"field":"stock_number","label":"仓库编码","type":"string","describe":"仓库编码","value":"{warehouseCode}"},
{"field":"qty","label":"数量","type":"string","describe":"数量","value":"{{goodsDocDetailList.quantity}}"},
{"field": "unit_id",
"label": "单位",
"type": "string",
"describe": "单位",
"value": "_findCollection find base_unit_id from 1be42e4a-5207-3c1d-8d49-1c7e49f90732 where number={{goodsDocDetailList.goodsNo}}"
},
{"field": "tax_price",
"label": "含税单价",
"type": "string",
"describe": "含税单价",
"value": "{{goodsDocDetailList.transHasTaxPrice}}"
},
{"field": "cess",
"label": "税率",
"type": "string",
"describe": "税率",
"value": 13
},
{"field":
is_free,
label: 是否赠品,
type: int,
describe: 是否赠品,
value: "_function case '{{goodsDocDetailList.transHasTaxPrice}}' when '0' then 'true' else 'false' end"
}
]
}
]
}
```
#### 配置解析与应用
1. **基础字段映射**：
- `bill_date` 映射到 `{inOutDate}`。
- `bill_no` 映射到 `{goodsdocNo}`。
- `trans_type` 固定值为 `1`（限购）。
- `supplier_number` 映射到 `{vendCustomerCode}`。
- `operation_key` 固定值为 `audit`（审核）。
2. **复杂字段处理**：
- `material_entity` 是一个数组字段，需要映射多个子字段，包括商品编码、仓库编码、数量、单位、含税单价、税率和是否赠品等。
- 商品编码映射到 `{{goodsDocDetailList.goodsNo}}`。
- 仓库编码映射到 `{warehouseCode}`。
- 数量映射到 `{{goodsDocDetailList.quantity}}`。
- 单位通过 `_findCollection` 方法查找对应的单位ID。
- 含税单价映射到 `{{goodsDocDetailList.transHasTaxPrice}}`。
- 税率固定值为 `13%`。
- 是否赠品通过 `_function case '{{goodsDocDetailList.transHasTaxPrice}}' when '0' then 'true' else 'false' end` 判断。
#### 接口调用
配置完成后，通过POST请求将转换后的数据发送至金蝶云星辰V2 API接口 `/jdy/v2/scm/pur_inbound`。确保请求体符合API要求，并包含所有必要字段。
```http
POST /jdy/v2/scm/pur_inbound HTTP/1.1
Host: api.kingdee.com
Content-Type: application/json
Authorization: Bearer <access_token>
{
...
}
```
#### 实时监控与异常处理
在数据写入过程中，实时监控请求状态和响应结果非常重要。如果出现异常情况（如网络错误或API返回错误信息），需要及时记录日志并进行相应处理，以确保数据一致性和完整性。
通过以上步骤，我们实现了从吉客云采购入库单到金蝶云星辰V2的无缝数据对接。这不仅提高了业务流程的自动化程度，还确保了数据传输的准确性和及时性。
