三单匹配反馈详细说明

一、概述

三单匹配任务支持 4 种反馈类型，每种类型的 taskData 结构不同：

反馈类型	说明	是否需要 taskId	taskData 是否为空
ACCEPT	用户接受算法结果	✅ 必须	✅ 可为空
ABANDON	用户放弃算法结果	✅ 必须	✅ 可为空
MODIFY	用户修改算法结果	✅ 必须	❌ 需要传数据
MANUAL	用户未调用算法，手动匹配	❌ 不需要	❌ 需要传数据

二、场景1：ACCEPT（接受算法结果）

使用场景

用户查看算法匹配结果后，认为结果正确，直接采用，无需修改。

请求参数
以下是转换后的 Markdown 表格：

参数	值	说明
taskType	"three_way_match"	固定值
feedbackType	"ACCEPT"	固定值
clientId	客户ID	必填
taskId	匹配接口返回的任务ID	必填，用于关联原始任务
taskData	{}	空对象或不传即可

完整示例

  {
      "taskType": "three_way_match",
      "feedbackType": "ACCEPT",
      "clientId": "client_123",
      "taskId": "8a99a18a3ca66a8fb332c66130b09f44"
  }

返回示例

  {
    "errcode": "0000",
    "description": "Success",
    "traceId": "f83d76a391634567853ebe1105a26adf",
    "data": null
  }

注意事项

taskId 必须是从匹配异步提交接口返回的有效任务ID

taskData 传空对象或不传即可，不需要传递具体数据

三、场景2：ABANDON（放弃算法结果）

使用场景

用户查看算法匹配结果后，认为结果不符合预期，放弃使用算法结果。

请求参数

参数	值	说明
taskType	"three_way_match"	固定值
feedbackType	"ABANDON"	固定值
clientId	客户ID	必填
taskId	匹配接口返回的任务ID	必填，用于关联原始任务
taskData	{}	空对象或不传即可

完整示例

  {
      "taskType": "three_way_match",
      "feedbackType": "ABANDON",
      "clientId": "client_123",
      "taskId": "8a99a18a3ca66a8fb332c66130b09f44"
  }

返回示例

  {
    "errcode": "0000",
    "description": "Success",
    "traceId": "f83d76a391634567853ebe1105a26adf",
    "data": null
  }

注意事项

放弃操作会删除反馈系统中对应的记录

taskData 传空对象或不传即可

四、场景3：MODIFY（修改算法结果）

使用场景

用户在算法匹配结果的基础上进行了修改（如调整匹配关系、引入新的入库单等），然后采用
改后的结果。

taskData 字段说明

userResult（list）- 必填

用户最终确认的匹配结果。

结构：

[
    {
        "targetItemId": "invoice_item_001",
        "candidateItem": [
            {
                "candidateDocId": "receipt_doc_001",
                "candidateItemId": "receipt_item_001"
            },
            {
                "candidateDocId": "receipt_doc_001",
                "candidateItemId": "receipt_item_002"
            }
        ]
    }
]

匹配关系列表字段说明：

一条发票明细可以匹配多条入库单明细

如果某条发票明细没有匹配到任何入库单，candidateItem 传空数组；但如果全部发票明细都没有匹配任何入库单明细，则直接传空数组

────────────────────────────────────────
字段: targetItemId
类型: string
说明: 发票明细ID（对应发票文件中的 item_id）
────────────────────────────────────────
字段: candidateItem
类型: array[object]
说明: 发票明细ID对应的入库单明细列表
────────────────────────────────────────
字段: candidateDocId
类型: string
说明: 入库单ID（对应入库单文件中的 doc_id）
────────────────────────────────────────
字段: candidateItemId
类型: string
说明: 入库单明细ID（对应入库单文件中的 item_id）

extraCandidateUrl（string）- 可选

额外入库单文件的 URL 地址。

何时需要传：

用户引入了原任务没有的入库单明细时需要传

建议做法：

业务端可直接将 userResult
中涉及的入库单的完整明细数据（包含该入库单的所有明细行）组成 CSV 文件传入

无需判断是否有新入库单，算法侧会自动处理

文件格式：

CSV 格式，UTF-8 编码

字段结构与匹配接口的 candidateUrl 一致

⚠️ 重要：

需要传该入库单的所有明细行，而不仅仅是被匹配的明细行

例如：userResult
中用到了入库单A的第2、5行，但需要传入入库单A的所有明细行（1-10行）

extraTargetUrl（string）- 可选

额外发票文件URL 地址。

何时需要传：

用户修改了原任务的发票数据时需要传

文件格式：

CSV 格式，UTF-8 编码

字段结构与匹配接口的 targetUrl 一致

完整示例1：仅调整匹配关系

用户只在原入库单范围内调整了匹配关系，没有引入新入库单。

{
    "taskType": "three_way_match",
    "feedbackType": "MODIFY",
    "clientId": "client_123",
    "taskId": "8a99a18a3ca66a8fb332c66130b09f44",
    "taskData": {
        "userResult": [
            {
                "targetItemId": "invoice_item_001",
                "candidateItem": [
                    {"candidateDocId": "receipt_doc_001", "candidateItemId": "receipt_item_001"},
                    {"candidateDocId": "receipt_doc_001", "candidateItemId": "receipt_item_002"}
                ]
            },
            {
                "targetItemId": "invoice_item_002",
                "candidateItem": [
                    {"candidateDocId": "receipt_doc_002", "candidateItemId": "receipt_item_003"}
                ]
            }
        ]
    }
}

完整示例2：引入新入库单

用户引入了原任务没有的入库单明细。

