提取API¶

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

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

该服务为付费服务。每个文档处理都会消耗您文档数字化 IAP 帐户中的一个积分。有关 IAP 帐户的更多信息，请访问 here。

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

概述¶

提取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 实现可以在 here 中找到，并且在 integration testing section 中提供了用于集成测试的令牌。

解析¶

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

路线¶

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

/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``（必填）

该版本将决定您的请求的格式和服务器响应的格式。您应该使用 latest version available。

``documents``（必填）

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

``dbuuid``（可选）

Odoo 数据库的唯一标识符。

``webhook_url``（可选）

可以提供 Webhook URL。当结果准备好时，一个空的 POST 请求将被发送到``webhook_url/document_token``。

``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 PO 格式。
``perspective``（可选）: 可以是 client or supplier. This field is useful for invoices only. client means that the user information provided are related to the client of the invoice. supplier 表示与供应商相关。如果未提供，将使用客户端。

{
    "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)。仅当 verify_bic 为 true 时，才会出现名称和城市。
`iban`	`content` 是一个字符串
`aba`	`content` 是一个字符串
`VAT_Number`	`content` 是一个字符串根据 user_infos 中透视图的值，这将是供应商或客户的增值税号。如果视角是客户，则它将是供应商的增值税号。如果是供应商，则为客户的增值税号。
`qr-bill`	`content` 是一个字符串
`payment_ref`	`content` 是一个字符串
`purchase_order`	`content` 是一个字符串使用``selected_values`` instead of `selected_value`
`country`	`content` 是一个字符串
`currency`	`content` 是一个字符串
`date`	`content` 是一个字符串格式：年-月-日
`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 实现可以在 here 找到。

提取API¶

概述¶

版本¶

流动¶

解析¶

路线¶

要求¶

回复¶

获取结果¶

路线¶

要求¶

回复¶

公共字段¶

feature_result¶

候选人¶

发票¶

invoice_lines 功能¶

银行对账单¶

bank_statement_lines 功能¶

费用¶

申请人¶

集成测试¶

`feature_result`¶

`invoice_lines` 功能¶

`bank_statement_lines` 功能¶