提取 API¶

Odoo 提供了一项服务，用于自动处理发票、银行对账单、费用或简历类型的文档。

该服务使用 OCR 引擎扫描文档，然后利用基于 AI（人工智能）的算法提取关键字段，例如发票的总额、到期日或发票明细，银行对账单 的初始和最终余额、日期，费用的总额、日期，以及简历的姓名、电子邮件、电话号码等。

这是一项付费服务。每次文档处理将从您的文档数字化 IAP 账户中扣除一个积分。有关 IAP 账户的更多信息，请参阅此处。

您可以直接在会计、费用或招聘应用中使用此服务，也可以通过 API 使用。Extract API（在下一节中详细介绍）允许您将我们的服务直接集成到自己的项目中。

概述¶

Extract API 使用 JSON-RPC2 协议，其端点路由位于 https://extract.api.odoo.com 。

版本¶

Extract API 的版本在路由中指定。

最新版本如下：

发票：123
银行对账单：100
费用：132
求职者：102

流程¶

每种文档类型的流程相同。

调用 /parse 提交您的文档（每个文档调用一次）。成功时，响应中会返回一个 document_token 。
然后，您需要定期轮询 /get_result 以获取文档的解析状态。

或者，您可以在调用 /parse 时提供一个 webhook_url ，当结果准备就绪时，您将通过 POST 请求收到通知。

所有请求均应使用 HTTP POST 方法。发票完整流程的 Python 实现可在此处找到 这里 ，并在集成测试部分中提供了用于集成测试的令牌。

解析¶

请求文档的数字化。该路由将返回一个 document_token ，您可以使用它来获取请求的结果。

路由¶

/api/extract/invoice/2/parse

/api/extract/bank_statement/1/parse

/api/extract/expense/2/parse

/api/extract/applicant/2/parse

请求¶

jsonrpc （必需）

参见 JSON-RPC2

method （必需）

参见 JSON-RPC2

id （必需）

参见 JSON-RPC2

params

account_token （必需）

IAP 账户的令牌，将从中扣除积分。每次成功调用消耗一个积分。

version （必需）

版本将决定请求的格式和服务器响应的格式。您应使用最新可用版本。

documents （必需）

文档必须以 ASCII 编码的 Base64 字符串形式提供。列表中应仅包含一个文档。此字段为列表形式仅出于遗留原因。支持的格式为 pdf、png 和 jpg。

dbuuid （可选）

Odoo 数据库的唯一标识符。

webhook_url （可选）

可以提供一个 webhook URL。当结果准备就绪时，会向 webhook_url/document_token 发送一个空的 POST 请求。

user_infos （可选）

有关将文档发送到提取服务的人员的信息。可以是客户或供应商（取决于 perspective ）。此信息不是服务运行所必需的，但能显著提高结果的质量。

user_company_vat （可选）: 用户的增值税号。
user_company_name （可选）: 用户公司名称。
user_company_country_code （可选）: 用户的国家代码。格式：ISO3166 alpha-2 。
user_lang （可选）: 用户语言。格式：语言代码 + _ + 区域 （例如 fr_FR、en_US）。
user_email （可选）: 用户电子邮件。
purchase_order_regex （可选）: 用于识别采购订单的正则表达式。如果未提供，默认使用 Odoo 采购订单格式。
perspective （可选）: 可以是 client 或 supplier 。此字段仅对发票有用。client 表示提供的用户信息与发票的客户相关，supplier 表示与供应商相关。如果未提供，则默认使用 client 。

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "account_token": string,
        "version": int,
        "documents": [string],
        "dbuuid": string,
        "webhook_url": string,
        "user_infos": {
            "user_company_vat": string,
            "user_company_name": string,
            "user_company_country_code": string,
            "user_lang": string,
            "user_email": string,
            "purchase_order_regex": string,
            "perspective": string,
        },
    },
    "id": string,
}

注解

user_infos 参数是可选的，但它能显著提高结果质量，尤其是对于发票。您提供的信息越多，效果越好。

