三单匹配-异步匹配任务提交

一、接口描述

解决发票和单据（比如入库单）匹配问题，输入发票信息和候选单据信息，输出发票每条明细匹配的单据明细

支持一张发票匹配多张单据；

仅支持一条发票明细匹配多条单据明细，不支持一条单据明细匹配多条发票明细的情况；

发票或入库单的金额、单价、数量字段若无值，应保持为空，不得转化为0；

当初始化配置项 use_product_code 设为 false 时，入库单的物料编码为非必填项；

若启用了向量库功能，在切换 use_product_code 配置时，需清空向量库中的数据以保证一致性。

【新增】反馈机制支持：接口支持反馈机制，调用时会保存任务输入、匹配结果和taskId到数据库，业务系统需保存返回的taskId用于后续反馈。

【新增】数据保留策略：

超过1个月未收到反馈的任务，将自动删除任务数据

超过10天删除冗余中间数据

私有化部署注意事项：

建议在私有化部署时同步部署 Milvus 向量数据库，并在初始化阶段提供完整的物料库数据（CSV 文件，包含单据上可能出现的所有物料）。物料库数据应至少包含以下字段：

product_code：商品编码 / 物料编码

product_name：物料名称，必填字段

specification_model：规格型号

client_id：租户标识。必填字段

supplier_id：供应商id。必填字段

虽然系统可在无初始数据的情况下正常部署，但此时所有向量计算将采用实时生成方式，可能导致接口响应时间较长。提供物料库数据后，系统可在初始化时预生成向量索引，从而显著提升后续接口调用的性能和响应速度。

二、输入参数

【新增】1. clientId（string）：客户ID，用于多租户隔离。必填字段。

【新增】2. supplierId（string）：供应商ID。必填字段，单次任务仅涉及一个供应商。

【新增】3. enableFeedback（bool）：是否启用反馈机制。选填字段，默认 false。

【新增】4. useVectorStore（bool）：是否使用向量库，默认为 false，主要用于兼容改造前的接口，业务方改造完成后，该字段会去掉。

【新增】4. requestScene（string）：请求场景标识。normal 代表正常使用场景（高优），init 代表初始化场景（低优）。不传默认按 normal 处理。

6. targetUrl： 发票明细文件（CSV 格式，UTF-8 编码）的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）：不含税金额，可为空（根据匹配模式决定是否必填）。

⚠️ 字段要求说明（根据匹配模式 matchMode 而定）：
当 matchMode = "0"（金额优先匹配）时，必须填写 amount 字段。
当 matchMode = "1"（数量优先匹配）时，必须填写 quantity 字段。
当 matchMode = "2"（金额和数量同时匹配）时，必须同时填写 amount 和 quantity 字段。

📌 注意：若缺失任何必填字段（如 doc_id、item_id、product_name，或匹配模式要求的 amount / quantity），系统将直接报错，无法继续处理。因此请确保所有必填字段完整且符合格式要求。

7. 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）：明细金额，可为空（根据匹配模式决定是否必填）。

⚠️ 字段要求说明（根据匹配模式 matchMode 而定）：
当 matchMode = "0"（金额优先匹配）时，必须填写 amount 字段。
当 matchMode = "1"（数量优先匹配）时，必须填写 quantity 字段。
当 matchMode = "2"（金额和数量同时匹配）时，必须同时填写 amount 和 quantity 字段。

📌 注意：若某条明细缺失必填字段（如 item_id、doc_id、product_name，或匹配模式要求的 amount / quantity），系统将自动过滤该条记录，不参与后续匹配。

8. settings: 动态配置项, 此动态配置项通过传入字典的方式来配置不同的容差参数和匹配模式,后续新增配置可以直接在该参数中新增。所有配置项为选填项，用户可以选择传入或不传入。如果没有传入配置项，则会使用默认值。以下是每个配置项的详细说明和要求：
配置项说明：

所有配置项均为选填项，可以选择传入也可以不传入。

如果不传入某些配置项，则会使用以下默认值：

matchMode 默认为 "0"（基于金额匹配）。

配置项具体描述

priceTolerance（单价容差）

类型: float

描述: 单价容差的值，表示允许的单价差异。

要求: 可选，若传入则必须和 priceToleranceType 一同传入，并且 priceTolerance 的值为非负数。

priceToleranceType（单价容差类型）

类型: string ("0" 或 "1")

描述: 单价容差的类型。

要求: 可选，若传入则必须和 priceTolerance 一同传入。并且值必须为：

"0": 容差以百分比表示。

"1": 容差以绝对值表示。

quantityTolerance（数量容差）

类型: float

描述: 数量容差的值，表示允许的数量差异。

要求: 可选，若传入则必须和 quantityToleranceType 一同传入，并且 quantityTolerance 的值为非负数。

quantityToleranceType（数量容差类型）

类型: string ("0" 或 "1")

描述: 数量容差的类型。

要求: 可选，若传入则必须和 quantityTolerance 一同传入，并且值必须为：

"0": 容差以百分比表示。

"1": 容差以绝对值表示。

amountTolerance（金额容差）

类型: float

描述: 金额容差的值，表示允许的金额差异。如果为 null，则金额容差将根据 priceTolerance 和 quantityTolerance 动态计算。

要求: 可选，若传入则必须和 amountToleranceType 一同传入，并且值为非负数。

amountToleranceType（金额容差类型）

类型: string ("0" 或 "1")

描述: 金额容差的类型。

要求: 可选，若传入则必须和 amountTolerance 一同传入，并且值必须为：

"0": 容差以百分比表示。

"1": 容差以绝对值表示。

matchMode（匹配模式）

类型: string ("0", "1", "2")

描述: 匹配时使用的策略。

要求: 可选，若传入则会覆盖默认值：

如果传入 matchMode，则必须为：

"0": 仅使用金额进行匹配。

"1": 仅使用数量进行匹配。

"2": 同时使用数量和金额进行匹配。

默认为 "0"。

三、主要输出参数

1.data: 输出异步任务id。可以根据这个id在查询接口查询结果。

application/json

Bodyapplication/json

示例

{
    "errcode": "0000",
    "description": "Success",
    "data": {
        "taskId": "8a99a18a3ca66a8fb332c66130b09f44"
    },
    "traceId": "f83d76a391634567853ebe1105a26adf"
}

一、接口描述

二、输入参数

三、主要输出参数

请求参数

请求示例代码

返回响应

三单匹配-异步匹配任务提交

一、接口描述#

二、输入参数#

三、主要输出参数#

请求参数

请求示例代码

返回响应

一、接口描述

二、输入参数

三、主要输出参数