在单据建模过程中，通常包含一个同步接口设置的Tab项目，该模块旨在实现与外部系统间的数据同步，确保业务流程的无缝衔接。以下是对该设置项的详细阐述：

1. 新增同步接口与管理页面

• 新增同步接口：用户点击相关按钮后，可以创建一个新的同步接口配置，定义其对接的具体功能和交互规则。
• 菜单管理（Sync/OutAPI/Index）：通过将管理页面添加至菜单中，用户可以便捷地访问和管理所有已配置的同步接口，便于监控、调试和维护。

同一个单据可以建多个API接口，系统会逐一调用。也可以针对单据中的不同数据设置调用条件。

2. 设置页面与同步内容搭建

点击新增或编辑后，用户将进入设置页面，该页面用于详细设定同步接口的各项参数及逻辑：

接口名称

• 用户可自由定义接口名称，但建议采用具有明确意义的词汇，以便于后期快速识别、查找和编辑。

动作内容

• 保存前：在本系统将单据数据存入数据库之前调用接口。若接口调用出现异常，系统将抛出异常并可能阻止后续数据保存操作。
• 保存后：在本系统完成单据数据入库后调用接口。即使接口调用发生异常，本系统的数据操作已完毕，异常仅作为提示，不影响系统内部状态。
• 删除前与删除后：同理，分别在执行单据删除操作前、后触发接口调用，根据动作时刻的不同，对异常处理策略有所区分。

单据分类与名称

• 指定接口调用所对应的单据类别和名称，确保接口能够准确对接到目标业务数据。

前置条件

• 通过设置基于主表字段的条件表达式（如BillExt=='出口'），控制在满足特定条件时才调用此接口。字符串常量需使用英文单引号包围。

URL信息

• 提交方式：选择接口所需的HTTP方法，如POST、GET、PUT等。
• 接口地址：填入第三方系统提供的接口URL，作为数据交换的目标地址。

Body格式

支持以下三种提交格式：

• application/json：将Body内容组装成JSON格式提交，广泛应用于现代API设计中。
• application/x-www-form-urlencoded：将Body内容以标准的URL-encoded形式编码成键值对，适用于传统表单提交场景。
• multipart/form-data：适用于类似文件上传等场景，允许额外指定参数名，将Body内容封装为“参数名: json”格式提交。

Body类型

• List：将Body内容包裹在JSON数组中。
• Object：直接将Body内容组装成JSON对象。选择何种类型应遵循第三方接口的数据结构要求。

Headers

• 用于在请求头中添加必要的参数，如AccessKey、SecretKey等认证信息，确保接口调用的合法性与安全性。

Body内容

• 根据第三方接口参数需求设置。对于涉及单据子表的内容，使用特定字段标识（如sub），系统会自动处理成相应的数据结构。可以点击“本地字段/值”旁边的问号打开对照表，这有助于用户正确填写本地字段与值。
• 在请求体（Body）中实现了一个特殊机制，该机制规定：任何字段名以“_*”为前缀的属性（包括其子节点），将不会被包含在向服务器提交的数据之中。这一设计旨在为开发者提供一个便捷的途径来存储临时变量或中间计算结果，而无需担心这些数据会被无意中上传至服务器，从而保证了数据的纯净性和传输效率。

单据可用的字段可以在行上右键查找。

字段格式化

格式化功能涵盖多个领域，包括日期、数字和字符串操作：

日期格式化：

• 年份：使用yyyy（四位数，如2019）或yy（两位数，如19）
• 月份：MM（两位数，如01-12）或M（一位数或两位数，如1-12）
• 日：dd（两位数，如01-31）或d（一位数或两位数，如1-31）
• 24小时制小时：HH（两位数，如00-23）或H（一位数或两位数，如0-23）
• 12小时制小时：hh（两位数，如01-12）或h（一位数或12，如1-12）
• 分钟：mm（两位数，如00-59）或m（一位数或两位数，如0-59）
• 秒：ss（两位数，如00-59）或s（一位数或两位数，如0-59）
• 毫秒：fff

数字格式化：

• 零占位符：0
• 数字占位符：#
• 小数点：. 用于分隔整数和小数部分
• 组分隔符：, 用于分隔数字中的千位
• 比例换算：可以结合小数点和数字占位符来设置精度和小数部分
• 百分比：% 用于表示百分比
• 千分比：‰ 用于表示千分比

字符串操作：

• 哈希算法：支持md5、SHA1、SHA256、SHA384和SHA512，指定算法名称即可，大写表示输出结果为大写
• Base64编码：将字符串转换为Base64格式的字符串

详情可以参阅格式化的字段说明，具体用法以页面中的说明为准。

3. Response设置与结果处理

内容格式

• 指定接口返回数据是JSON对象还是JSON数组，以便系统正确解析响应。

状态字段

• 填写返回对象中用于标识接口操作成功与否的字段全路径。当实际返回值与此字段的预设成功状态相符时，认为接口调用成功；否则视为失败。

错误消息字段

• 若接口无明确状态字段，可选使用错误消息字段作为调用成功与否的依据。当返回JSON对象中该字段非空时，视为接口调用失败。

异常处理

• 抛出异常：在接口调用失败时，系统弹出错误信息。对于操作前的接口，异常将阻止本系统写入数据库；操作后的接口则仅提示异常，此时数据库操作已完成。
• 不做处理：仅记录调用日志，无论接口调用成功与否，系统均不显示异常，数据操作按原计划进行。

单号字段与消息字段

• 系统将接口返回的指定字段值（如单号、消息）写入单据主表相应字段，实现数据回填与状态同步。

注意事项

状态字段和错误消息字段二选一，至少填写一个，否则系统无法判断调用结果。如实不需要系统关注调用结果也可以不填，并将失败时设置为不做处理。

所有返回内容字段名称必须填写完整的路径名称，确保系统能准确提取所需数据。错误的配置可能导致接口报错！

如果返回的格式有列表，请在路径中指定列表行索引。例如返回格式是：

{
    "Status": 0,
    "Data": {
        "id": 1,
        "code": "SH20200021",
        "description": "test",
        "created_at": "2021-01-01 00:00:00",
        "updated_at": "2021-01-01 00:00:00",
        "deleted_at": null
    }
}

要获取单号则路径应该写成：Data.code，状态字段是：Status。

如果是：

{
    "Status": 0,
    "Data": [{
        "id": 1,
        "code": "SH20200021",
        "description": "test",
        "created_at": "2021-01-01 00:00:00",
        "updated_at": "2021-01-01 00:00:00",
        "deleted_at": null
    }]
}

要获取单号则路径是：Data.0.code，状态字段是：Status。

如果是：

[{
    "Status": 0,
    "Data": [{
        "id": 1,
        "code": "SH20200021",
        "description": "test",
        "created_at": "2021-01-01 00:00:00",
        "updated_at": "2021-01-01 00:00:00",
        "deleted_at": null
    }]
}]

要获取单号路径则是：0.Data.0.code，状态字段是：0.Status。

4. 执行日志记录

您可以在同步接口列表中查看执行记录，这有助于调试接口信息。