响应¶

jsonrpc

参见 JSON-RPC2

id

参见 JSON-RPC2

result

status: 指示请求状态的代码。请参见下表。
status_msg: 提供有关请求状态详细信息的字符串。
document_token: 仅在请求成功时存在。

状态	状态消息
`success`	成功
`error_unsupported_version`	不支持的版本
`error_internal`	发生错误
`error_no_credit`	您的积分不足
`error_unsupported_format`	不支持的文件格式
`error_maintenance`	服务器当前正在维护中，请稍后再试

{
    "jsonrpc": "2.0",
    "id": string,
    "result": {
        "status": string,
        "status_msg": string,
        "document_token": string,
    }
}

注解

API 实际上并未使用 JSON-RPC 错误方案，而是将自身的错误方案打包到成功的 JSON-RPC 结果中。

获取结果¶

路由¶

/api/extract/invoice/2/get_result

/api/extract/bank_statement/1/get_result

/api/extract/expense/2/get_result

/api/extract/applicant/2/get_result

请求¶

jsonrpc （必需）

参见 JSON-RPC2

method （必需）

参见 JSON-RPC2

id （必需）

参见 JSON-RPC2

params

version （必需）: 版本应与传递给 /parse 请求的版本匹配。
document_token （必需）: 您希望获取当前解析状态的 document_token 。
account_token （必需）: 用于提交文档的 IAP 账户的令牌。

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "version": int,
        "document_token": int,
        "account_token": string,
    },
    "id": string,
}

响应¶

从解析结果中获取内容时，检测到的字段会因文档类型而有很大差异。每个响应是一个字典列表，每个文档一个字典。字典的键是字段名称，值是字段的值。

jsonrpc

参见 JSON-RPC2

id

参见 JSON-RPC2

result

status

指示请求状态的代码。请参见下表。

status_msg

提供有关请求状态详细信息的字符串。

results

仅在请求成功时存在。

full_text_annotation: 包含该文档的 OCR 未经处理的完整结果。

状态	状态消息
`success`	成功
`error_unsupported_version`	不支持的版本
`error_internal`	发生错误
`error_maintenance`	服务器当前正在维护中，请稍后再试
`error_document_not_found`	未找到文档
`error_unsupported_size`	文档因尺寸太小而被拒绝
`error_no_page_count`	无法获取 PDF 文件的页数
`error_pdf_conversion_to_images`	无法将 PDF 转换为图像
`error_password_protected`	PDF 文件受密码保护
`error_too_many_pages`	文档包含过多页面

{
    "jsonrpc": "2.0",
    "id": string,
    "result": {
        "status": string,
        "status_msg": string,
        "results": [
            {
                "full_text_annotation": string,
                "feature_1_name": feature_1_result,
                "feature_2_name": feature_2_result,
                ...
            },
            ...
        ]
    }
}

通用字段¶

`feature_result`¶

我们希望从文档中提取的每个感兴趣字段（例如总额或到期日期）也称为特征。与某种文档类型相关的所有提取特征的详尽列表可以在以下部分找到。

对于每个特征，我们会返回一个候选列表，并突出显示模型预测为最适合该特征的候选。

selected_value （可选）: 此特征的最佳候选。
selected_values （可选）: 此特征的最佳候选列表。
candidates （可选）: 此特征的所有候选列表，按置信度分数降序排列。

"feature_name": {
    "selected_value": candidate_12,
    "candidates": [candidate_12, candidate_3, candidate_4, ...]
}

候选¶

对于每个候选，我们提供其表示形式及其在文档中的位置。候选按适用性降序排列。

content: 候选的表示形式。
coords: [center_x, center_y, width, height, rotation_angle] 。位置和尺寸相对于页面大小，因此介于 0 和 1 之间。角度是以顺时针方向测量的旋转角度，单位为度。
page: 原始文档中候选所在的页面（从 0 开始）。

