Trích xuất API

SoOn cung cấp dịch vụ tự động hóa việc xử lý các loại tài liệu hóa đơn, chi phí hoặc sơ yếu lý lịch.

Dịch vụ này quét tài liệu bằng công cụ OCR và sau đó sử dụng các thuật toán dựa trên AI để trích xuất các trường quan tâm như tổng số tiền, ngày đến hạn hoặc dòng hóa đơn đối với hóa đơn, tổng số, ngày đối với chi phí hoặc tên, email, số điện thoại đối với sơ yếu lý lịch.

Dịch vụ này là một dịch vụ trả phí. Mỗi lần xử lý tài liệu sẽ tiêu tốn của bạn một khoản tín dụng. Bạn có thể mua tín dụng trên iap.odoo.com.

Bạn có thể sử dụng dịch vụ này trực tiếp trong Ứng dụng Kế toán, Chi phí hoặc Tuyển dụng hoặc thông qua API. API trích xuất, được trình bày chi tiết trong phần tiếp theo, cho phép bạn tích hợp dịch vụ của chúng tôi trực tiếp vào các dự án của riêng bạn.

Tổng quan

API trích xuất sử dụng giao thức JSON-RPC2; các tuyến điểm cuối của nó được đặt tại https://extract.api.odoo.com.

Phiên bản

Phiên bản của API trích xuất được chỉ định trong tuyến đường.

Các phiên bản mới nhất là:
  • hóa đơn: 122

  • chi phí: 132

  • người nộp đơn: 102

Chảy

Quy trình giống nhau đối với từng loại tài liệu.

  1. Gọi /parse để gửi tài liệu của bạn (một cuộc gọi cho mỗi tài liệu). Khi thành công, bạn sẽ nhận được document_token trong phản hồi.
  2. Sau đó, bạn phải thường xuyên thăm dò /get_result để biết trạng thái phân tích cú pháp của tài liệu.
    Ngoài ra, bạn có thể cung cấp webhook_url tại thời điểm gọi tới /parse và bạn sẽ được thông báo (thông qua yêu cầu POST) khi kết quả đã sẵn sàng.

Phương thức HTTP POST nên được sử dụng cho tất cả chúng. Bạn có thể tìm thấy cách triển khai python của toàn bộ quy trình cho hóa đơn tại đây và mã thông báo để kiểm tra tích hợp được cung cấp trong phần kiểm tra tích hợp.

Phân tích cú pháp

Yêu cầu xử lý tài liệu từ OCR. Tuyến đường sẽ trả về document_token, bạn có thể sử dụng nó để nhận kết quả yêu cầu của mình.

Tuyến đường

  • /api/trích xuất/hóa đơn/2/parse

  • /api/trích xuất/chi phí/2/parse

  • /api/trích xuất/người nộp đơn/2/parse

Lời yêu cầu

jsonrpc (bắt buộc)

xem JSON-RPC2

phương thức (bắt buộc)

xem JSON-RPC2

id (bắt buộc)

xem JSON-RPC2

thông số
account_token (bắt buộc)

Mã thông báo của tài khoản mà tín dụng sẽ được lấy. Mỗi cuộc gọi thành công tốn một mã thông báo.

phiên bản (bắt buộc)

Phiên bản sẽ xác định định dạng yêu cầu của bạn và định dạng phản hồi của máy chủ. Bạn nên sử dụng phiên bản mới nhất có sẵn.

``tài liệu``(bắt buộc)

Tài liệu phải được cung cấp dưới dạng chuỗi trong mã hóa ASCII. Danh sách chỉ nên chứa một chuỗi. Nếu nhiều chuỗi được cung cấp thì chỉ chuỗi đầu tiên tương ứng với tệp pdf sẽ được xử lý. Nếu không tìm thấy pdf, chuỗi đầu tiên sẽ được xử lý. Trường này chỉ là danh sách vì lý do cũ. Các tiện ích mở rộng được hỗ trợ là pdf, png, jpgbmp.

