API Keys

1. Quản lý API Key

Trong Docbase, vào phần Cài đặt → API Keys. Ở đây, bạn có thể quản lý danh sách các API keys đã được tạo.

Bạn tạo mới 1 API Key bằng cách nhấp chuột vào nút Thêm API Key. Khi đó, màn hình tạo API Key sẽ hiện ra.

Các thông tin cần cung cấp khi tạo 1 API Key bao gồm:

Tên API Key.
Quyền: Docbase API Key hỗ trợ 2 quyền: Read và Write đối với dữ liệu trong thư mục tương ứng đươc gán vào API Key.
Thư mục: Chọn các thư mục để sử dụng API Key.

2. Cơ chế xác thực của API Key

Sử dụng Basic Authentication để xác thực quyền truy cập vào API.

Các tham số:

Username: sử dụng API Key lấy trên hệ thống
Password: bỏ trống

Cách hoạt động: Client gửi HTTP requests cùng với Authorization header chứa Basic theo sau là một khoảng trắng và một mã hoá Base64 username:password. Ví dụ, demo:p@55w0rd client sẽ gửi:

Copied

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Ví dụ về sử dụng API KEY thông qua postman:

3. Loại dữ liệu được sử dụng

Các dữ liệu trong văn bản sẽ là các thông tin về ô dữ liệu đó. Với mỗi loại tài liệu, các thông tin, gọi chung là Data, sẽ được chia thành các loại cấp bậc dữ liệu khác nhau dựa theo đặc điểm của tài liệu đó. Các cấp bậc được này được chia thành 4 kiểu lần lược là Section, Table, Row và Datapoint.

Datapoint là dạng dữ liệu thấp nhất của từng dữ liệu đọc được trong tài liệu.Datapoint sẽ chứa các thông tin chi tiết về kết quả OCR và gía trị của các ô dữ liệu đó.

Section sẽ gồm nhiều Datapoint có liên quan đến nhau được nhóm lại tùy theo từng loại tài liệu. (Ví dụ như 1 tài liệu hóa đơn sẽ có những thông tin như ngày hóa đơn, mẫu số, số ký hiệu, số hóa đơn, … Mỗi thông tin sẽ là 1 Datapoint và được gom lại với nhau thành Section Thông tin hóa đơn).

Table là kiểu dữ liệu dạng bảng. Table sẽ chứa nhiều hàng (row) và mỗi ô trong giá trị trong từng hàng sẽ được tính là 1 Datapoint. (Ví dụ: Bảng hóa đơn sẽ gồm các cột như tên hàng hóa, đơn vị tính, số lượng,… và gồm nhiều dòng dữ liệu. Mỗi ngăn trong bảng sẽ là một datapoint chứa thông tin và giá trị của dữ liệu đó).

3.1 Data

Copied
{
  "id": "aefc17a7-8318-4180-ab28-482d55dc22cc",
  "service_label": {
      "id": "232bb139-f411-4bfc-b63b-f4e5aad96dcd",
      "created_at": "2024-04-26T08:54:55.396569Z",
      "updated_at": "2024-04-26T08:54:55.396590Z",
      "deleted_at": null,
      "label": "invoice_data",
      "display_name": "Thông tin hóa đơn",
      "default": true,
      "enable": true,
      "ordering": 0,
      "data_type": "string",
      "format": null,
      "constraint": "required",
      "category": "section",
      "capitalize_type": "default",
      "box": null,
      "document_template": "c44b7565-7116-4600-a6ff-6d84dbddad60",
      "parent": null
  },
  "created_at": "2024-05-06T08:37:40.924170Z",
  "updated_at": "2024-05-06T08:37:40.924196Z",
  "deleted_at": null,
  "ocr_value": null,
  "value": null,
  "last_ocr_value": null,
  "normalized_value": null,
  "confidence_score": null,
  "status": "for_review",
  "category": "section",
  "box": null,
  "lookup_verified": null,
  "row_idx": null,
  "value_confirmation": null,
  "value_approval": null,
  "merchandise": null,
  "page": "a5c39172-40d1-412b-a531-d4449ae80477",
  "document": "27d72697-1076-452b-8d85-8f437979e68d",
  "parent": null,
  "data_set":[]
}

Cấu trúc của 1 ô dữ liệu trong 1 văn bản sẽ có những thông tin quan trọng như:

