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

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ố.
  • APIDongBoThongTinBuuDien 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 Thông tin hồ sơ có yêu cầu trả kết quả qua bưu điện tại đơn vị về CSDL dùng chung của Thành phố.
  • Nền tảng HCM LGSP sẽ chuyển thông tin hồ sơ này qua Hệ thống bưu điện.

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 hồ sơ trả kết quả qua 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 hồ sơ trả kết quả qua 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 lấy thông tin bưu điện

Hình 1: Mô hình kết nối lấy 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ố.
  • APIDongBoThongTinBuuDien 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 Thông tin hồ sơ có yêu cầu trả kết quả qua bưu điện tại đơn vị về CSDL dùng chung của Thành phố.
  • Nền tảng HCM LGSP sẽ chuyển thông tin hồ sơ này qua Hệ thống bưu điện.

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 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 lấy thông tin bưu điện

  • Đường dẫn: /GetThongTinChuyenPhat
  • Method: GET
  • Đầu vào:
  • Header: Authorization
  • Param: Ticket=00.0H49.000001.111
  • Param: MaHoSo=00.0H49.000001
  • Param: LoaiDichVu=1

Lưu ý:

  • Tùy vào trường hợp hồ sơ đã phát sinh số biên nhận hay chưa mà truyền vào 1 trong 2 biến Ticket, MaHoSo.
  • LoaiDichVu : "1": Trả kết quả tại nhà , "2": Thu gom hồ sơ tại nhà
  • Đầu ra:
  • Chuỗi json chứa thông tin trả về , resultObject là chuỗi json thông tin chi tiết hồ sơ, chi tiết dữ liệu tại mục 3.4

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

Boolean

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

{

    "StatusCode": 200,

    "Description": null,

    "ResultObject": {

        "DiaChiLH": [{

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

},

        "DienThoaiLH": "00000000",

     "DaHuy":false,

    "DaHoanTat":true,

    "ChuyenHoan":true,

    "ChuyenHoanThanhCong":false

        "GhiChu": "",

        "LoaiDichVu": "Nhận HS Tại nhà - chuyển trả KQ",

        "MaDonVi": "ĐVCP0001",

        "MaHoSo": "SBN-0010",

        "NguoiLH": "Nguyễn Nghiêm Thuận",

        "NguoiNhans": [{

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

},

                "DienThoaiNhan": "0359093780",

                "EmailNhan": "",

                "NguoiNhan": "Nguyễn Nghiêm Thuận"

            }

        ],

        "Ticket": "8.98.H292019046046002010"

    },

    "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

}

 

  1.  

3. Danh sách các bảng mã liên quan tới gói tin hồ sơ

STT

Mã trạng thái

Tên trạng thái

Mô tả

1

2

Đã nhận thông tin hồ sơ cần thu gom, phát hành

Bưu điện đã nhận gói tin hồ sơ từ Nền tảng HCM LGSP

2

8

Báo hủy

Gói tin báo hủy được gửi qua bưu điện

3

13

Thu gom hồ sơ thất bại lần 1

Bưu điện tiến hành đến địa chỉ người dân/ đơn vị cần chuyển  hồ sơ để thu gom hồ sơ nhưng thất bại

4

14

Thu gom hồ sơ thất bại lần 2

Bưu điện tiến hành đến địa chỉ người dân/ đơn vị cần chuyển  hồ sơ để thu gom hồ sơ nhưng thất bại lần 2

5

15

Thu gom hồ sơ thất bại lần 3

Bưu điện tiến hành đến địa chỉ người dân/ đơn vị cần chuyển  hồ sơ để thu gom hồ sơ nhưng thất bại lần 3

6

16

Thu gom hồ sơ thất bại trên 3 lần

Bưu điện tiến hành đến địa chỉ người dân/ đơn vị cần chuyển  hồ sơ để thu gom hồ sơ nhưng thất bại trên 3 lần

7

21

Hủy hồ sơ

(hoàn tất quá trình chuyển phát bưu điện với trạng thái hủy)

Hủy hồ sơ

8

22

Đã nhận báo hủy

Bưu điện đã nhận gói tin báo hủy

9

95

Đã chấp nhận chuyển phát

Bưu điện đã thu gom hồ sơ thành công và tiến hành chuyển phát

10

96

Chuyển phát không thành công

Bưu điện chuyển phát hồ sơ đến địa chỉ người dân/ đơn vị nhận hồ sơ không thành công

11

97

Chuyển hoàn không thành công

Bưu điện chuyển phát hồ sơ đến địa chỉ người dân/ đơn vị nhận hồ sơ không thành công. Bưu điện chuyển hoàn lại hồ sơ cho người dân/ đơn vị cần chuyển hồ sơ không thành công

12

98

Chuyển phát thành công

Bưu điện chuyển phát hồ sơ đến địa chỉ người dân/ đơn vị nhận hồ sơ thành công

Bảng 3: bảng mã trạng thái bưu điện

 

STT

Mã loại dịch vụ bưu điện

Tên loại dịch vụ bưu điện

Ghi chú

1

1

Nhận kết quả hồ sơ tại nhà

Bưu điện nhận kết quả tại cơ quan hành chính và phát trả kết quả tại nhà

2

2

Thu gom hồ sơ tại nhà

Bưu điện đến thu gom hồ sơ tại nhà nộp cho cơ quan hành chính

Bảng 4: bảng mã loại dịch vụ bưu điện

  1.  

4. Gói thông tin chuyển phát

STT

Tên trường

Định Dạng

Mô tả

Yêu cầu

1

MaDonVi

String