dbuuid (tùy chọn)

Mã định danh duy nhất của cơ sở dữ liệu SoOn.

webhook_url (tùy chọn)

Một URL webhook có thể được cung cấp. Một yêu cầu POST trống sẽ được gửi đến webhook_url/document_token khi kết quả đã sẵn sàng.

user_infos (tùy chọn)

Thông tin liên quan đến người gửi tài liệu đến dịch vụ trích xuất. Có thể là khách hàng hoặc nhà cung cấp (tùy vào góc nhìn). Thông tin này không bắt buộc để dịch vụ hoạt động nhưng nó cải thiện đáng kể chất lượng của kết quả.

user_company_vat (tùy chọn)

Mã số VAT của người sử dụng.

user_company_name (tùy chọn)

Tên công ty của người dùng.

user_company_country_code (tùy chọn)

Mã quốc gia của người dùng. Định dạng: ISO3166 alpha-2.

user_lang (tùy chọn)

Ngôn ngữ người dùng. Định dạng: ngôn ngữ_code + _ + ngôn ngữ (ví dụ: fr_FR, en_US).

user_email (tùy chọn)

Email người dùng.

purchase_order_regex (tùy chọn)

Regex để nhận dạng đơn đặt hàng. Sẽ mặc định ở định dạng SoOn PO nếu không được cung cấp.

phối cảnh (tùy chọn)

Có thể là khách hàng hoặc ''nhà cung cấp``. Trường này chỉ hữu ích cho hóa đơn. khách hàng có nghĩa là thông tin người dùng được cung cấp có liên quan đến khách hàng của hóa đơn. nhà cung cấp có nghĩa là nó liên quan đến nhà cung cấp. Nếu không được cung cấp, khách hàng sẽ được sử dụng.

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

Ghi chú

Tham số user_infos là tùy chọn nhưng nó cải thiện đáng kể chất lượng của kết quả, đặc biệt là đối với hóa đơn. Bạn càng có thể cung cấp nhiều thông tin thì càng tốt.

Phản ứng

jsonrpc

xem JSON-RPC2

id

xem JSON-RPC2

kết quả
trạng thái

Mã cho biết trạng thái của yêu cầu. Xem bảng dưới đây.

thông báo trạng thái

Một chuỗi cung cấp chi tiết chi tiết về trạng thái yêu cầu.

tài liệu_token

Chỉ hiện diện nếu yêu cầu thành công.

trạng thái

trạng thái_tin nhắn

thành công

Thành công

error_unsupported_version

Phiên bản không được hỗ trợ

lỗi_internal

Đã xảy ra lỗi

lỗi_no_credit

Bạn không có đủ tín dụng

error_unsupported_format

Định dạng tập tin không được hỗ trợ

lỗi_bảo trì

Server hiện đang bảo trì, vui lòng thử lại sau

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

Ghi chú

API không thực sự sử dụng sơ đồ lỗi JSON-RPC. Thay vào đó, API có sơ đồ lỗi riêng được gói bên trong kết quả JSON-RPC thành công.

Nhận kết quả

Tuyến đường

  • /api/trích xuất/hóa đơn/2/get_result

  • /api/trích xuất/chi phí/2/get_result

  • /api/trích xuất/người nộp đơn/2/get_result

Lời yêu cầu

jsonrpc (bắt buộc)

xem JSON-RPC2

phương thức (bắt buộc)

xem JSON-RPC2

id (bắt buộc)

xem JSON-RPC2

thông số
phiên bản (bắt buộc)

Phiên bản phải khớp với phiên bản được chuyển đến yêu cầu /parse.

document_token (bắt buộc)

document_token mà bạn muốn nhận trạng thái phân tích cú pháp hiện tại.

account_token (bắt buộc)

Mã thông báo của tài khoản đã được sử dụng để gửi tài liệu.

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