id: ID của ô dữ liệu
service_label: Chứa thông tin về nhãn của ô dữ liệu đó, gồm các thông tin như: -label: Nhãn của ô dữ liệu (VD: invoice_data)
- display_name: Tên hiển thị của nhãn đó (VD: Thông tin hóa đơn)
- category: Loại kiểu dữ liệu, sẽ là 1 trong 4 kiểu dữ liệu được đề cập dến ở phần a.
- constraint: Nếu giá trị là “required” nghĩa là trường dữ liệu này là bắt buộc cần điền để xác nhận hồ sơ.
value: Giá trị hiện tại của ô dữ liệu
box: Danh sách 4 phần tử là vị trí 4 đỉnh của vùng trên tài liệu mà đọc được dữ liệu
confidence_score: Độ tin cậy của dữ liệu
ocr_value: Dữ liệu đọc được từ quá trình OCR
normalized_value: Dữ liệu được định dạng lại sao cho hợp lý
value: Dữ liệu cuối cùng, khi người dùng thay đổi dữ liệu của các giấy tờ trong tài liệu sẽ thay đổi giá trị này
page: UUID của trang chứa vùng dữ liệu
parent: UUID của dữ liệu cha
data_set: Nếu là kiểu dữ liệu section, table hay row sẽ có các trường con, vậy nên data_set sẽ là danh sách của các Data con của dữ liệu Data này.

3.2. Datapoint

Copied
{
    "id": "101cfb31-b110-46bc-91b8-29abc02dfc4c",
    "submission_field": {
        "id": "8f55f8c0-e8a2-4159-8763-62bcc7674f60",
        "created_at": "2024-04-26T08:54:55.480396Z",
        "updated_at": "2024-04-26T08:54:55.482287Z",
        "deleted_at": null,
        "label": "date",
        "name": "Ngày",
        "ordering": 1,
        "data_type": "date",
        "format": null,
        "category": "datapoint",
        "rir_labels_json": [
            {
                "label": "date",
                "document_type": "invoice"
            }
        ],
        "enable": true,
        "required": true,
        "select_strategy": "order",
        "can_delete": true,
        "editable": true,
        "folder": "fd38c314-e9ce-4794-be0d-db091f96a962",
        "parent": "6e30e16b-79a0-40e4-83fd-2a8beb0a8690"
    },
    "created_at": "2024-05-06T08:37:52.002558Z",
    "updated_at": "2024-05-06T08:37:52.009851Z",
    "deleted_at": null,
    "value": "23/03/2021",
    "category": "datapoint",
    "box": null,
    "confidence_score": null,
    "data": "5349aa70-ae95-4ff2-a83e-cbea7800cfea",
    "submission": "5138c6f9-0ed5-4a06-90ed-8ef0a8bf2430",
    "parent": "be12172c-4c52-42f2-a6a7-ea2a7d5e2d55",
    "page": null,
    "data_source": []
}

Các thông tin quan trọng trong datapoint gồm:

category: Loại dữ liệu sẽ có giá trị là “datapoint”
data: UUID của data
datasource: Danh sách chứa 1 phần tử, mô tả dữ liệu đọc được từ quá trình OCR. Trong phần tử đầu tiên sẽ chứa các thông tin tương tự phần Data
submission_field: Chứa các thông tin về tên và nhãn của kiểu dữ liệu
- editable: Chỉnh sửa được hay không
- label: Nhãn của dữ liệu (vd: serial_no)
- name: Tên nhãn của dữ liệu (vd: Số ký hiệu hóa đơn)
- required: Bắt buộc hay không
- ordering: Số thứ tự của dữ liệu này trong tài liệu
parent: UUID của dữ liệu cha chứa dữ liệu
value: Giá trị của trường dữ liệu, , khi người dùng thay đổi dữ liệu sẽ thay đổi giá trị này

3.3 Section

Copied
{
  "id": "be12172c-4c52-42f2-a6a7-ea2a7d5e2d55",
  "submission_field": {
      "id": "6e30e16b-79a0-40e4-83fd-2a8beb0a8690",
      "created_at": "2024-04-26T08:54:55.476267Z",
      "updated_at": "2024-04-26T08:54:55.478421Z",
      "deleted_at": null,
      "label": "invoice_data",
      "name": "Thông tin hóa đơn",
      "ordering": 0,
      "data_type": "string",
      "format": null,
      "category": "section",
      "rir_labels_json": [],
      "enable": true,
      "required": false,
      "select_strategy": "order",
      "can_delete": true,
      "editable": true,
      "folder": "fd38c314-e9ce-4794-be0d-db091f96a962",
      "parent": null
  },
  "created_at": "2024-05-06T08:37:51.679976Z",
  "updated_at": "2024-05-06T08:37:51.680002Z",
  "deleted_at": null,
  "value": null,
  "category": "section",
  "box": null,
  "confidence_score": null,
  "data": null,
  "submission": "5138c6f9-0ed5-4a06-90ed-8ef0a8bf2430",
  "parent": null,
  "page": null,
  "data_source": [],
  "field_data_set": []
}

