提取接口¶

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

该服务使用 OCR 引擎扫描文档，然后使用 AI 基础的算法提取感兴趣的字段，例如发票的总金额、到期日期或发票行；银行对账单的初始余额和最终余额、日期；费用的总金额、日期；以及简历中的姓名、邮件、电话号码。

此服务是一项付费服务。每处理一份文档将消耗您一个积分。积分可以在 iap.odoo.com 上购买。

你可以直接在会计、费用或招聘应用中使用此服务，也可以通过接口进行调用。下一节将详细介绍提取接口，该接口允许你将我们的服务直接集成到自己的项目中。

概览¶

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

版本¶

提取接口的版本在路线中指定。

最新版本为：

发票：123
银行对账单：100
费用：132
申请人：102

流程¶

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

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

另一种方式是，在调用 /parse 时提供一个 webhook_url，当结果准备就绪时，您将通过 POST 请求收到通知。

应使用 HTTP POST 方法。所有操作都应使用 HTTP POST 方法。发票完整流程的 Python 实现可以在 此处 找到，集成测试所需的令牌可在集成测试部分中获取。

解析¶

向 OCR 请求处理文档。该路线将返回一个 document_token，您可以使用它来获取请求的结果。

路由¶

/api/提取/发票/2/解析

/api/提取/银行对账单/1/解析

/api/提取/费用/2/解析

/api/提取/申请人/2/解析

请求¶

`jsonrpc` (必填)

请参见 JSON-RPC2

方法 (必填)

请参见 JSON-RPC2

id (必填)

请参见 JSON-RPC2

参数

``account_token``（必填）

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

版本 (必填)

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

文档 (必填)

文档必须以 ASCII 编码的字符串形式提供。列表中只能包含一个字符串。如果提供了多个字符串，只有第一个对应 PDF 的字符串会被处理。如果没有找到 PDF，第一个字符串将被处理。此字段仅出于遗留原因而为列表类型。支持的扩展名包括 pdf、png、jpg 和 bmp。

dbuuid (可选)

Odoo 数据库的唯一标识符。

webhook_url (可选)

可以提供一个网络钩子网址。当结果准备就绪时，将向 webhook_url/document_token 发送一个空的 POST 请求。

user_infos (可选)

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

user_company_vat (可选): 用户的增值税编号。
user_company_name (可选): 用户所属公司的名称。
user_company_country_code (可选): 用户的国家代码。格式：ISO3166 字母-2。
user_lang (可选): 用户的语言。格式：*语言代码 + _ + 区域代码*（例如：fr_FR, en_US）。
user_email (可选): 用户的邮件。
purchase_order_regex (可选): 用于采购订单识别的正则表达式。如果未提供，将默认使用 Odoo 的采购订单格式。
视角 (可选): 可以是 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 参数是可选的，但它能显著提高结果的质量，尤其是在发票处理方面。您提供的信息越多，效果越好。

响应¶

JSON-RPC

请参见 JSON-RPC2

编号

请参见 JSON-RPC2

结果

状态: 表示请求状态的代码。请参见下面的表格。
状态消息: 一个字符串，用于提供关于请求状态的详细描述。
文档令牌: 仅在请求成功时显示。

状态	状态消息
`成功`	成功
`不支持的版本`	不支持的版本
`内部错误`	发生了一个错误
`没有信用`	您信用额度不足
`不支持的格式`	不支持的文件格式
`维护模式错误`	服务器当前正在维护中，请稍后再试。

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

注解

API 实际上并不使用 JSON-RPC 错误方案。相反，API 自带一个错误方案，并将其打包在成功的 JSON-RPC 结果中。

获取结果¶

路由¶

/api/提取/发票/2/获取结果

/api/提取/银行对账单/1/获取结果

/api/提取/费用/2/获取结果

/api/提取/申请者/2/获取结果

请求¶

`jsonrpc` (必填)

请参见 JSON-RPC2

方法 (必填)

请参见 JSON-RPC2

id (必填)

请参见 JSON-RPC2

参数

版本 (必填): 版本应与传递给 /parse 请求的版本相匹配。
document_token (必填): 您想要获取当前解析状态的 document_token。
``account_token``（必填）: 提交文档所使用的账户的令牌。

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

响应¶

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

JSON-RPC

请参见 JSON-RPC2

编号

请参见 JSON-RPC2

结果

状态

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

状态消息

一个字符串，用于提供关于请求状态的详细描述。

结果

仅在请求成功时显示。

全文本注释: 包含该文档的 OCR 未处理完整结果