Phản ứng

Khi nhận được kết quả từ phân tích cú pháp, trường được phát hiện sẽ thay đổi rất nhiều tùy thuộc vào loại tài liệu. Mỗi phản hồi là một danh sách các từ điển, một từ điển cho mỗi tài liệu. Các khóa của từ điển là tên của trường và giá trị là giá trị của trường.

jsonrpc

xem JSON-RPC2

id

xem JSON-RPC2

kết quả
trạng thái

Mã cho biết trạng thái của yêu cầu. Xem bảng dưới đây.

thông báo trạng thái

Một chuỗi cung cấp chi tiết chi tiết về trạng thái yêu cầu.

kết quả

Chỉ hiện diện nếu yêu cầu thành công.

full_text_annotation

Chứa kết quả đầy đủ chưa được xử lý từ OCR cho tài liệu

trạng thái

trạng thái_tin nhắn

thành công

Thành công

error_unsupported_version

Phiên bản không được hỗ trợ

lỗi_internal

Đã xảy ra lỗi

lỗi_bảo trì

Server hiện đang bảo trì, vui lòng thử lại sau

lỗi_tài liệu_không_tìm thấy

Không thể tìm thấy tài liệu

lỗi_không được hỗ trợ_kích thước

Tài liệu đã bị từ chối vì nó quá nhỏ

lỗi_no_trang_count

Không thể lấy số trang của tệp PDF

error_pdf_conversion_to_images

Không thể chuyển đổi PDF thành hình ảnh

lỗi_mật khẩu_được bảo vệ

Tệp PDF được bảo vệ bằng mật khẩu

error_too_many_pages

Tài liệu chứa quá nhiều trang

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

Các trường chung

kết quả tính năng

Mỗi trường quan tâm mà chúng ta muốn trích xuất từ tài liệu như tổng số hoặc ngày đến hạn cũng được gọi là tính năng. Bạn có thể tìm thấy danh sách đầy đủ tất cả các tính năng được trích xuất liên quan đến một loại tài liệu trong các phần bên dưới.

Đối với mỗi tính năng, chúng tôi trả về một danh sách các ứng cử viên và chúng tôi đánh dấu ứng cử viên mà mô hình của chúng tôi dự đoán là phù hợp nhất cho tính năng đó.

giá trị được chọn (tùy chọn)

Ứng cử viên tốt nhất cho tính năng này.

giá trị được chọn (tùy chọn)

Các ứng cử viên tốt nhất cho tính năng này.

ứng viên (tùy chọn)

Danh sách tất cả các ứng cử viên cho tính năng này được sắp xếp theo điểm tin cậy giảm dần.

"feature_name": {
    "selected_value": candidate_12,
    "candidates": [candidate_12, candidate_3, candidate_4, ...]
}
ứng viên

Đối với mỗi ứng cử viên, chúng tôi đưa ra sự đại diện và vị trí của họ trong tài liệu. Các ứng viên được sắp xếp theo mức độ phù hợp giảm dần.

nội dung

Đại diện của ứng viên.

`` coords``

[center_x, center_y, chiều rộng, chiều cao, góc quay]. Vị trí và kích thước tương ứng với kích thước của trang và do đó nằm trong khoảng từ 0 đến 1. Góc là một phép quay theo chiều kim đồng hồ được đo bằng độ.

trang

Trang của tài liệu gốc chứa ứng viên (bắt đầu từ 0).

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

Hóa đơn

Hóa đơn rất phức tạp và có thể có nhiều trường khác nhau. Bảng sau đây cung cấp danh sách đầy đủ tất cả các trường mà chúng tôi có thể trích xuất từ hóa đơn.

Tên tính năng

Đặc điểm kỹ thuật

SWIFT_code

content là một từ điển được mã hóa dưới dạng chuỗi.

Nó chứa thông tin về mã SWIFT được phát hiện (hoặc BIC).

Phím:

bi

