提取 API?

Odoo 提供了一項服務，允許您自動處理發票。該服務使用光學字符識別（OCR）引擎掃描您的文檔，然后使用基于人工智能的算法提取感興趣的字段，例如總額、到期日期或發票行。更多功能信息可以在演示頁面上找到。

此服務是付費服務。每個發票處理將花費您一個信用?？梢栽?iap.odoo.com 上購買三種不同大小的套餐。

您可以直接在Odoo會計應用程序中使用此服務，也可以通過API使用。下一節中詳細介紹的Extract API允許您將我們的服務直接集成到您自己的項目中。

發票?

提取API使用JSON-RPC2_協議。不同的路由位于以下地址： https://iap-extract.odoo.com 。

預期成功的流程?

調用 /iap/invoice_extract/parse 來提交您的發票（每張發票調用一次）。成功后，您將在響應中收到一個 document_id 。
你需要定期輪詢 /iap/invoice_extract/get_results 來獲取文檔的解析狀態。
一旦收到結果，您可以通過調用 /iap/invoice_extract/validate 并發送期望的值來驗證它。這一步驟是可選的，但可以極大地幫助系統改進。

這三個路由在這個章節中有詳細說明。所有路由都應使用HTTP POST方法。完整流程的Python實現可以在這里 下載 ，集成測試的令牌在集成測試章節中提供。

路線?

`/iap/invoice_extract/parse`?

描述?

請求OCR處理文檔。該路由將返回一個 document_id ，您可以使用它來獲取您的請求的結果。

請求正文?

jsonrpc (必填)

必須完全是“2.0”。

method (必填)

必須是“call”。

id (必填)

客戶端建立的標識符。它允許客戶端跟蹤哪個響應與哪個請求相對應。這使異步調用更容易。

params

account_token (必填)

從中扣除信用額度的帳戶令牌。每個成功的調用都需要一個令牌。

version (可選)

版本將決定您的請求格式和服務器響應格式。某些結果在舊版本中可能不可用。對于當前版本1.2.0，請發送“120”。如果未指定，則將使用最新版本。

documents (必填)

發票必須以 ASCII 編碼的字符串形式提供。列表應該只包含一個字符串。如果提供了多個字符串，則只處理與 pdf 對應的第一個字符串。如果沒有找到 pdf，則處理第一個字符串。出于歷史原因，此字段僅為列表。支持的擴展名為 pdf * 、 * png 、 jpg 和 bmp 。

user_infos (必填)

發票收件人信息。此信息不是服務運行所必需的，但它可以極大地提高結果的質量。

user_company_vat (可選): 客戶的增值稅號碼。
user_company_name (可選): 客戶公司名稱。
user_company_country_code (可選): 客戶端的國家代碼。格式： ISO3166 alpha-2。
user_lang (可選): 客戶端語言。格式： 語言代碼 + _ + 區域設置 （例如：fr_FR，en_US）。
user_email (可選): 客戶電子郵件。

{
    "jsonrpc": string,
    "method": string,
    "params": {
            "account_token": string (hex),
            "version": int,
            "documents": [string],
            "user_infos": {
                    "user_company_vat": string,
                    "user_company_name": string,
                    "user_company_country_code": string,
                    "user_lang": string,
                    "user_email": string,
            },
    },
    "id": string (hex),
}

回應?

jsonrpc

一個字符串，指定 JSON-RPC 協議的版本。它將是“2.0”。

id

您在請求正文中設置的標識符。

result

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.
document_id: 僅在請求成功時出現。

注解

API實際上并不使用JSON-RPC錯誤方案。相反，API在成功的JSON-RPC結果中捆綁了自己的錯誤方案。

狀態碼	狀態消息
0	成功
2	發生了一個錯誤
3	您的信用額度不足
6	不支持的文件格式
9	服務器正在維護中，請稍后再試。

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "status_code": int,
        "status_msg": string,
        "document_id": int,
    }
}

`/iap/invoice_extract/get_results`?

描述?

請求使用 /parse 路由獲取的文檔 ID 的結果?？梢苑祷亟Y果或“請求掛起”消息。

請求正文?

jsonrpc (必填)

Same as for /parse.

method (必填)

Same as for /parse.

id (必填)

Same as for /parse.

params :

version (必填): Same as for /parse.
documents_ids (必填): 您想獲取當前解析狀態的文檔ID列表。

{
    "jsonrpc": string,
    "method": string,
    "params": {
        "version": int,
        "documents_ids": [int]
    },
    "id": string (hex),
}

回應?

jsonrpc

Same as for /parse.

id

Same as for /parse.

result

每個鍵為文檔ID的字典。對于每個 document_id ：

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.
results: 僅在請求成功時出現。

警告

結果鍵是字符串，盡管請求體中給出的 document_ids 是整數。

狀態碼	狀態消息
0	成功
1	未準備好
2	發生了一個錯誤
9	服務器正在維護中，請稍后再試。

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "document_id_1": {
            "status_code": int,
            "status_msg": str,
            "results": [{"feature_1_name": feature_1_result,
                         "feature_2_name": feature_2_result,
                         …
                        }]
            },
        "document_id_2": {
            "status_code": int,
            "status_msg": str,
            "results": [{"feature_1_name": feature_1_result,
                         "feature_2_name": feature_2_result,
                         …
                        }]
            },
            ...
    }
}

`feature_result`?

我們想從發票中提取的每個感興趣的字段，例如總額或到期日期，也稱為特征。所有提取的特征的詳盡列表可以在下表中找到。

