Tài liệu này nhằm cung cấp giải thích về Scope (lĩnh vực quyền hạn) trong hệ thống ủy quyền ứng dụng eSignGlobal dành cho nhà phát triển đối tác sinh thái. Khi tích hợp ủy quyền ứng dụng, nhà phát triển cần đăng ký Scope tương ứng dựa trên nhu cầu chức năng nghiệp vụ thực tế. Mỗi Scope bao gồm danh sách các OpenAPI được phép gọi trong lĩnh vực quyền hạn đó, và nền tảng sẽ nghiêm ngặt kiểm soát quyền thao tác của ứng dụng đối với các tài nguyên liên quan dựa trên Scope đã được ủy quyền.
Giao diện xác thực cơ bản
Trước khi ứng dụng sinh thái chính thức gọi giao diện, cần phải lấy thông tin xác thực gọi thông qua điểm cuối ủy quyền trước:
Tên giao diện
Đường dẫn giao diện
Mô tả giao diện
Lấy AccessToken
POST /esignglobal/v1/oauth2/accessToken
Thông qua appid và appsecret để lấy access_token xác thực, dùng để yêu cầu API eSignGlobal dưới danh nghĩa người dùng cụ thể, thời gian hiệu lực của Token là 24 giờ.
Hiện nay, các lĩnh vực quyền hạn Scope mở rộng trong hệ sinh thái eSignGlobal chủ yếu bao gồm:
signature: Dịch vụ cốt lõi chữ ký điện tử
stamp: Dịch vụ quản lý con dấu
comparisons: Dịch vụ so sánh hợp đồng
2. Chi tiết Scope và danh sách giao diện
2.1 Scope: signature (Dịch vụ chữ ký điện tử)
Scope này là vùng quyền hạn cơ bản và thường dùng nhất, bao gồm các giao diện cốt lõi trên toàn bộ chuỗi quy trình nghiệp vụ chữ ký điện tử. Khi được cấp quyền Scope này, ứng dụng có thể quản lý và vận hành luồng phong bì chính đối với mẫu, tài liệu ký (kèm tệp đính kèm), các bên tham gia.
Mô-đun 1: Dịch vụ mẫu
Tên giao diện
Mô tả giao diện
Lấy chi tiết thành phần mẫu của người ký
Lấy thông tin thành phần mẫu và cấu hình thuộc tính tương ứng của người ký chỉ định
Lấy chi tiết mẫu
Lấy thông tin đầy đủ của mẫu cụ thể, bao gồm chi tiết trường dữ liệu và cấu trúc tệp
Điền thông tin vào mẫu để tạo tệp
Dựa trên mẫu đã cho, điền dữ liệu nghiệp vụ và tự động tạo tệp định dạng PDF
Tra cứu danh sách mẫu
Tra cứu danh sách mẫu khả dụng của tài khoản hiện tại theo phân trang hoặc theo điều kiện lọc cụ thể
Tra cứu chi tiết nhiệm vụ tạo tệp
Tra cứu kết quả thực thi cuối cùng của tác vụ tạo tệp từ mẫu thông qua ID tác vụ bất đồng bộ
Mô-đun 2: Quản lý tệp
Tên giao diện
Mô tả giao diện
Tải tệp lên
Tải các tệp cục bộ hoặc tệp thuộc luồng nghiệp vụ được chỉ định lên nền tảng để sử dụng cho việc ký kết sau này
Lấy tọa độ dựa trên từ khóa
Tìm kiếm văn bản trong tài liệu đã tải lên và trả về thông tin tọa độ vị trí của từ khóa khớp
Tải tệp xuống
Tải xuống các tài liệu đã ký hoàn tất cụ thể, tệp nguồn hoặc các tệp phụ trợ nghiệp vụ khác
Thêm tệp ký
Gán các tệp đã tải lên thành công trước đó vào phong bì ký hoặc quy trình cụ thể
Xóa tệp ký
Loại bỏ các tệp bị tải nhầm hoặc tạm thời không cần ký khỏi quy trình phong bì
Thêm tệp đính kèm
Thêm tài liệu đính kèm giải thích mang tính bổ sung vào quy trình phong bì hoặc ký kết
Xóa tệp đính kèm
Gỡ bỏ tài liệu đính kèm được chỉ định khỏi quy trình phong bì hoặc ký kết
Mô-đun 3: Quản lý bên tham gia
Tên giao diện
Mô tả giao diện
Thêm người ký
Thêm bên tham gia ký kết cần thực hiện thao tác ký trong một quy trình phong bì cụ thể
Xóa người ký
Gỡ bỏ bên ký kết đã bị loại bỏ khỏi quy trình phong bì cụ thể
Thêm người nhận sao chép
Thêm vai trò bên sao chép, chỉ nhận thông báo tiến độ và xem tài liệu đã hoàn tất ký kết cuối cùng
Xóa người nhận sao chép
Gỡ bỏ vai trò bên sao chép cụ thể
Mô-đun 4: Quản lý phong bì
Tên giao diện
Mô tả giao diện
Tạo phong bì nhanh
Nếu nền tảng tích hợp sử dụng giao diện này để tạo phong bì, sau khi hoàn tất ký kết, hệ thống sẽ tự động xử lý quy trình kết thúc, không cần gọi thủ công “Kết thúc phong bì”.
Tạo phong bì
Dùng để tạo phong bì ở trạng thái bản nháp, hỗ trợ cấu hình các tham số như chủ đề ký kết, cài đặt người ký, v.v.
Kích hoạt phong bì
Sau khi xác nhận tất cả tài liệu ký kết và người ký đều chính xác, chính thức gửi nhiệm vụ ký kết xuống hệ thống phía dưới.
Kết thúc phong bì
Kết thúc thủ công phong bì. Trước khi phong bì kết thúc, tất cả người ký phải hoàn thành ký kết; sau khi quy trình kết thúc, tài nguyên không thể chỉnh sửa.
Lấy địa chỉ ký kết
Lấy liên kết rút gọn độc quyền hoặc URL trang ký kết có thể tải trực tiếp dành cho người ký được chỉ định.
Tra cứu chi tiết phong bì
Lấy thông tin tổng quan của phong bì, tài liệu liên quan, người tham gia và trạng thái xử lý hiện tại.
Hủy phong bì
Người khởi tạo chủ động thu hồi một phong bì ký chưa hoàn tất toàn bộ
Nhắc nhở ký phong bì
Khi phong bì chưa hoàn tất việc ký, hỗ trợ gửi lời nhắc đến người ký hiện tại cần ký nhưng chưa ký, khoảng thời gian nhắc là 30 phút
Lấy địa chỉ trang xem trước khi ký
Sau khi mở phong bì, có thể sử dụng API này để lấy địa chỉ trang xem trước khi ký. Chủ yếu dùng trong nền tảng tích hợp để cho phép người không tham gia phong bì xem tài liệu ký và tiến độ.
Tạo chế độ xem gửi phong bì
Tạo chế độ xem người gửi phong bì thông qua ID phong bì. Quy trình ký được khởi tạo dưới chế độ xem này sẽ điền thông tin người khởi tạo bằng thông tin người dùng được trích xuất từ Access Token trong OAuth.
2.2 Scope: stamp (Dịch vụ quản lý con dấu)
Scope này chuyên dành cho ủy quyền quản lý con dấu doanh nghiệp hoặc con dấu tên cá nhân. Phù hợp với hệ sinh thái bên thứ ba chỉ cần duy trì cơ sở dữ liệu con dấu thống nhất của doanh nghiệp (thêm, xóa, sửa, tra cứu con dấu) mà không cần trực tiếp can thiệp vào quy trình khởi tạo ký.
Tên API
Mô tả API
Tra cứu danh sách con dấu
Sử dụng AppID có quyền tra cứu con dấu tương ứng để lấy dữ liệu danh sách tài nguyên con dấu.
Tạo con dấu
Sử dụng AppID có quyền, tạo con dấu thông qua chuỗi mã hóa Base64 của hình ảnh tải lên (hỗ trợ PNG, kích thước 18mm-100mm).
Chỉnh sửa con dấu
Sửa đổi các thông tin như tên và hình ảnh của con dấu đã được tạo.
Xóa con dấu
Xóa hoàn toàn tài nguyên con dấu đã chỉ định và không còn liên quan đến nghiệp vụ.
2.3 Scope: comparisons (Dịch vụ so sánh hợp đồng)
Scope này chuyên dành cho lĩnh vực chức năng pháp lý hợp đồng thông minh. Cho phép ứng dụng đối tác hệ sinh thái linh hoạt gọi khả năng so sánh văn bản và phiên bản trong giai đoạn thẩm định hợp đồng và đánh giá pháp lý của riêng mình, giúp nắm bắt nhanh chóng các điểm khác biệt trước và sau khi chỉnh sửa hợp đồng.
Tên giao diện
Mô tả giao diện
Lấy trang kết quả so sánh hợp đồng
Lấy địa chỉ trang trực quan hóa hiển thị kết quả so sánh sự khác biệt
Tra cứu chi tiết so sánh hợp đồng
Lấy kết quả so sánh hợp đồng thông qua ID nghiệp vụ so sánh hợp đồng, bao gồm số lượng chênh lệch (số lượng thêm, xóa, sửa) và nội dung chi tiết về các điểm khác biệt (định vị chi tiết).
