发票云（智能特性）
旗舰版标准版智能特性
旗舰版标准版智能特性
🤖 AI Support​​
  1. 三单匹配
  • 整体介绍
  • 开发指南
  • 授权
    • token获取
      POST
  • 智能特性
    • 文档信息识别
      • 国际发票识别
      • 国际发票识别（明细）
      • 文档信息识别（反馈）
      • 银行回单识别
    • 三单匹配
      • 三单匹配-同步接口
        POST
      • 三单匹配-异步任务提交
        POST
      • 三单匹配-异步结果查询
        POST
    • 统一反馈
      • 三单匹配反馈详细说明
      • 算法服务统一反馈接口
    • 文档分类（区分发票、附件）
      POST
    • 智能赋码税收分类编码识别
      POST
  • 文档中心
    • 外部文件上传接口
      POST
  • 国际发票
  • 数据模型
    • 示例数据模型
      • Pet
      • Category
      • Tag
  1. 三单匹配

三单匹配-同步接口

POST
/ai/knowledge/nlpService/item/match

一、接口描述#

解决发票和单据（比如入库单）匹配问题，输入发票信息和候选单据信息，输出发票每条明细匹配的单据明细
1.
支持一张发票匹配多张单据；
2.
仅支持一条发票明细匹配多条单据明细，不支持一条单据明细匹配多条发票明细的情况；
3.
发票或入库单的金额、单价、数量字段若无值，应保持为空，不得转化为0；
4.
当初始化配置项 use_product_code 设为 false 时，入库单的物料编码为非必填项；
5.
若启用了向量库功能，在切换 use_product_code 配置时，需清空向量库中的数据以保证一致性。
私有化部署注意事项：
建议在私有化部署时同步部署 Milvus 向量数据库，并在初始化阶段提供完整的物料库数据（CSV 文件，包含单据上会出现的所有物料）。物料库数据应至少包含以下字段：
product_code：商品编码 / 物料编码
product_name：物料名称
虽然系统可在无初始数据的情况下正常部署，但此时所有向量计算将采用实时生成方式，可能导致接口响应时间较长。提供物料库数据后，系统可在初始化时预生成向量索引，从而显著提升后续接口调用的性能和响应速度。

二、输入参数#

1. targetFile： 发票明细文件（CSV 格式，UTF-8 编码）。文件中的每一行表示一条发票明细记录，字段说明如下：
item_id（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、product_name，或匹配模式要求的 amount / quantity），系统将直接报错，无法继续处理。因此请确保所有必填字段完整且符合格式要求。
2. targetUrl： 发票文件（csv文件，UTF-8 编码）的url地址。文件格式和targetFile一致。优先使用targetFile，如果targetFile存在，则忽略 targetUrl。targetFile 和 targetUrl 至少提供一个，不可同时为空。
3. candidateFile： 候选单据明细文件（CSV 格式，UTF-8 编码）。每一行表示一张单据中的一条明细记录，字段说明如下：
item_id（string）：单据明细的唯一标识。必填且不可重复，通常建议格式为{单据单号}_{单据行号} ，例如{入库单号}_{入库单行号}。
doc_id（string）：该明细所属单据的唯一标识（即单据单号）。必填字段。
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_code、product_name，或匹配模式要求的 amount / quantity），系统将自动过滤该条记录，不参与后续匹配。
4. candidateUrl： 候选单据文件（csv文件，UTF-8 编码）的url地址。文件格式和candidateFile一致。优先使用candidateFile，如果candidateFile存在，则忽略candidateUrl。candidateFile和candidateUrl至少提供一个，不可同时为空。
5. settings: 动态配置项, 此动态配置项通过传入 JSON 字符串 的方式来配置不同的容差参数和匹配模式,后续新增配置可以直接在该参数中新增。所有配置项为选填项，用户可以选择传入或不传入。如果没有传入配置项，则会使用默认值。以下是每个配置项的详细说明和要求：
配置项说明：
所有配置项均为选填项，可以选择传入也可以不传入。
如果不传入某些配置项，则会使用以下默认值：
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: 输出结果。包含匹配的单据信息和每一行发票明细的匹配情况。如果没有匹配到单据，matchDocIds/matchDetails 返回空列表；如果匹配到单据，则返回发票与单据的匹配信息。匹配信息包含以下字段：
matchDocIds: 该发票匹配的单据 IDs，，若无匹配，返回空列表；若有匹配，返回一个包含所有匹配单据 ID 的数组。单据 ID 来源于单据文件中的 doc_id 字段。
matchDetails: 发票与单据的明细匹配信息列表。每个明细项包含以下字段：
targetItemId: 发票的明细 ID，来源于发票文件中的 item_id 字段。
candidateItem: 候选单据明细信息列表。每个候选项是一个对象，包含：
candidateDocId: 该明细所属的单据 ID。(doc_id)
candidateItemId: 该明细的 ID。

请求参数

Query 参数

Header 参数

Body 参数multipart/form-data

请求示例代码

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location -g --request POST '/ai/knowledge/nlpService/item/match?access_token={{access_token}}' \
--header 'client-platform: common' \
--form 'targetFile=@"cmMtdXBsb2FkLTE3MzYxMzMwMzYzODEtMjU=/test_invoice_data.csv"' \
--form 'targetUrl=""' \
--form 'candidateFile=@"cmMtdXBsb2FkLTE3MzYxMzMwMzYzODEtMjk=/test_receipt_data.csv"' \
--form 'candidateUrl=""' \
--form 'settings="{\"priceTolerance\":0.001,\"priceToleranceType\":\"0\"}"'

返回响应

🟢200成功
application/json
Body

示例
{
    "errcode": "0000",
    "description": "Success",
    "data": {
        "matchDocIds": [
            "100145695"
        ],
        "matchDetails": [
            {
                "targetItemId": "24232000000053162531_1",
                "candidateItem": [
                    {
                        "candidateDocId": "100145695",
                        "candidateItemId": "100145695_1"
                    }
                ]
            }
        ]
    },
    "traceId": "1eb3120be1724f1c81bb170737d10e73"
}
修改于 2026-02-25 06:51:01
上一页
银行回单识别
下一页
三单匹配-异步任务提交
Built with