Các thông tin quan trọng trong Section gồm:

category: Loại dữ liệu sẽ có giá trị là “section”
submission_field: Tên và nhãn của Section, tương tự Datapoint
field_data_set: Danh sách các trường dữ liệu con hay chính là các Datapoint trong section này

3.4 Row

Các trường tương tự như phần Section. Như mô tả ở trên, ý nghĩa của hàng là để gộp những dữ liệu cho 1 hàng trong bảng nên sẽ có các trường giống với phần Section.

Lưu ý là trường category sẽ có giá trị là “row”

3.5 Table

Các trường tương tự như phần Section. Table là dữ liệu dạng bảng của 1 tài liệu, vì vậy điểm khác biệt so với Section và Row là trường field_data_set sẽ là danh sách của các Row – hàng trong bảng

Lưu ý trường category cũng sẽ có giá trị là “table”

4. Các api sử dụng API Keys

Docbase hiện hỗ trợ upload các định dạng tệp dạng png, jpg, jpeg, pdf, zip, xml. Tổng dung lượng của tệp trong 1 api không quá 60MB.

4.1 Upload tệp (đối với API key gán quyền Write)

a. Upload tệp

API:

Method	URL	content-type
`POST`	`https://app.docbase.ai/api/v1/folders/<folder_id>/submissions`	`multipart/form-data`

Body:

Key	Type	Mô tả
`files`	file	Tệp upload lên thư mục của Docbase (có thể upload nhiều tệp 1 lúc)

b. Upload nhiều ảnh của cùng 1 tệp

API:

Method	URL	content-type
`POST`	`https://app.docbase.ai/api/v1/folders/<folder_id>/images`	`multipart/form-data`

Body:

Key	Type	Mô tả
`files`	file	Các ảnh trong cùng 1 tệp

Response:

Copied
{
  "success_file_ids": ["c80f62ea-774c-4bc5-9f9e-b0062b61828e"],
  "error_file_name": []
}

4.2 Lấy về tệp (đối với API key gán quyền Read)

a. Lấy về tệp (không kèm dữ liệu)

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/submissions/<submission_id>`

Response:

Copied
{
    "id": "5138c6f9-0ed5-4a06-90ed-8ef0a8bf2430",
    "created_at": "2024-05-06T08:37:33.102602Z",
    "updated_at": "2024-08-07T04:03:00.708027Z",
    "last_ocr_time": "2024-05-06T08:37:33.102472Z",
    "deleted_at": null,
    "name": "Hoa_don",
    "status": "for_review",
    "ocr_error_code": null,
    "note": null,
    "reviewing": false,
    "sorted_documents": null,
    "last_export_time": null,
    "turnaround_time": null,
    "validate_time": null,
    "edit_rate": null,
    "validated_at": null,
    "auto_verified": false,
    "upload_source": "web",
    "message_id": null,
    "folder": "fd38c314-e9ce-4794-be0d-db091f96a962",
    "validated_by": null,
    "owner": "537004c7-c79f-450c-9a4a-751cc5ba9644",
    "validator": null,
    "rejected_by": null,
    "reviewing_by": null,
    "documents_count": 1,
    "files_count": 1,
    "unclassified_pages_count": 0,
    "unclassified_files": [],
    "documents": [...],
    "files": [...]
    "pages_count": 1
}

Ví dụ cho trường documents

Copied
"documents": [
  {
      "id": "27d72697-1076-452b-8d85-8f437979e68d",
      "page_set": [
          "a5c39172-40d1-412b-a531-d4449ae80477",
          "1d08d58f-5462-4afe-b922-71fe0986c153"
      ],
      "created_at": "2024-05-06T08:37:40.914655Z",
      "updated_at": "2024-05-06T08:37:40.914680Z",
      "deleted_at": null,
      "name": "Hóa đơn",
      "status": "for_review",
      "last_data_changed": null,
      "note": null,
      "ocr_error_code": "0",
      "last_validated_at": null,
      "last_verified_at": null,
      "sorted_pages": null,
      "document_type": "invoice",
      "archived": false,
      "submission": "5138c6f9-0ed5-4a06-90ed-8ef0a8bf2430",
      "users": []
  }
]

Ví dụ cho trường files

Copied
"files": [
    {
        "id": "94a1d7d1-ac0b-4396-99d2-a11337200b85",
        "created_at": "2024-05-06T08:37:33.106847Z",
        "updated_at": "2024-05-06T08:37:33.106867Z",
        "deleted_at": null,
        "name": "Hoa_don.jpg",
        "path": "files/01f5ada6-22b1-4b69-a510-fb87967eacf5/fd38c314-e9ce-4794-be0d-db091f96a962/origins/487d8a98-d736-4c13-9d2c-d728177f656f.jpg",
        "extension": "jpg",
        "mime_type": null,
        "thumbnail_path": null,
        "size": 207235,
        "input_email": null,
        "submission": "5138c6f9-0ed5-4a06-90ed-8ef0a8bf2430",
        "org": "01f5ada6-22b1-4b69-a510-fb87967eacf5"
    }
],

Các trường thông tin quan trọng gồm:

documents_count: Số văn bản tài liệu đọc được (hóa đơn, bảng kê, giấy tờ, ...)
files_count: Số file của bộ hồ sơ
pages_count: Tổng số trang tài liệu của bộ hồ sơ
unclassified_pages_count: Số trang tài liệu không xác định được,
documents: Danh sách của văn bản tài liệu, mỗi phần tử trong danh sách sẽ gồm các thông tin như:
- name: Tên văn bản tài liệu
- document_type: Loại văn bản tài liệu
- page_set: Các trang trong văn bản tài liệu này. Các văn bản có dữ liệu dạng bảng sẽ được đính kèm thêm trang ảnh là phần văn bản có bảng. Danh sách này là danh sách các ID của trang văn bản.
files: Danh sách các tệp trong bộ tài liệu, mỗi phần tử trong danh sách gồm các thông tin như:
- id: ID của tệp tài liệu
- name: Tên tệp tài liệu
- size: Độ lớn về dung lượng của tệp
unclassified_files: Danh sách các tệp không xác định trong bộ tài liệu

b. Lấy về tệp (có kèm dữ liệu)

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/submissions/<submission_id>/data`

