Extract 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 （可选）: 用户语言。格式：language_code + _ + locale （例如 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 错误方案。相反，该 API 有自己的一套错误方案，封装在一个成功的 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（bool）。仅当 verified_bic 为 true 时才存在 name 和 city。
`iban`	`content` 是一个字符串
`aba`	`content` 是一个字符串
`VAT_Number`	`content` 是一个字符串根据 user_infos 中 perspective 的取值，这将是供应商或客户的增值税号。如果 perspective 为 client，则为供应商的增值税号。如果为 supplier，则为客户的增值税号。
`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 来测试你的集成。

使用此令牌可以在不计费的情况下解析文档。请注意，集成令牌受严格的每日速率限制，仅用于测试目的。如果超出此限制，你必须等待一整天该限制才会重置。

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

Extract API¶

概述¶

版本¶

流程¶

解析¶

路线¶

请求¶

响应¶

获取结果¶

路线¶

请求¶

响应¶

常规字段¶

feature_result¶

候选¶

结算单¶

invoice_lines 特性¶

银行对账单¶

bank_statement_lines 特性¶

费用报销¶

申请人¶

集成测试¶

`feature_result`¶

`invoice_lines` 特性¶

`bank_statement_lines` 特性¶