Extract API¶

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

该服务使用 OCR 引擎扫描文档，然后运用 AI 算法提取所需字段，例如 invoices （发票）的总额、到期日或发票行， bank statements （银行对账单）的期初和期末余额及日期， expenses （费用）的总额和日期，以及 resumes （简历）的姓名、电子邮箱和电话号码。

该服务为付费服务。每处理一份文档都会从您的文档数字化 IAP 账户中扣除一个积分。有关 IAP 账户的更多信息，请参阅此处。

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

概述¶

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

版本¶

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

最新版本为：

invoices（发票）：123
bank statements（银行对账单）：100
expenses（费用）：132
applicant（应聘者）：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 （可选）: 用户的增值税号（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 PO 格式。
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,
}

Note

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,
    }
}

Note

该 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`¶

我们要从文档中提取的每个关注字段（例如总额或到期日）也称为 features （特征）。某种文档类型对应的所有已提取特征的完整列表见下文各节。

对于每个特征，我们会返回一个候选列表，并标出模型预测为该特征最佳匹配的候选。

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 为 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 来测试您的集成。

使用该令牌会使您进入测试模式，让您可以模拟整个流程，而无需真正解析文档，也无需为每次成功解析 document 支付一个积分。

测试模式下唯一的技术差异是，您发送的文档不会被系统解析，并且您从 /get_result 得到的响应是硬编码的。

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

Extract API¶

概述¶

版本¶

流程¶

解析¶

路由¶

请求¶

响应¶

获取结果¶

路由¶

请求¶

响应¶

公共字段¶

feature_result¶

候选¶

发票¶

invoice_lines 特性¶

银行对账单¶

bank_statement_lines 特性¶

费用¶

申请人¶

集成测试¶

`feature_result`¶

`invoice_lines` 特性¶

`bank_statement_lines` 特性¶