三单匹配反馈详细说明

1. 接口信息

项目	内容
请求方式	POST
请求地址	/ai/knowledge/aiService/feedback
Content-Type	application/json
taskType	three_way_match

一次请求提交一张发票的反馈。请求中包含本次勾选确认的行，以及这张发票仍未勾选的算法来源行。已成功确认的行不必在下一次反馈中重复提交；请求失败后按第 7 节重试。

2. 请求参数

2.1 请求体

字段	类型	必填	说明
taskType	string	是	固定为 three_way_match
clientId	string	是	客户 ID
taskData	object	是	本次发票反馈数据
taskData.supplierId	string	是	供应商 ID
taskData.targetDocId	string	是	发票单据 ID；上报的发票行必须属于该单据
taskData.userResult	array	是	本次上报的发票明细，至少一条；targetItemId 不可重复
taskData.extraCandidateUrl	string	条件必填	有任意非空 candidateItem 时必传，见第 4 节
taskData.extraTargetUrl	string	条件必填	有 MANUAL 行时必传，见第 4 节
taskData.settings	object/null	否	用于 MANUAL 行；算法来源行使用原任务配置

2.2 userResult 元素

字段	类型	必填	说明
targetItemId	string	是	发票明细 ID
feedbackType	string/null	是	ACCEPT、MODIFY、MANUAL 或 JSON null，见第 3 节
sourceTaskId	string/null	是	算法来源行传当前页面展示的 task ID；MANUAL 传 JSON null
candidateItem	array	是	客户确认的完整匹配列表；未勾选传 []

sourceTaskId 仅表示本次展示来源。即使页面展示的算法结果为空，也要传对应 task ID。同一明细关联其他任务时，无须在请求中列出其他 task ID。服务端仅处理本次显式上报的 targetItemId，不根据 targetDocId 自动补充未上报行。

2.3 candidateItem 元素

字段	类型	必填	说明
candidateDocId	string	是	入库单 ID，与候选文件中的 doc_id 一致
candidateItemId	string	是	入库单明细 ID；同一发票行内不可重复
allocatedAmount	number	按匹配维度	分配金额
allocatedQuantity	number	按匹配维度	分配数量，使用入库单明细自身的单位

candidateItem 是客户已确认的完整匹配结果，不是页面当前展示列表。一个发票行对应多条入库单明细时，在同一个 candidateItem 中传完整列表，不要拆成多条 userResult。

3. feedbackType 取值

页面操作	feedbackType	sourceTaskId	candidateItem
勾选并接受系统的非空结果	ACCEPT	当前展示 task ID	完整非空确认列表
修改候选或分配额后勾选；或系统无结果、人工补出非空结果后勾选	MODIFY	当前展示 task ID	修改后的完整非空确认列表
未勾选：保留系统结果、编辑但未确认、清空结果、系统无结果	null	当前展示 task ID	[]
无算法来源的人工行，确认非空匹配	MANUAL	null	完整非空确认列表

未勾选时统一传 JSON null 和 []；这表示本次没有确认匹配，不表示确认空匹配。纯人工行尚无非空确认时不提交。ACCEPT、MODIFY、MANUAL 均须传非空 candidateItem；ACCEPT + []、MODIFY + []、null + 非空列表不合法。已确认的非空匹配不能通过 [] 撤销。

4. 补充文件与配置

字段	要求
extraCandidateUrl	只要任一行的 candidateItem 非空就必传。UTF-8 CSV 必须覆盖本次引用的全部 candidateItemId，每个 ID 一条完整明细；包括原池内、池外和已入库的候选。仅上报未勾选行时可省略。
extraTargetUrl	有 MANUAL 行时必传。UTF-8 CSV 必须覆盖本次全部 MANUAL targetItemId，且这些行的 doc_id 等于 targetDocId。
settings	与匹配主接口配置规则一致，仅作用于 MANUAL；不传、null 或 {} 使用默认配置，matchMode 默认字符串 "0"。显式非法配置会报错。

两个 CSV 的字段沿用匹配接口的 targetUrl/candidateUrl：item_id、doc_id、product_name、specification_model、unit、quantity、unit_price、amount；候选文件可包含 product_code。tax_rate、business_time 可选。文件可包含其他明细，但引用的每个 ID 都必须有完整明细。业务方无须判断候选是否已在数据库或某个任务的候选池中。

matchMode 的分配维度："0" 仅金额、"1" 仅数量、"2" 金额和数量、"3" 按发票行实际具备的维度。参与维度中，候选明细本身有该维度时须传对应 allocated 字段；不参与或候选明细缺少的维度可省略。数量按入库单明细的原生单位填写。

5. 请求示例

示例 ID 和文件地址仅用于说明字段关系；实际调用需提供可访问的 CSV。除 5.6 外，以下示例按金额模式填写分配额。

5.1 接受系统结果

系统从 task_001 为 A_1 展示 R_1，客户勾选。候选文件仍须包含 R_1。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_1", "feedbackType": "ACCEPT", "sourceTaskId": "task_001",
       "candidateItem": [{"candidateDocId": "receipt_1", "candidateItemId": "R_1", "allocatedAmount": 1200}]}
    ],
    "extraCandidateUrl": "https://files.example.com/receipt_R1.csv"
  }
}

