Nền tảng tích hợp, chia sẻ liên thông kết nối chính quyền điện tử thành phố

Giải pháp thực hiện

I. TỔNG QUAN

1. Mục đích tài liệu

Tài liệu này hướng dẫn các đơn vị của BNĐP kết nối tới hệ thống NGSP thông qua Nền tảng HCM LGSP để thực hiện tra cứu thông tin Danh mục điện tử dùng chung.

2. Phạm vi và đối tượng áp dụng

Tài liệu này cung cấp các phương thức, đối tượng cho lập trình viên sử dụng để phát triển tích hợp ứng dụng đơn vị của BNĐP với các dịch vụ tra cứu của Danh mục điện tử dùng chung thông qua Nền tảng HCM LGSP.

3. Thông tin kết nối

Đơn vị cần kết nối liên hệ với Sở Thông tin và Truyền thông để được cung cấp thông tin kết nối bao gồm:
- AppName
- AccessKey
- SecretKey
- PartnerCode
- PartnerCodeCus

II. MÔ HÌNH KẾT NỐI

1. Mô hình kết nối

Hình 1: Mô hình kết nối

Nền tảng NGSP thực hiện chia sẻ thông tin về danh mục điện tử dùng chung cho Nền tảng HCM LGSP
Nền tảng HCM LGSP đảm nhiệm vai trò chính trong việc kết nối với Nền tảng NGSP để thực hiện chia sẻ dữ liệu danh mục điện tử dùng chung cho đơn vị thực hiện tra cứu.
API Tra cứu thông tin danh mục điện tử dùng chung hỗ trợ phần mềm tại đơn vị kết nối vào Nền tảng HCM LGSP để thực hiện tra cứu thông tin

2. Quá trình trao đổi gói tin

Hình 2: Quy trình trao đổi gói tin

Bước 1: Phần mềm của đơn vị gọi đến Nền tảng HCM LGSP thông qua api kèm theo access token.
Bước 2: Nền tảng HCM LGSP kiểm tra access token của đơn vị. Nếu thất bại sẽ trả về mã lỗi được mô tả như bên dưới

Mã lỗi <Error_Number>	Ý nghĩa
401	Sai thông tin xác thực
403	Tài khoản không có quyền truy cập API
429	Vượt quá số lượng request cho phép trong một đơn vị thời gian

Bước 3: Nền tảng HCM LGSP xử lý dữ liệu và trả về gói tin JSON kết quả cho phần mềm đơn vị.

III. ĐẶC TẢ API

1. Thông tin kết nối

Kiểu	Diễn giải	Ví dụ
Địa chỉ adapter Nền tảng HCM chính	Địa chỉ cổng dịch vụ chính thức	https://hcmlgsp.tphcm.gov.vn
Địa chỉ adapter Nền tảng HCM thử nghiệm	Địa chỉ cổng dịch vụ thử nghiệm	https://hcmesb-test.tphcm.gov.vn
AccessKey	Khóa	rTkhYCBwHM
SecretKey	Khóa bí mật	DWkQgY1YSS
AppName	Đơn vị kết nối	TPHCM
PartnerCode	Mã đơn vị cung cấp ứng dụng	000.00.01.H29
PartnerCodeCus	Mã đơn vị sử dụng dịch vụ	000.00.01.H29
lgspaccesstoken	Khai báo trong Header, Là chuỗi gồm 5 tham số dạng json được mã hóa thành StringBase64	ewoiQWNjZXNzS2V5IjoiclRraFlDQndITSIsCiJTZWNyZXRLZXkiOiJE V2tRZ1kxWVNTIiwKIkFwcE5hbWUiOiAiVFBIQ00iLAoiUGFydG5lck NvZGUiOiAiMDAwLjAwLjAxLkgyOSIsCiJQYXJ0bmVyQ29kZUN1cyI 6ICIwMDAuMDAuMDEuSDI5Igp9Cg== được stringbase64 từ: { "AccessKey":"rTkhYCBwHM", "SecretKey":"DWkQgY1YSS", "AppName": "TPHCM", "PartnerCode": "000.00.01.H29", "PartnerCodeCus": "000.00.01.H29" }

Bảng 1: Bảng thông tin kết nối

2. API lấy thông tin token

Đường dẫn: /dmdc/token
Method: POST
Đầu vào:
- Header:
  - Content-Type: application/x-www-form-urlencoded
  - lgspaccesstoken
- Body:
  - grant_type=client_credentials
Đầu ra:
- Chuỗi json chứa thông tin trả về

STT	Tên trường	Kiểu	Bắt buộc	Mô tả
	access_token	string	Có	Chuỗi token được cấp tương ứng với một phiên làm việc của một HTTT/LGSP
	token_type	string	Có	Kiểu token
	expires_in	int	Có	Thời gian token có hiệu lực (giây)

Bảng 2: Tham số chuỗi json trả về của API lấy thông tin token

Ví dụ:

{

"access_token": "7602fd18-9d6f-385d-b9c6-671609b5c078",

"scope": "am_application_scope default",

"token_type": "Bearer",

"expires_in": 3600

}

3. API lấy danh sách danh mục

Đường dẫn: /dmdc/st/1.0/AllCategory
Method: GET
Đầu vào:
- Header:
  - Authorization: Bearer {token} (token sinh ra từ API lấy thông tin token phía trên)
  - Content-Type: application/json
  - lgspaccesstoken
Đầu ra:
- Danh sách danh mục với thông tin phiên bản, số bản ghi, các endpoint của danh mục (Đối tượng trả ra List<CategoryInfo>)

Ví dụ:

<CategoryCode>DanhMucHeThongNganhSanPhamVietNamCap5</CategoryCode>

<CategoryName>Danh mục Hệ thống ngành sản phẩm Việt Nam cấp 5</CategoryName>

<ServiceName>DanhMucHeThongNganhSanPhamVietNamCap5</ServiceName>

<UrlDublinCoreMetadata>http://dmdc/st.ngsp.gov.vn/svc/NGSP.svc/DublinCoreMetadata/DanhMucHeThongNganhSanPham

VietNamCap5</UrlDublinCoreMetadata>

<UrlMetadata>/dmdc/st/1.0/Metadata/DanhMucHeThongNganhSanPhamVietNamCap5</UrlMetadata>

<UrlGetList>/dmdc/st/1.0/Category/DanhMucHeThongNganhSanPhamVietNamCap5</UrlGetList>

<UrlPostList>/dmdc/st/1.0/Category/DanhMucHeThongNganhSanPhamVietNamCap5</UrlPostList>

<UrlGetTrace>http://dmdc/st.ngsp.gov.vn/svc/NGSP.svc/TraceCategory/DanhMucHeThongNganhSanPhamVietNamCap5</UrlGetTrace>

</CategoryInfo>

4. API danh mục – mã định danh kết nối các hệ thống QLVBĐH cấp 1

4.1. Lấy cấu trúc danh mục

Đường dẫn: /dmdc/st/1.0/Metadata/qlvanbandieuhanhcap1
Method: GET
Đầu vào:
- Header:
  - Authorization: Bearer {token} (token sinh ra từ API lấy thông tin token phía trên)
  - Content-Type: application/json hoặc application/xml
  - lgspaccesstoken
Đầu ra:
- Danh sách các trường dữ liệu của danh mục Văn bản điều hành cấp 1

Ví dụ:

<PropertyCode>MaDinhDanhCap1</PropertyCode>