對于每個特征，我們返回一個候選列表，并突出顯示我們的模型預測最適合該特征的候選項。

selected_value: 該功能的最佳候選人。
words: 按照得分遞減的順序列出此功能的所有候選項。

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

`candidate`?

對于每個候選項，我們都會給出其在文檔中的表示和位置。候選項按照適用性遞減的順序排序。

content: 候選人的表示。
coords: [center_x, center_y, width, height, rotation_angle] 。位置和尺寸是相對于頁面大小的，因此在0和1之間。角度是以度為單位的順時針旋轉。
page: 原始文檔中包含該候選項的頁面編號（從0開始）。

{
    "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 為真，則名稱和城市才存在。
`VAT_Number`	content 是一個字符串
`country`	content 是一個字符串
`currency`	content 是一個字符串
`date`	content 是一個字符串格式： YYYY-MM-DD HH:MM:SS
`due_date`	與 `date` 相同
`global_taxes`	content 是一個浮點數 candidate 有一個額外的字段 `amount_type` 。它的值始終為百分比。 selected_values 是一個候選項列表。
`global_taxes_amount`	content 是一個浮點數
`invoice_id`	content 是一個字符串
`subtotal`	content 是一個浮點數
`total`	content 是一個浮點數
`supplier`	content 是一個字符串

`invoice_lines` 功能的 `feature_result`?

它遵循更具體的結構?；旧鲜且粋€字典列表，其中每個字典代表一條發票行。每個值都遵循 feature_result 結構。

[
    {
        "description": feature_result,
        "discount": feature_result,
        "product": feature_result,
        "quantity": feature_result,
        "subtotal": feature_result,
        "total": feature_result,
        "taxes": feature_result,
        "total": feature_result,
        "unit": feature_result,
        "unit_price": feature_result
    },
    ...
]

`/iap/invoice_extract/validate`?

描述?

驗證發票不同特征的路由。驗證步驟是可選的，但強烈建議使用。通過告訴系統每個特征是否正確或錯誤，您提供了重要的反饋。它沒有直接影響，但有助于系統大大提高未來發送的發票的預測準確性。

請求正文?

jsonrpc (必填)

Same as for /parse.

method (必填)

Same as for /parse.

params

documents_id (必填): 您要驗證結果的文檔的ID。
values: 包含每個功能的驗證。字段 merged_line 指示是否已合并 invoice_lines 。

注解

您不必驗證所有功能才能使驗證成功。但是，對于同一張發票，無法多次調用 /validate 。因此，您應該一次性驗證所有要驗證的功能。

{
    "jsonrpc": string,
    "method": string,
    "params": {
        "document_id": int,
        "values": {
            "merged_lines": bool
            "feature_name_1": validation_1,
            "feature_name_2": validation_2,
            ...
        }
    },
    "id": string (hex),
}

`validation`?

給定功能的驗證是一個包含該給定功能預期值的文本表示的字典。此格式適用于除 global_taxes 和 invoice_lines 之外的所有功能，這兩個功能具有更復雜的驗證格式。

{ "content": string|float }

`global_taxes` 的驗證?

content 是一個字典列表。每個字典表示一種稅收：

amount: 適用稅的金額。
tax_amount: 稅額。
tax_amount_type: 指示 tax_amount 是百分比還是固定值。必須使用文字字符串“fixed”或“percent”指定類型。
tax_price_include: 指示 amount 是否已經包含稅費。

{"content": [
    {
        "amount": float,
        "tax_amount": float,
        "tax_amount_type": "fixed"|"percent",
        "tax_price_include": bool
    },
    ...
]}

對 `invoice_lines` 的驗證?

lines 是一個字典列表。每個字典代表一個發票行。字典鍵名說明了其含義。

{"lines": [
    {
        "description": string,
        "quantity": float,
        "unit_price": float,
        "product": string,
        "taxes_amount": float,
        "taxes": [
                    {
                        "amount": float,
                        "type": "fixed"|"percent",
                        "price_include": bool
                    },
                    ...
                ],
        "subtotal": float,
        "total": float
    },
    ...
]}

回應?

jsonrpc

Same as for /parse.

id

Same as for /parse.

result

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.

狀態碼	狀態消息
0	成功
12	驗證格式不正確

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "status_code": int,
        "status_msg": string,
    }
}

集成測試?

您可以通過在 /parse 請求中使用 integration_token 作為 account_token 來測試您的集成。

使用此令牌可將您置于測試模式，并允許您模擬整個流程，而無需解析文檔并且每次成功的發票解析不會被計費。

測試模式下唯一的技術差異是您發送的文檔不會被系統解析，而且您從 /get_results 得到的響應是硬編碼的。

可以在這里找到完整流程的Python實現： 這里 。

Edit on GitHub

提取 API?

發票?

預期成功的流程?

路線?

/iap/invoice_extract/parse?

描述?

請求正文?

回應?

/iap/invoice_extract/get_results?

描述?

請求正文?

回應?

feature_result?

candidate?

invoice_lines 功能的 feature_result?

/iap/invoice_extract/validate?

描述?

請求正文?

validation?

global_taxes 的驗證?

對 invoice_lines 的驗證?

回應?

集成測試?

`/iap/invoice_extract/parse`?

`/iap/invoice_extract/get_results`?

`feature_result`?

`candidate`?

`invoice_lines` 功能的 `feature_result`?

`/iap/invoice_extract/validate`?

`validation`?

`global_taxes` 的驗證?

對 `invoice_lines` 的驗證?