I. TỔNG QUAN
1. Mô tả nghiệp vụ
- 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ố.
- APIDongBoThongTinChuyenPhat hỗ trợ phần mềm tại đơn vị kết nối vào Nền tảng HCM LGSP Đồng bộ dữ liệu Hồ sơ có yêu cầu Nhận và trả kết quả qua Bưu điện từ hệ thống phần mềm tại đơn vị về CSDL dùng chung của Thành phố.
2. Mục đích tài liệu
- Tài liệu này nhằm hướng dẫn đơn vị đồng bộ thông tin bưu điện về CSDL dùng chung của Thành phố.
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 đồng bộ thông tin bưu điện về CSDL dùng chung của Thành phố.
II. MÔ HÌNH KẾT NỐI
1. Mô hình kết nối đồng bộ thông tin bưu điện
Hình 1: Mô hình kết nối đồng bộ thông tin bưu điện
- 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ố.
- APIDongBoThongTinChuyenPhat hỗ trợ phần mềm tại đơn vị kết nối vào Nền tảng HCM LGSP Đồng bộ dữ liệu Hồ sơ có yêu cầu Nhận và trả kết quả qua Bưu điện từ hệ thống phần mềm tại đơn vị về CSDL dùng chung của Thành phố.
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ị đóng gói dữ liệu về dạng JSON.
- Bước 2: 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 3: 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 4: 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 ĐỒNG BỘ THÔNG TIN BƯU ĐIỆN
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ụ dự kiến chính thức
|
https://hcmesb.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.tphcm.gov.vn/test
|
|
AccessKey
|
Khóa
|
rTkhYCBwHM
|
|
SecretKey
|
Khóa bí mật
|
DWkQgY1YSS
|
|
AppName
|
Đơn vị kết nối
|
TPHCM
|
|
Authorization/Token
|
Khai báo trong Header, Là chuỗi gồm 3 tham số dạng json được mã hóa thành StringBase64
|
eyJhcHAiOiJRTkkiLCJzZWNyZXQiOiJEV2tRZ1kxWVNTIiwia2V5IjoiclRraFlDQndITSJ9
được stringbase64 từ:
{
"AccessKey":"rTkhYCBwHM",
"SecretKey":"DWkQgY1YSS",
"AppName": "TPHCM"
}
|
Bảng 1: bảng thông tin kết nối
2. API đồng bộ thông tin bưu điện
- Đường dẫn: / DongBoThongTinChuyenPhat
- Method: POST
- Đầu vào:
- Header: Authorization
- Body: chuỗi json chứa thông tin truyền vào
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
Lưu ý
|
|
1
|
MaHoSo
|
String
|
Mã định danh của hồ sơ theo nghị định 61
|
Bắt buộc khi Ticket bẳng rỗng
|
|
2
|
Ticket
|
String
|
Mã định danh của hồ sơ nộp qua mạng. Dùng để xác định hồ sơ qua mạng khi trao đổi thông tin giữa các phần mềm với nhau.
Hồ sơ phát sinh từ phần mềm nào thì phần mềm đó sinh một mã định danh duy nhất trong phần mềm đó để trao đổi qua mạng.
Phần mềm nên đặt ticket theo cấu trúc sau:[Mã đơn vị] [Năm nhận hồ sơ][Mã lĩnh vực][Mã thủ tục][Số thứ tự hồ sơ]
|
Bắt buộc khi MaHoSo bằng rỗng
|
|
3
|
MaDonVi
|
String
|
Mã đợn vị của cơ quan, tổ chức
|
Bắt buộc
|
|
4
|
LoaiDichVu
|
String
|
Loại DV:
"1": Trả kết quả tại nhà
"2": Thu gom hồ sơ tại nhà
|
Bắt buộc
|
|
5
|
NguoiLH
|
String
|
Người liên hệ để nhân viên bưu điện liên nhận hoặc trả hồ sơ.
|
Bắt buộc
|
|
6
|
DienThoaiLH
|
String
|
Số điện thoại để nhân viên bưu điện liên hệ nhận hoặc trả hồ sơ.
|
Không bắt buộc
|
|
7
|
DiaChiLH
|
JSON Object
|
JSON địa chỉ tại mục 5.3
Địa chỉ để nhân viên bưu điện đến liên hệ nhận hoặc trả hồ sơ.
|
Bắt buộc
|
|
8
|
GhiChu
|
String
|
Ghi chú, Ghi nội dung hàng cần gửi, mô tả các yêu cầu nhận gửi, nhận
|
Không bắt buộc
|
|
9
|
NguoiNhans
|
JSONArray
|
Json danh sách người nhận tại mục 5.4
Độ ưu tiên theo số được chỉ định ưu tiên từ nhỏ đến lớn (Mặc định là số 1 người nhận chính)
|
Bắt buộc
|
|
10
|
MaDonViChuyenPhat
|
String
|
Mã đơn vị chuyển phát:
-VNPOST
-VIETTELPOST
|
Bắt buộc
|
|
11
|
SoHieu
|
String
|
Số hiệu bưu điện của hồ sơ
(Trường hợp đơn vị ISO điện tử chưa chưa có số hiệu bưu đơn vị chuyển phát sẽ phát sinh số hiệu này và gửi lại cho Nền tảng HCM LGSP. Nền tảng HCM LGSB gửi lại cho đơn vị thông qua gói tin lấy thông tin chuyển phát, trạng thái chuyển phát với mã là POST01)
|
Không bắt buộc
|
Bảng 2: tham số truyền vào chuỗi json của body
Ví dụ:
|
{
"MaHoSo": "SBN_00010",
"Ticket": null,
"MaDonVi": "ĐVCP0001",
"LoaiDichVu": "Nhận HS Tại nhà - chuyển trả KQ",
"NguoiLH": "Nguyễn Văn A",
"DienThoaiLH": "00000000",
"DiaChiLH": {..},
"GhiChu": "",
"NguoiNhans": [{…}],
"MaDonViChuyenPhat":"VNPOST",
"SoHieu":""
}
|
- Đầu ra:
- Chuỗi json chứa thông tin trả về , resultObject là true hoặc false
|
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
|
Chuỗi json 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 3: tham số trả về của chuỗi json
Ví dụ:
|
Thành công
|
Lỗi
|
|
{
"StatusCode": 200,
"Description": null,
"ResultObject": true,
"ResultType": "JSON",
"Status": "SUCCESS",
"ThrowException": false
}
|
{
"StatusCode": 500,
"Description": "Tham số đầu vào không đúng",
"ResultObject": null,
"ResultType": null,
"Status": "FAIL",
"ThrowException": true
}
|
-
3. Gói tin địa chỉ
|
STT
|
Tên trường
|
Định Dạng
|
Mô tả
|
Yêu cầu
|
|
1
|
MaThanhPho
|
String
|
Mã thành phố
|
Bắt buộc
|
|
2
|
TenThanhPho
|
String
|
Tên thành phố
|
|
|
3
|
MaQuanHuyen
|
String
|
Mã quận huyện
|
Bắt buộc
|
|
4
|
TenQuanHuyen
|
String
|
Tên quận huyện
|
|
|
5
|
MaPhuongXa
|
String
|
Mã phường
|
Bắt buộc
|
|
6
|
TenPhuongXa
|
String
|
Tên phường
|
|
|
7
|
DiaChi
|
String
|
Số nhà và tên đường
|
Bắt buộc
|
|
8
|
TenDuong
|
String
|
Tên đường
|
Không bắt buộc
|
|
9
|
KhuPho
|
String
|
Khu phố
|
Không bắt buộc
|
|
10
|
SoNha
|
String
|
Số nhà
|
Không bắt buộc
|
|
11
|
Tang
|
String
|
Tầng
|
Không bắt buộc
|
|
12
|
Phong
|
String
|
Phòng
|
Không bắt buộc
|
Bảng 4: Gói tin địa chỉ
Ví dụ:
|
{
"MaThanhPho": "",
"TenThanhPho": "",
"MaQuanHuyen": "",
"TenQuanHuyen": "",
"MaPhuongXa": "",
"TenPhuongXa": "",
"DiaChi": "",
"TenDuong": "",
"KhuPho": "",
"SoNha": "",
"Tang": "",
"Phong": ""
}
|
-
4. Gói tin người nhận
|
STT
|
Tên trường
|
Định Dạng
|
Mô tả
|
Yêu cầu
|
|
1
|
ChiDinh
|
Int
|
Độ ưu tiên theo số được chỉ định ưu tiên từ nhỏ đến lớn (Mặc định là số 1 người nhận chính)
|
Bắt buộc
|
|
2
|
NguoiNhan
|
String
|
Họ tên người nhận hồ sơ gửi đến
|
Bắt buộc
|
|
3
|
DiaChiNhan
|
JSON Object
|
JSON địa chỉ tại mục 3.12
Địa chỉ được hồ sơ gửi đến
|
Bắt buộc
|
|
4
|
DienThoaiNhan
|
String
|
Số điện thoại người nhận được hồ sơ gửi đến
|
Không bắt buộc
|
|
5
|
EmailNhan
|
String
|
Email người nhận được hồ sơ gửi đến
|
Không bắt buộc
|
Bảng 5: Gói tin người nhận
Ví dụ:
|
{
"ChiDinh": 0,
"NguoiNhan": "Nguyễn Văn A",
"DiaChiNhan": {…}
"DienThoaiNhan": "0359093780",
"EmailNhan": ""
}
|