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

I. TỔNG QUAN

1.1. Mô tả nghiệp vụ

  • Phần mềm ISO điện tử khi có nhu cầu lấy bộ danh mục quốc gia thì sẽ gọi api lấy bộ danh mục quốc gia lên HCM LGSP (APILayDanhMucQuocGia).
  • HCM LGSP sẽ lấy thông tin bộ danh mục quốc gia từ CSDL dùng chung của Thành phố và trả về thông tin danh mục quốc gia cho đơn vị.

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

  • Tài liệu này nhằm hướng dẫn đơn vị lấy thông tin danh mục quốc gia từ CSDL tập trung của Thành phố.

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

  • Tài liệu này được sử dụng bởi các kỹ thuật viên của các đơn vị cần lấy thông tin danh mục quốc gia từ chuẩn CSDL dùng chung của Thành phố.

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

  • Đơn vị cần kết nối liên hệ 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

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

2.1. Mô hình kết nối lấy danh mục quốc gia

Hình 1: Mô hình kết nối lấy bộ danh mục quốc gia

  • CSDL Dùng chung là nơi tập trung toàn bộ kho dữ liệu dùng chung của TPHCM. Cơ quan, tổ chức có thể thực hiện việc khai thác và đồng bộ dữ liệu về CSDL Dùng chung của Thành phố thông qua Nền tảng HCM LGSP.
  • Nền tảng HCM LGSP đảm nhiệm vai trò chính trong việc cung cấp các thông tin kết nối đến các phần mềm tại đơn vị, khai thác và đồng bộ dữ liệu từ CSDL tập trung của thành phố.
  • APILayDanhMucQuocGia hỗ trợ phần mềm kết nối vào Nền tảng HCM LGSP lấy bộ danh mục Quốc gia chuẩn từ CSDL dùng chung của Thành phố.

2.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ề gói tin JSON lỗi cho phần mềm của đơn vị.
  • 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 LẤY DANH MỤC QUỐC GIA

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

  • Đơn vị đang trong giai đoạn thử nghiệm sẽ dùng hệ thống test theo địa chỉ apdapter Nền tảng HCM thử nghiệm
  • Đơn vị khi có thông báo vận hành chính thức sẽ dùng hệ thống chính theo địa chỉ apdapter Nền tảng HCM chính

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

Authorization

Khai báo trong Header, Là chuỗi gồm 5 tham số dạng json được mã hóa thành StringBase64

ewoiQWNjZXNzS2V5IjoiclRraFlDQndITSIsCiJTZWNyZXRLZ

XkiOiJEV2tRZ1kxWVNTIiwKIkFwcE5hbWUiOiAiVFBIQ00iL

AoiUGFydG5lckNvZGUiOiAiMDAwLjAwLjAxLkgyOSIsCiJQYX

J0bmVyQ29kZUN1cyI6ICIwMDAuMDAuMDEuSDI5Igp9Cg==

đượ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

  •  

3.2. API lấy danh mục quốc gia

  • Đường dẫn: /GetDanhMucQuocGia
  • Method: GET
  • Đầu vào:
    • Header: Authorization
  • Đầu ra:
    • chuỗi json chứa thông tin trả về, resultObject là chuỗi json array chứa thông tin danh mục, chi tiết dữ liệu tại mục 3.3

STT

Tham số

Thuộc tính tham số

Mô tả

1

StatusCode   

Int

Mã trạng thái gói tin

- 200: Request đã được tiếp nhận và xử lý thành công

- 400: Request bị lỗi hoặc không thể xử lý

- 404: Tài nguyên không tồn tại

- 500: Lỗi trong quá trình xử lý

2

Description

String

Nội dung lỗi trả về

3

ResultObject

JSON Aray

Kết quả trả về

4

ResultType

String

Type của gói tin trả về Mặc định là “JSON”

5

Status

String

Trạng thái gói tin“SUCCESS” hoặc “FAIL”

6

ThrowException

bool

 Có lỗi xảy ra hay không

Bảng 2: tham số trả về của chuỗi json

Ví dụ:

Thành công

Lỗi