ID của cơ quan, tổ chức

Bắt buộc

2

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

4

NguoiLH

String

Người liên hệ để nhân viên bưu điện liên hệ nhận hoặc trả hồ sơ.

Bắt buộc

5

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

6

DiaChiLH

JSON Object

JSON địa chỉ tại mục 3.5
Đị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

7

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

8

NguoiNhans

JSON Array

Json danh sách người nhận tại mục 3.6
Độ ư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

9

MaDonViChuyenPhat

String

Mã đơn vị chuyển phát:
-VNPOST
-VIETTELPOST

Bắt buộc

10

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

11

DaHuy

Boolean

Đã hủy chuyển phát

Không bắt buộc

12

DaHoanTat

Boolean

Đã hoàn tất quá trình chuyển phát
(Bao gồm chuyển phát thành công và chuyển hoàn)

DaHoanTat=true: Kết thúc quá trình chuyển phát, không cần gọi lại api để lấy trạng thái mới.

Không bắt buộc

13

ChuyenHoan

Boolean

Phát sinh chuyển hoàn

ChuyenHoan=true: Bưu điện chuyển hoàn lại hồ sơ cho người dân/ đơn vị cần chuyển hồ sơ.

ChuyenHoan=false: Trường hợp khác

Không bắt buộc

14

ChuyenHoanThanhCong

Boolean

Trạng thái chuyển hoàn
(Trường hợp ChuyenHoan=true)

ChuyenHoanThanhCong =true: Chuyển hoàn thành công

ChuyenHoanThanhCong =false: Chuyển hoàn không thành công

Không bắt buộc

15

QuaTrinhChuyenPhat

Json Array

Json quá trình chuyển phát tại mục 3.7
Độ ư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)

Không bắt buộc

Bảng 5: Gói thông tin chuyển phát

Ví dụ:

{

  "MaDonVi": "ĐVCP0001",

  "LoaiDichVu": "1",

  "NguoiLH": "Nguyễn Nghiêm Thuận",

  "DienThoaiLH": "035909….",

  "DiaChiLH": {

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

},

 "GhiChu": "",

 "NguoiNhans": "NguoiNhans": [{

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

},

                "DienThoaiNhan": "0359093780",

                "EmailNhan": "",

                "NguoiNhan": "Nguyễn Nghiêm Thuận"

            }],

 "MaDonViChuyenPhat":"VNPOST",

 "SoHieu":"",

"DaHuy":false,

"DaHoanTat":true,

"ChuyenHoan":true,

"ChuyenHoanThanhCong":false,

 "QuaTrinhChuyenPhat":[{

  "SoHieu": "CW123456789VN",

  "SoDoiTac": "2018010001054/BN-UB",

  "NgayXuLy": "2018-08-07 09:20:20.900 ",

  "NguoiXuLy": "Nguyễn Văn Dũng",

  "TrangThai": "POST01",

  "GhiChu": "Đã Nhận Tin Thành Công Ngày 09/10/2018",

  "NgayTruyen": "2018-08-07 09:20:20.900 ",

  "BuuDienID": "xxxxx-xxxxx"

}]

}

 

  1.  

5. 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 6: Gói tin địa chỉ

Ví dụ:

{

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

}

 

 

  1.  

6. 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.5
Đị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 7: Gói tin người nhận

Ví dụ:

{

  "ChiDinh": 0,

  "NguoiNhan": "Nguyễn Văn A",

  "DiaChiNhan": {

  "MaThanhPho": "79",

  "TenThanhPho": "TP. Hồ Chí Minh",

  "MaQuanHuyen": "765",

  "TenQuanHuyen": "Quận Bình Thạnh",

  "MaPhuongXa": "26935",

  "TenPhuongXa": "Phường 14",

  "DiaChi": "122 Bùi Hữu Nghĩa Phường 14 Quận Bình Thạnh TP. Hồ Chí Minh",

  "TenDuong": "",

  "KhuPho": "",

  "SoNha": "122",

  "Tang": "",

  "Phong": ""

}

  "DienThoaiNhan": "0359093780",

  "EmailNhan": ""

}

 

 

  1.  

7. Gói tin thông tin trạng thái chuyển phát

STT

Tên trường

Định Dạng

Mô tả

Yêu cầu

1

SoHieu

String

Số hiệu bưu điện

Không bắt buộc

2

NguoiXuly

String

Người xử lý

Bắt buộc

3

NgayXuly

String

Ngày xử lý

Định dang: dd/MM/yyyy HH:mm:ss

Bắt buộc

4

NgayTruyen

String

Ngày hệ thống truyền

Định dang: dd/MM/yyyy HH:mm:ss

Bắt buộc

6

TrangThai

String

Trạng thái chuyển phát

(Tham khảo bảng 1)

Bắt buộc

7

GhiChu

String

Ghi chú

Không bắt buộc

8

BuuDienID

String

ID trạng thái chuyển phát

Không bắt buộc

Bảng 8: Gói tin thông tin trạng thai chuyển phát

Ví dụ:

{

  "SoHieu": "CW123456789VN",

  "NgayXuLy": "2018-08-07 09:20:20.900 ",

  "NguoiXuLy": "Nguyễn Văn Dũng",

  "TrangThai": "POST01",

  "GhiChu": "Đã Nhận Tin Thành Công Ngày 09/10/2018",

  "NgayTruyen": "2018-08-07 09:20:20.900 ",

  "BuuDienID": "xxxxx-xxxxx"

}

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

  • DacTaLienThong_APILayThongTinBuuDien_v1.1.docx

API Lấy thông tin bưu điện

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