5.2 修改后确认多条入库单明细

A_2 最终确认 R_2 和 R_3。candidateItem 传完整列表，候选文件同时覆盖 R_2、R_3。系统原本展示为空、客户补出非空结果时，也使用 MODIFY 并保留 sourceTaskId。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_2", "feedbackType": "MODIFY", "sourceTaskId": "task_002",
       "candidateItem": [
         {"candidateDocId": "receipt_2", "candidateItemId": "R_2", "allocatedAmount": 300},
         {"candidateDocId": "receipt_3", "candidateItemId": "R_3", "allocatedAmount": 200}
       ]}
    ],
    "extraCandidateUrl": "https://files.example.com/receipts_R2_R3.csv"
  }
}

5.3 未勾选

页面仍显示系统结果、编辑过但未勾选、清空结果或系统无结果，都按下面格式提交；无需 extraCandidateUrl。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_3", "feedbackType": null, "sourceTaskId": "task_003", "candidateItem": []}
    ]
  }
}

5.4 纯人工确认

A_4 无算法来源；发票文件覆盖 A_4，候选文件覆盖 R_4。省略 settings 时使用默认金额模式。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_4", "feedbackType": "MANUAL", "sourceTaskId": null,
       "candidateItem": [{"candidateDocId": "receipt_4", "candidateItemId": "R_4", "allocatedAmount": 100}]}
    ],
    "extraTargetUrl": "https://files.example.com/invoice_A_manual.csv",
    "extraCandidateUrl": "https://files.example.com/receipt_R4.csv"
  }
}

5.5 一张发票混合多种反馈

不同发票行可有不同 sourceTaskId，也可与 MANUAL 混合。候选文件覆盖 R_1、R_2、R_4；发票文件覆盖 A_4。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_1", "feedbackType": "ACCEPT", "sourceTaskId": "task_001",
       "candidateItem": [{"candidateDocId": "receipt_1", "candidateItemId": "R_1", "allocatedAmount": 1200}]},
      {"targetItemId": "A_2", "feedbackType": "MODIFY", "sourceTaskId": "task_002",
       "candidateItem": [{"candidateDocId": "receipt_2", "candidateItemId": "R_2", "allocatedAmount": 300}]},
      {"targetItemId": "A_3", "feedbackType": null, "sourceTaskId": "task_003", "candidateItem": []},
      {"targetItemId": "A_4", "feedbackType": "MANUAL", "sourceTaskId": null,
       "candidateItem": [{"candidateDocId": "receipt_4", "candidateItemId": "R_4", "allocatedAmount": 100}]}
    ],
    "extraTargetUrl": "https://files.example.com/invoice_A_manual.csv",
    "extraCandidateUrl": "https://files.example.com/receipts_R1_R2_R4.csv"
  }
}

5.6 MANUAL 使用金额和数量模式

若客户配置 matchMode 为 "2"，MANUAL 的分配金额和数量同时填写。配置仅用于 MANUAL 行。

{
  "taskType": "three_way_match",
  "clientId": "client_123",
  "taskData": {
    "supplierId": "supplier_456",
    "targetDocId": "invoice_A",
    "userResult": [
      {"targetItemId": "A_5", "feedbackType": "MANUAL", "sourceTaskId": null,
       "candidateItem": [{"candidateDocId": "receipt_5", "candidateItemId": "R_5",
                          "allocatedAmount": 260, "allocatedQuantity": 10}]}
    ],
    "extraTargetUrl": "https://files.example.com/invoice_A_manual.csv",
    "extraCandidateUrl": "https://files.example.com/receipt_R5.csv",
    "settings": {"matchMode": "2"}
  }
}

6. 返回结果

成功响应示例：

{"errcode":"0000","description":"Success"}

errcode	含义	处理建议
0000	请求处理成功	无须重试
2001	参数错误	根据错误描述修正请求
3000	服务处理失败	使用原请求重试

7. 幂等与重试

网络结果未知或返回 3000 时，调用方无法判断本次请求处理到了哪一步。请使用完整原请求重试，并保持补充文件的地址和内容不变。服务端会识别已保存的确认结果，继续处理尚未完成的任务；收到 0000 后，本次请求才算处理完成。

已确认发票行的重试按完整 candidateItemId 集合判断，顺序无关。集合相同可接受，但首次保存的分配额、feedbackType 和确认时间不会被重试内容覆盖；增加、删除、更换候选或改为空数组会被拒收。重试时仍须提供必需文件并满足字段校验。已确认的行不能通过本接口撤销或更正。

一张发票可关联多个任务，一个任务也可包含多张发票；每次仍按一张发票上报。仅上报本次发票的行，不要把其他发票的行并入同一请求。

1. 接口信息#

2. 请求参数#

2.1 请求体#

2.2 userResult 元素#

2.3 candidateItem 元素#

3. feedbackType 取值#

4. 补充文件与配置#

5. 请求示例#

5.1 接受系统结果#

5.2 修改后确认多条入库单明细#

5.3 未勾选#

5.4 纯人工确认#

5.5 一张发票混合多种反馈#

5.6 MANUAL 使用金额和数量模式#

6. 返回结果#

7. 幂等与重试#