Response:

Cấu trúc trả về tương tự phần a., tuy nhiên ở trong phần documents, sẽ có thêm 1 trường là data_set: là 1 danh sách của các dữ liệu đọc được trong văn bản.

Copied

{
...,
"documents": [
        {
            "id": "27d72697-1076-452b-8d85-8f437979e68d",
	          ...,
            "users": [],
            "data_set": []
    }
  ]
}

Data set là các dữ liệu trong một văn bản tài liệu, sẽ gồm các dữ liệu Data được phân chia theo dạng cây với các kiểu dữ liệu được đề cập ở phần Kiểu dữ liệu.

c. Lấy về nhiều tệp (không kèm dữ liệu)

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/folders/<folder_id>/submissions`

Params:

Key	Mô tả/Giá trị
`limit`	Giới hạn số tệp lấy về
`offset`	Số trang, bắt đầu từ 0
`search`	Tìm kiếm theo tên
`status`	`for_review`/`process_error`/`for_verify`/`verified`/`processing`/`exported`
`start`	Chặn trên của ngày tải lên
`end`	Chặn dưới của ngày tải lên

Response:

d. Lấy về thông tin chung của bộ hồ sơ

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/submissions/<submission_id>/general-data`

Response:

Response Câu trúc trả về gồm:

count: Số tệp
next: URL cho trang tiếp theo
previous: URL cho trang trước
results: Danh sánh thông tin các tệp, mỗi phần tử trong danh sách sẽ có giá trị tương tự phần response của phần a.

e. Lấy về ảnh của tệp

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/files/<file_id>/document`

Response:

Dạng ảnh của tệp

f. Lấy về ảnh của từng trang trong tệp

API:

Method	URL
`GET`	`https://app.docbase.ai/api/v1/pages/<page_id>/photo`

Response:

Dạng ảnh của từng trang trong tệp

Chú ý tham số:

Key	Mô tả
`folder_id`	id của thư mục lấy trên hệ thống Để lấy id của thư mục: Vào Tài liệu → {{Thư mục bất kỳ}} → Cài đặt ID của thư mục sẽ xuất hiện trong mục Thông tin thư mục
`file_id`	id của tệp lấy trên hệ thống
`page_id`	id của trang lấy trên hệ thống

Hướng dẫn sử dụng

OCR Keys

Tích hợp

API Keys

1. Quản lý API Key

2. Cơ chế xác thực của API Key

3. Loại dữ liệu được sử dụng

3.1 Data

3.2. Datapoint

3.3 Section

3.4 Row

3.5 Table

4. Các api sử dụng API Keys

4.1 Upload tệp (đối với API key gán quyền Write)

a. Upload tệp

b. Upload nhiều ảnh của cùng 1 tệp

4.2 Lấy về tệp (đối với API key gán quyền Read)

a. Lấy về tệp (không kèm dữ liệu)

b. Lấy về tệp (có kèm dữ liệu)

c. Lấy về nhiều tệp (không kèm dữ liệu)

d. Lấy về thông tin chung của bộ hồ sơ

e. Lấy về ảnh của tệp

f. Lấy về ảnh của từng trang trong tệp