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.
- 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. - 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, jpg và bmp.
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 |
|
Phiên bản không được hỗ trợ |
|
Đã xảy ra lỗi |
|
Bạn không có đủ tín dụng |
|
Định dạng tập tin không được hỗ 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 |
|
Phiên bản không được hỗ trợ |
|
Đã xảy ra lỗi |
|
Server hiện đang bảo trì, vui lòng thử lại sau |
|
Không thể tìm thấy tài liệu |
|
Tài liệu đã bị từ chối vì nó quá nhỏ |
|
Không thể lấy số trang của tệp PDF |
|
Không thể chuyển đổi PDF thành hình ảnh |
|
Tệp PDF được bảo vệ bằng mật khẩu |
|
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 |
---|---|
|
Nó chứa thông tin về mã SWIFT được phát hiện (hoặc BIC). Phím:
Tên và thành phố chỉ hiển thị nếu verify_bic là đúng. |
`` iban`` |
|
`` aba`` |
|
|
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`` |
|
|
|
|
Sử dụng |
|
|
|
|
|
Định dạng: YYYY-MM-DD |
|
Tương tự với |
|
|
|
|
`` tổng phụ`` |
|
`` tổng '' |
|
|
|
|
|
|
|
|
|
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ả`` |
|
|
|
|
|
`` tổng '' |
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
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
.