đã phát hiện BIC (chuỗi).

tên (tùy chọn)

tên ngân hàng (chuỗi).

quốc gia

Mã quốc gia ISO3166 alpha-2 của ngân hàng (chuỗi).

thành phố (tùy chọn)

thành phố của ngân hàng (chuỗi).

đã xác minh_bic

Đúng nếu BIC đã được tìm thấy trong DB (bool) của chúng tôi.

Tên và thành phố chỉ hiển thị nếu verify_bic là đúng.

`` iban``

nội dung là một chuỗi

`` aba``

nội dung là một chuỗi

Số VAT

nội dung là một chuỗi

Tùy thuộc vào giá trị phối cảnh trong user_infos, đây sẽ là mã số VAT của nhà cung cấp hoặc khách hàng. Nếu phối cảnh là khách hàng thì đó sẽ là mã số VAT của nhà cung cấp. Nếu là nhà cung cấp thì đó là mã số VAT của khách hàng.

`` hóa đơn qr``

nội dung là một chuỗi

thanh toán_ref

nội dung là một chuỗi

đơn_hàng mua hàng

nội dung là một chuỗi

Sử dụng selected_values thay vì selected_value

đất nước

nội dung là một chuỗi

tiền tệ

nội dung là một chuỗi

ngày

nội dung là một chuỗi

Định dạng: YYYY-MM-DD

ngày_đến_hạn

Tương tự với ngày

tổng_số_thuế

nội dung là một float

invoice_id

nội dung là một chuỗi

`` tổng phụ``

nội dung là một float

`` tổng ''

nội dung là một float

nhà cung cấp

nội dung là một chuỗi

khách hàng

nội dung là một chuỗi

email

nội dung là một chuỗi

trang web

nội dung là một chuỗi

feature_result cho tính năng invoice_lines

Nó tuân theo một cấu trúc cụ thể hơn. Về cơ bản nó là một danh sách các từ điển trong đó mỗi từ điển đại diện cho một dòng hóa đơn. Mỗi giá trị tuân theo cấu trúc latestextrac_api/get_result/feature_result.

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

Chi phí

Các chi phí ít phức tạp hơn hóa đơn. Bảng sau đây cung cấp danh sách đầy đủ tất cả các trường mà chúng tôi có thể trích xuất từ báo cáo chi phí.

Tên tính năng

Đặc điểm kỹ thuật

`` mô tả``

nội dung là một chuỗi

đất nước

nội dung là một chuỗi

ngày

nội dung là một chuỗi

`` tổng ''

nội dung là một float

tiền tệ

nội dung là một chuỗi

Người xin việc

Loại tài liệu thứ ba này dùng để xử lý sơ yếu lý lịch. Bảng sau đây cung cấp danh sách đầy đủ tất cả các trường mà chúng tôi có thể trích xuất từ sơ yếu lý lịch.

Tên tính năng

Đặc điểm kỹ thuật

tên

nội dung là một chuỗi

email

nội dung là một chuỗi

điện thoại

nội dung là một chuỗi

di động

nội dung là một chuỗi

Thử nghiệm hội nhập

Bạn có thể kiểm tra sự tích hợp của mình bằng cách sử dụng integration_token làm account_token trong yêu cầu /parse.

Việc sử dụng mã thông báo này sẽ đưa bạn vào chế độ thử nghiệm và cho phép bạn mô phỏng toàn bộ quy trình mà không thực sự phân tích cú pháp tài liệu cũng như không bị tính phí một khoản tín dụng cho mỗi lần phân tích cú pháp tài liệu thành công.

Sự khác biệt kỹ thuật duy nhất trong chế độ kiểm tra là tài liệu bạn gửi không được hệ thống phân tích cú pháp và phản hồi bạn nhận được từ /get_result là một tài liệu được mã hóa cứng.

Bạn có thể tìm thấy cách triển khai python của toàn bộ quy trình cho hóa đơn tại đây.