三单匹配-normal 正常匹配场景
normal：正常匹配场景
requestScene="normal"；省略场景参数也按 normal 处理。正常使用场景为高优，可按需启用反馈。以下为本场景完整的对外字段及规则。一、接口描述
1.
2.
3.
4.
requestScene=normal 且 enableFeedback=true 时，才会保存可用于反馈的匹配任务数据，业务系统需保存返回的 taskId 用于后续反馈。requestScene=init 不建立反馈 task；异步提交返回的 taskId 仍可用于查询匹配结果，但不能作为反馈来源 task ID 。5.
二、输入参数
clientId（string）：客户ID，用于多租户隔离。必填字段。supplierId（string）：供应 商ID。必填字段，单次任务仅涉及一个供应商。enableFeedback（bool）：是否启用反馈机制。选填字段，默认 false。仅 requestScene=normal 时生效；requestScene=init 时即使传 true 也按 false 执行，不建立反馈 task。useVectorStore（bool）：是否使用向量库，默认为 false，主要用于兼容改造前的接口，业务方改造完成后，该字段会去掉。requestScene（string）：请求场景标识。normal 代表正常使用场景（高优，可启用反馈），init 代表初始化场景（低优，不启用反馈）。不传默认按 normal 处理。targetUrl： 发票明细文件（CSV 格式，UTF-8 编码， 明细数量不能超过5000条）的url地址。文件格式如下：文件中的每一行表示一条发票明细记录，字段说明如下：
doc_id（string）：发票的唯一标识。必填字段（⚠️ 【重要】同一张发票的 doc_id 必须始终一致，不能因为换了任务就改变。）item_id（string）：发票明细的唯一标识。每条记录必须提供该字段，且不能重复。（⚠️ 同一条明细的 item_id 必须始终一致，不能因为换了任务就改变。）product_name（string）：商品名称。必 填字段specification_model（string）：规格型号，可为空。unit（string）：单位，可为空。quantity（float）：本次可参与匹配的数量，可为空（根据匹配模式决定是否必填）。unit_price（float）：本次参与匹配的单价，可为空。amount（float）：本次可参与匹配的金额，可为空（根据匹配模式决定是否必填）。business_time（string）：业务时间，格式 yyyy-mm-dd（如 2024-03-15），可为空。tax_rate（float）：税率，小数表示（如 0.13 表示 13%），可为空。当 matchMode = "0"（金额优先匹配）时，必须填写amount字段。当 matchMode = "1"（数量优先匹配）时，必须填写quantity字段。当 matchMode = "2"（金额和数量同时匹配）时， 必须填写amount和quantity字段 。当 matchMode = "3"（金额或数量自适应匹配）时，amount和quantity字段 至少填写一项。
📌 注意：若缺失任何必填字段（如 doc_id、item_id、product_name，或匹配模式要求的amount/quantity），系统将直接报错，无法继续处理。因此请确保所有必填字段完整且符合格式要求。
candidateUrl： 候选单据明细文件（CSV 格式，UTF-8 编码）的url地址。文件格式如下：每一行表示一张单据中的一条明细记录，字段说明如下：
item_id（string）：单据明细的唯一标识。必填且不可重复，通常建议格式为 {单据单号}_{单据行号}，例如 {入库单号}_{入库单行号}。（⚠️ 同一条明细的 item_id 必须始终一致，不能因为换了任务就改变。）doc_id（string）：该明细所属单据的唯一标识（即单据单号）。必填字段（⚠️ 【重要】同一张入库单的 doc_id 必须始终一致，不能因为换了任务就改变。）product_code（string）：商品/物料编码，商品的唯一标识。（根据初始化配置决定是否必填）product_name（string）：商品名称 / 物料名称 / 描述。必填字段specification_model（string）：规格型号，可为空。unit（string）：单位，可为空。quantity（float）：本次可参与匹配的数量（接收数量 / 入库数量），可为空（根据匹配模式决定是否必填）。unit_price（float）：本次参与匹配的单价，可为空。amount（float）：本次可参与匹配的明细金额，可为空（根据匹配模式决定是否必填）。business_time（string）：业务时间，格式 yyyy-mm-dd（如 2024-03-15），可为空。tax_rate（float）：税率，小数表示（如 0.13 表示 13%），可为空。priority（int）：入库明细优先级，取值 >= 1 的整数，越小越优先。priorityStrategy="PRIORITY" 时必填且每条明细都要有值（任一条缺失或非法即报参数错误）；⚠️ 字段要求说明（根据匹配模式 matchMode而定）：当 matchMode = "0"（金额优先匹配）时，必须填写amount字段。当 matchMode = "1"（数量优先匹配）时，必须填写quantity字段。当 matchMode = "2"（金额和数量同时匹配）时，必须同时填写amount和quantity字段。当 matchMode = "3"（金额或数量自适应匹配）时，amount和quantity字段 字段至少有一项。
📌 注意：若某条明细缺失必填字段（如 item_id、doc_id、product_name，或匹配模式要求的amount/quantity），系统将自动过滤该条记录，不参与后续匹配。
settings: 动态配置项, 此动态配置项通过传入 字典 的方式来配置不同的容差参数和匹配模式,后续新增配置可以直接在该参数中新增。所有配置项为选填项，用户可以选择传入或不传入。如果没有传入配置项，则会使用默认值。以下是每个配置项的详细说明和要求：配置项说明：
matchDetails 中只包含匹配成功的明细，未匹配的明细不返回。priority 列决定核销次序，取值小的入库单明细先被核销；该列必填且每条明细都要有值false。unit 列（可选列）。三、主要输出参数
四、FAQ
1.
"2" 与 "3" 的区别 ?"2" 数量+金额 | "3" 金额或数量（按行自适应） | |
|---|---|---|
| 列存在性要求 | quantity 和 amount 两列都必须存在 | 两列至少存在一列 |
| 某行只有一维有值 | 返回参数错误，请求失败 | 该行按存在的那一维校验，继续匹配 |
| 某行两维都为空 | 返回参数错误，请求失败 | 返回参数错误，请求失败 |
| 校验维度 | 恒定双维 | 逐行自适应 |
"3" 的逐行规则："2"）；"0"）；"1"）。quantity 值的入库单明细不会成为它的候选。matchMode="2"：第 2、3 行缺维度，直接返回参数错误，整个请求失败；matchMode="3"：第 1 行按数量+金额校验，第 2 行按金额校验，第 3 行按数量校验，三行均正常参与匹配。五、异步提交示例
{
"clientId": "client_001",
"supplierId": "supplier_001",
"requestScene": "normal",
"enableFeedback": true,
"useVectorStore": false,
"targetUrl": "https://file.example.com/invoice.csv",
"candidateUrl": "https://file.example.com/candidates.csv",
"settings": {
"matchMode": "0",
"matchRelation": "ONE_TO_MANY",
"returnMode": "WHOLE"
}
}data.taskId 调用异步匹配结果查询接口。仅本场景启用反馈后，任务 ID 才可作为后续反馈来源。修改于 2026-10-15 03:28:31