{

    "Description": null,

    "ResultObject": [

        {

            "CacNgonNguHanhChinhAlpha2": "",

            "CacNgonNguHanhChinhAlpha3": "",

            "CoQuanBanHanh": "Tiêu chuẩn Việt Nam",

            "MaAlpha3": "BVT",

            "MaQuocGia": "BV",

            "NgayBanHanh": "",

            "NuocDocLap": "",

            "QDBanHanhSuaDoi": "TCVN 7217-1:2007",

            "TenQuocGiaDayDuBangTiengAnh": "",

            "TenQuocGiaDayDuBangTiengViet": "Đảo Buvê",

            "TenQuocGiaVietGonBangTiengAnh": "BOUVET ISLAND",

            "TenQuocGiaVietGonBangTiengViet": "",

            "TenVietGonDiaPhuong": "",

            "Used": true

        },

        {

            "CacNgonNguHanhChinhAlpha2": "en; zh",

            "CacNgonNguHanhChinhAlpha3": "eng; zho",

            "CoQuanBanHanh": "Tiêu chuẩn Việt Nam",

            "MaAlpha3": "HKG",

            "MaQuocGia": "HK",

            "NgayBanHanh": "",

            "NuocDocLap": "",

            "QDBanHanhSuaDoi": "TCVN 7217-1:2007",

            "TenQuocGiaDayDuBangTiengAnh": "The Hong Kong Special Administrative Region of China",

            "TenQuocGiaDayDuBangTiengViet": "Đặc khu hành chính Hồng Kông thuộcTrung Quốc",

            "TenQuocGiaVietGonBangTiengAnh": "HONG KONG",

            "TenQuocGiaVietGonBangTiengViet": "",

            "TenVietGonDiaPhuong": "Hong Kong; Xianggang",

            "Used": true

        }

    ],

    "ResultType": "JSON",

    "Status": "SUCCESS",

    "StatusCode": 200,

    "ThrowException": false

}

{

    "StatusCode": 500,

    "Description": "Tham số đầu vào không đúng",

    "ResultObject": null,

    "ResultType": null,

    "Status": "FAIL",

    "ThrowException": true

}         

  1.  

3.3. Gói tin danh mục quốc gia

STT

Tham số

Thuộc tính tham số

Mô tả

Yêu cầu

1

MaQuocGia

String

Mã quốc gia.

Bắt buộc

2

TenQuocGiaDayDuBangTiengViet

String

Tên quốc gia đầy đủ bằng tiếng việt

Không bắt buộc

3

MaAlpha3

String

Mã alpha-3

Không bắt buộc

4

TenQuocGiaDayDuBangTiengAnh

String

Tên quốc gia đầy đủ bằng tiếng anh

Không bắt buộc

5

CacNgonNguHanhChinhAlpha2

String

Các ngôn ngữ hành chính alpha-2

Không bắt buộc

6

CacNgonNguHanhChinhAlpha3

String

Các ngôn ngữ hành chính alpha-3

Không bắt buộc

7

TenVietGonDiaPhuong

String

Các tên viết gọn địa phương

Không bắt buộc

8

NuocDocLap

String

Nước độc lập

Không bắt buộc

9

QDBanHanhSuaDoi

String

Quyết định ban hành/QĐ sửa đổi

Không bắt buộc

10

NgayBanHanh

String

Ngày ban hành QĐ

Không bắt buộc

11

CoQuanBanHanh

String

Cơ quan ban hành QĐ

Không bắt buộc

12

Used

String

Được sử dụng

Không bắt buộc

Bảng 3: Gói tin danh mục quốc gia

Ví dụ:

{

            "CacNgonNguHanhChinhAlpha2": "en; zh",

            "CacNgonNguHanhChinhAlpha3": "eng; zho",

            "CoQuanBanHanh": "Tiêu chuẩn Việt Nam",

            "MaAlpha3": "HKG",

            "MaQuocGia": "HK",

            "NgayBanHanh": "",

            "NuocDocLap": "",

            "QDBanHanhSuaDoi": "TCVN 7217-1:2007",

            "TenQuocGiaDayDuBangTiengAnh": "The Hong Kong Special Administrative Region of China",

            "TenQuocGiaDayDuBangTiengViet": "Đặc khu hành chính Hồng Kông thuộcTrung Quốc",

            "TenQuocGiaVietGonBangTiengAnh": "HONG KONG",

            "TenQuocGiaVietGonBangTiengViet": "",

            "TenVietGonDiaPhuong": "Hong Kong; Xianggang",

            "Used": true

}

Danh sách tệp tin đính kèm

  • DacTaLienThong_APICungCapDanhMucQuocGia_v1.1.docx

API lấy danh mục quốc gia

Câu hỏi thường gặp

CHÚNG TÔI LUÔN SẴN
SÀNG ĐỂ GIÚP ĐỠ BẠN

Hỗ trợ trực tuyến

Để được hỗ trợ tốt nhất. Hãy gọi

028 38233717 - 111
HOẶC
0889490111

SỞ THÔNG TIN VÀ TRUYỀN THÔNG TPHCM

LIÊN KẾT WEBSITE

KẾT NỐI VỚI CHÚNG TÔI

  • chinh-se-tren-gm
  • chinh-se-tren-fb
  • chinh-se-mes-tren-fb
  • chinh-se-tren-gg
  • chinh-se-tren-tw
Giấy phép số 91/GP-TTĐT, do Cục Phát thanh, Truyền hình và Thông tin điện tử - Bộ Thông tin và Truyền thông cấp ngày 26/04/2018