{
    "taskType": "three_way_match",
    "feedbackType": "MODIFY",
    "clientId": "client_123",
    "taskId": "8a99a18a3ca66a8fb332c66130b09f44",
    "taskData": {
        "userResult": [
            {
                "targetItemId": "invoice_item_001",
                "candidateItem": [
                    {"candidateDocId": "receipt_doc_003", "candidateItemId": "receipt_item_005"}
                ]
            }
        ],
        "extraCandidateUrl": "https://example.com/additional_receipts.csv"
    }
}

完整示例3：修改了发票数据

用户修改了原任务的发票明细。

{
    "taskType": "three_way_match",
    "feedbackType": "MODIFY",
    "clientId": "client_123",
    "taskId": "8a99a18a3ca66a8fb332c66130b09f44",
    "taskData": {
        "userResult": [
            {
                "targetItemId": "invoice_item_001",
                "candidateItem": [
                    {"candidateDocId": "receipt_doc_001", "candidateItemId": "receipt_item_001"}
                ]
            }
        ],
        "extraTargetUrl": "https://example.com/updated_invoice.csv"
    }
}

返回示例

  {
    "errcode": "0000",
    "description": "Success",
    "traceId": "f83d76a391634567853ebe1105a26adf",
    "data": null
  }

注意事项

userResult 必填：必须传入用户最终确认的匹配结果

extraCandidateUrl 的使用：

如果不确定是否有新入库单，建议直接传入

传入时需要包含完整的入库单数据（所有明细行）

五、场景4：MANUAL（人工手动匹配）

使用场景

用户没有调用算法匹配接口，直接进行手动匹配。这种情况下没有
taskId，需要提供完整的原始数据。

taskData 字段说明

supplierId（string）- 必填

供应商ID，用于标识本次匹配涉及的供应商。

targetUrl（string）- 必填

发票文件的 url 地址。

文件格式：

CSV 格式，UTF-8 编码

字段结构与匹配接口的 targetUrl 一致

必须包含 doc_id 字段（发票唯一标识）

candidateUrl（string）- 必填

入库单文件的 url 地址。

文件格式：

CSV 格式，UTF-8 编码

字段结构与匹配接口的 candidateUrl 一致

settings（object）- 可选

动态配置项，用于记录用户手动匹配时使用的配置。

格式：与匹配接口的 settings 参数一致，例如：

  {
      "priceTolerance": 0.05,
      "priceToleranceType": "0",
      "quantityTolerance": 1.0,
      "quantityToleranceType": "1",
      "amountTolerance": 0.02,
      "amountToleranceType": "0",
      "matchMode": "2"
  }

userResult（list）- 必填

用户手动匹配的结果。

结构：与 MODIFY 场景中的 userResult 一致。

完整示例

{
    "taskType": "three_way_match",
    "feedbackType": "MANUAL",
    "clientId": "client_123",
    "taskData": {
        "supplierId": "supplier_456",
        "targetUrl": "https://example.com/invoice.csv",
        "candidateUrl": "https://example.com/receipts.csv",
        "settings": {
            "priceTolerance": 0.05,
            "priceToleranceType": "0"
        },
        "userResult": [
            {
                "targetItemId": "invoice_item_001",
                "candidateItem": [
                    {"candidateDocId": "receipt_doc_001", "candidateItemId": "receipt_item_001"}
                ]
            }
        ]
    }
}

返回示例

  {
    "errcode": "0000",
    "description": "Success",
    "traceId": "f83d76a391634567853ebe1105a26adf",
    "data": null
  }

注意事项

不需要 taskId：因为用户没有调用过匹配接口，所以不需要传 taskId

必须提供完整数据：需要提供 supplierId、targetUrl、candidateUrl、userResult

settings 可选：如果不确定用户使用的配置，可以不传

文件格式要求：targetUrl 和 candidateUrl 指向的文件必须符合匹配接口的格式要求

六、常见问题

Q1: taskId 不存在或已过期怎么办？

错误返回：

{
    "errcode": "2001",
    "description": "Invalid Parameter 'taskId' - Invalid or expired taskId.",
    "traceId": "f83d76a391634567853ebe1105a26adf",
    "data": null
}

原因：

taskId 输入错误

该任务没有启用反馈

任务超过 1 个月未反馈，已被自动清理

该任务已经反馈过了，不能重复反馈

解决方法：

检查 taskId 是否正确

如果任务已过期，需要重新调用匹配接口

Q2: MODIFY 场景下，extraCandidateUrl 什么时候需要传？

需要传的情况：

用户引入了原任务没有的入库单明细

建议做法：

如果不确定是否有新入库单，可以直接传

将 userResult 中涉及的所有入库单的完整明细数据组成 CSV 文件传入

算法侧会自动判断哪些是新入库单

Q3: extraCandidateUrl 中需要传哪些数据？

正确做法：

传入 userResult 中涉及的入库单的所有明细行

例如：userResult
中用到了入库单A的第2、5行，但需要传入入库单A的所有明细行（1-10行）

错误做法：

❌ 只传被匹配的明细行（不完整）

Q4: 如何判断反馈是否提交成功？

判断标准：

errcode = "0000" 表示成功

errcode != "0000" 表示失败，查看 description 了解失败原因

七、数据保留策略

任务数据保留期：

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

因此建议尽早提交反馈

中间数据保留期：

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

一、概述#

二、场景1：ACCEPT（接受算法结果）#

三、场景2：ABANDON（放弃算法结果）#

四、场景3：MODIFY（修改算法结果）#

五、场景4：MANUAL（人工手动匹配）#

六、常见问题#

一、概述

二、场景1：ACCEPT（接受算法结果）

三、场景2：ABANDON（放弃算法结果）

四、场景3：MODIFY（修改算法结果）

五、场景4：MANUAL（人工手动匹配）

六、常见问题