状态	状态消息
`成功`	成功
`不支持的版本`	不支持的版本
`内部错误`	发生了一个错误
`维护模式错误`	服务器当前正在维护中，请稍后再试。
`未找到文档`	该文档未找到
`不支持的大小`	该文档因尺寸过小已被拒绝
`没有页面计数`	无法获取 PDF 文件的页数
`错误：将PDF转换为图像`	无法将 PDF 转换为图像
`密码保护错误`	PDF 文件受密码保护
`错误：页面过多`	该文档包含过多页面

{
    "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,
                ...
            },
            ...
        ]
    }
}

常用字段¶

`功能结果`¶

每个我们希望从文档中提取的字段，例如总金额或到期日，也被称为特征。所有与特定类型文档相关的已提取特征的完整列表可以在下面的章节中找到。

对于每个特性，我们返回一个候选列表，并突出显示我们的模型预测为该特性最佳匹配的候选项。

selected_value (可选): 这个功能的最佳候选。
selected_values (可选): 此功能的最佳适用场景。
候选人 (可选): 此功能的所有候选项，按置信度分数降序排列。

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

候选者¶

对于每个候选项，我们提供其在文档中的表示形式和位置。候选项按适用性递减的顺序排序。

内容: 候选人的表示形式。
坐标: [中心点X坐标, 中心点Y坐标, 宽度, 高度, 旋转角度]。位置和尺寸是相对于页面大小的，因此其值在0到1之间。角度是以度为单位的顺时针旋转角度。
页面: 当前候选对象所在的原始文档页面（从 0 开始）。

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

发票¶

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

功能名称	特定性
`SWIFT代码`	`content` 是一个以字符串编码的字典。它包含有关检测到的 SWIFT 代码（或 BIC）的信息。键： `bic` 检测到的 BIC（字符串）。 ``name``（可选）银行名称（字符串）。 `国家代码` 银行的 ISO3166 alpha-2 国家代码（字符串）。 `城市` (可选) 银行所在城市（字符串）。 `验证的BIC` 如果 BIC 在我们的数据库中找到（布尔值）。名称和城市仅在 `verified_bic` 为真时存在。
`iban`	`内容` 是一个字符串
`aba`	`内容` 是一个字符串
`增值税编号`	`内容` 是一个字符串根据 user_infos 中 perspective 的值，这将是供应商或客户的增值税号码。如果 perspective 是 client，则这是供应商的增值税号码。如果是 supplier，则这是客户的增值税号码。
`二维码单据`	`内容` 是一个字符串
`支付参考`	`内容` 是一个字符串
`purchase_order`	`内容` 是一个字符串使用 `selected_values` 而不是 `selected_value`
`国家`	`内容` 是一个字符串
`货币`	`内容` 是一个字符串
`日期`	`内容` 是一个字符串格式：YYYY-MM-DD
`到期日期`	与 `date` 相同
`总税额`	`内容` 是一个浮点数
`发票编号`	`内容` 是一个字符串
`小计`	`内容` 是一个浮点数
`总数`	`内容` 是一个浮点数
`供应商`	`内容` 是一个字符串
`客户端`	`内容` 是一个字符串
`邮件`	`内容` 是一个字符串
`网站`	`内容` 是一个字符串

`发票行` 功能¶

它以字典列表的形式返回，每个字典代表一行发票。

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

银行对账单¶

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

功能名称	特定性
`期初余额`	`内容` 是一个浮点数
`期末余额`	`内容` 是一个浮点数
`日期`	`内容` 是一个字符串

`银行对账单行` 功能¶

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

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

费用¶

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

功能名称	特定性
`描述`	`内容` 是一个字符串
`国家`	`内容` 是一个字符串
`日期`	`内容` 是一个字符串
`总数`	`内容` 是一个浮点数
`货币`	`内容` 是一个字符串

申请人¶

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

功能名称	特定性
`名称`	`内容` 是一个字符串
`邮件`	`内容` 是一个字符串
`电话`	`内容` 是一个字符串
`移动`	`内容` 是一个字符串

集成测试¶

你可以通过在 /parse 请求中将 integration_token 作为 account_token 进行测试。

使用此令牌将使您进入测试模式，允许您模拟整个流程，而无需实际解析文档，且每次成功**文档**解析也不会被计费一次信用点。

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

可以在此处下载完整的发票流程的 Python 实现：这里。

Edit on GitHub

提取接口¶

概览¶

版本¶

流程¶

解析¶

路由¶

请求¶

响应¶

获取结果¶

路由¶

请求¶

响应¶

常用字段¶

功能结果¶

候选者¶

发票¶

发票行 功能¶

银行对账单¶

银行对账单行 功能¶

费用¶

申请人¶

集成测试¶

`功能结果`¶

`发票行` 功能¶

`银行对账单行` 功能¶