"candidate": [
    {
        "content": string|float,
        "coords": [float, float, float, float, float],
        "page": int
    },
    ...
]

发票¶

发票结构复杂，可能包含许多不同字段。下表列出了我们可以从发票中提取的所有字段。

特征名称	特性
`SWIFT_code`	`content` 是编码为字符串的字典。它包含有关检测到的 SWIFT 代码（或 BIC ）的信息。键： `bic` 检测到的 BIC（字符串）。 `name` （可选）银行名称（字符串）。 `country_code` 银行的 ISO3166 alpha-2 国家代码（字符串）。 `city` （可选）银行所在城市（字符串）。 `verified_bic` 如果 BIC 在我们的数据库中找到，则为 True（布尔值）。仅当 verified_bic 为 true 时，名称和城市才会存在。
`iban`	`content` 是字符串
`aba`	`content` 是字符串
`VAT_Number`	`content` 是字符串根据 user_infos 中 perspective 的值，这将是供应商或客户的增值税号。如果 perspective 为客户，则为供应商的增值税号；如果为供应商，则为客户的增值税号。
`qr-bill`	`content` 是字符串
`payment_ref`	`content` 是字符串
`purchase_order`	`content` 是字符串使用 `selected_values` 而不是 `selected_value`
`country`	`content` 是字符串
`currency`	`content` 是字符串
`date`	`content` 是字符串格式：YYYY-MM-DD
`due_date`	与 `date` 相同
`total_tax_amount`	`content` 是浮点数
`invoice_id`	`content` 是字符串
`subtotal`	`content` 是浮点数
`total`	`content` 是浮点数
`supplier`	`content` 是字符串
`client`	`content` 是字符串
`email`	`content` 是字符串
`website`	`content` 是字符串

`invoice_lines` 特性¶

它以字典列表的形式返回，其中每个字典代表一条发票明细。

"invoice_lines": [
    {
        "description": string,
        "quantity": float,
        "subtotal": float,
        "total": float,
        "taxes": list[float],
        "total": float,
        "unit_price": float
    },
    ...
]

银行对账单¶

下表列出了从银行对账单中提取的所有字段。

特征名称	特性
`balance_start`	`content` 是浮点数
`balance_end`	`content` 是浮点数
`date`	`content` 是字符串

`bank_statement_lines` 特性¶

它以字典列表的形式返回，其中每个字典代表一条银行对账单明细。

"bank_statement_lines": [
    {
        "amount": float,
        "description": string,
        "date": string,
    },
    ...
]

费用¶

费用比发票简单。下表列出了我们可以从费用报告中提取的所有字段。

特征名称	特性
`description`	`content` 是字符串
`country`	`content` 是字符串
`date`	`content` 是字符串
`total`	`content` 是浮点数
`currency`	`content` 是字符串

求职者¶

这种第三类文档用于处理简历。下表列出了我们可以从简历中提取的所有字段。

特征名称	特性
`name`	`content` 是字符串
`email`	`content` 是字符串
`phone`	`content` 是字符串
`mobile`	`content` 是字符串

集成测试¶

您可以通过在 /parse 请求中使用 integration_token 作为 account_token 来测试您的集成。

使用此令牌将进入测试模式，允许您模拟整个流程，而无需真正解析文档，也不会因每次成功解析文档而扣除一个积分。

测试模式中唯一的区别是，您发送的文档不会被系统解析，并且您从 /get_result 获取的响应是硬编码的。

发票完整流程的 Python 实现可以在此处找到 这里 。

Edit on GitHub

提取 API¶

概述¶

版本¶

流程¶

解析¶

路由¶

请求¶

响应¶

获取结果¶

路由¶

请求¶

响应¶

通用字段¶

feature_result¶

候选¶

发票¶

invoice_lines 特性¶

银行对账单¶

bank_statement_lines 特性¶

费用¶

求职者¶

集成测试¶

`feature_result`¶

`invoice_lines` 特性¶

`bank_statement_lines` 特性¶