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 BHXH.
    1. 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 BHXH Việt Nam thông qua Nền tảng HCM LGSP.
    1. 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
    • PartnerCode
    • PartnerCodeCus
  1. MÔ HÌNH KẾT NỐI
    1.  Mô hình kết nối

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

 

  • Nền tảng NGSP thực hiện chia sẻ thông tin về CSDL BHXH 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 BHXH cho đơn vị thực hiện tra cứu.
  • API Tra cứu thông tin BHXH 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 BHXH
    1. 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ị.
  1. ĐẶ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 thử nghiệm

Địa chỉ cổng dịch vụ chính thức

https://hcmesb-test.tphcm.gov.vn

Địa chỉ adapter Nền tảng HCM chính

Địa chỉ cổng dịch vụ thử nghiệm

https://hcmlgsp.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

ewoiQWNjZXNzS2V5IjoiclRraFlDQndITSIsCiJTZWNyZXRLZXkiOiJ

EV2tRZ1kxWVNTIiwKIkFwcE5hbWUiOiAiVFBIQ00iLAoiUGFydG5

lckNvZGUiOiAiMDAwLjAwLjAxLkgyOSIsCiJQYXJ0bmVyQ29kZUN

1cyI6ICIwMDAuMDAuMDEuSDI5Igp9Cg==

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

    1. API lấy thông tin token
  • Đường dẫn: /bhxh/Token
  • Method: POST
  • Đầu vào:
    • Header:
      • Content-Type: application/x-www-form-urlencoded
      • lgspaccesstoken: Base64
    • 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ả
  1.  

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
  1.  

token_type

string

Có

Kiểu token
  1.  

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": " e02e8bbe-e81f-3fc8-910e-64bf8bd08b3d ",

  "scope": "am_application_scope default",

  "token_type": "Bearer",

  "expires_in": 768

}

Ví dụ:

 

{

    "maSoBhxh": "8306005079"

}

 

  • Đầu ra:
    • Chuỗi json chứa thông tin trả về

STT

Tên trường

Kiểu

Mô tả
  1.  

hoTen

string

Họ tên
  1.  

soSoCu

string

Số sổ BHXH cũ
  1.  

ngaySinh

string

Ngày tháng năm sinh theo thứ tự Năm – tháng – ngày viết liền. vd: 19890812
  1.  

loaiNgaySinh

string

Nhận 3 giá trị:

0: đầy đủ ngày, tháng, năm sinh

1: chỉ có năm sinh

2: chỉ có năm, tháng sinh
  1.  

gioiTinh

string

Nhận 3 giá trị:

1: Nam

2: Nữ

3: Khác
  1.  

maTinhKs

string

Mã tỉnh theo quy định của tổng cục thống kê
  1.  

maHuyenKs

string

Mã huyện theo quy định của tổng cục thống kê
  1.  

maXaKs

string

Mã xã theo quy định của tổng cục thống kê
  1.  

trangThai

string

Trạng thái

Bảng 3: Tham số chuỗi json trả về của API tra cứu thông tin hộ gia đình từ mã số bảo hiểm xã hội

Ví dụ:

{

    "TST_GetTraCuuTtHgdByMaSoBhxhResponse": {

        "successful": {

            "dataThongTinHgd": {

                "hoTen": "Đàm Đình Sơn",

                "soSoCu": 8306005079,

                "ngaySinh": 19601215,

                "loaiNgaySinh": 0,

                "gioiTinh": 1,

                "maTinhKs": 27,

                "maHuyenKs": 261,

                "maXaKs": "09373",

                "trangThai": 1

            },

            "errorCode": "00"

        }

    }

}

 

    1. API lấy mã số bảo hiểm theo tiêu chí
  • Đường dẫn: /bhxh/getMaSoBhxhTheoTieuChi
  • Method: POST
  • Đầ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: Base64
    • Body: Chuỗi json chứa thông tin truyền vào

STT

Tên trường

Kiểu

Mô tả
  1.  

hoTen

string

Họ tên
  1.  

ngaySinh

string

Ngày tháng năm sinh theo thứ tự Năm – tháng – ngày viết liền. vd: 19890812
  1.  

loaiNgaySinh

string

Nhận 3 giá trị:

0: đầy đủ ngày, tháng, năm sinh

1: chỉ có năm sinh

2: chỉ có năm, tháng sinh
  1.  

gioiTinh

string

Nhận 3 giá trị:

1: Nam

2: Nữ

3: Khác
  1.  

maTinhKs

string

Mã tỉnh theo quy định của tổng cục thống kê
  1.  

maHuyenKs

string

Mã huyện theo quy định của tổng cục thống kê
  1.  

maXaKs

string

Mã xã theo quy định của tổng cục thống kê
  1.  

isKs

string

Nhận 2 giá trị:

1: tra cứu theo địa chỉ khai sinh

0: tra cứu theo địa chỉ hộ khẩu

Bảng 4: Tham số chuỗi json truyền vào của API lấy mã số bảo hiểm theo tiêu chí

Ví dụ:

{

            "hoTen":"Võ Việt Dũng",

            "ngaySinh":"19910929",

            "loaiNgaySinh":"0",

            "gioiTinh":"1",

            "maTinhKs":"01",

            "maHuyenKs":"005",

            "maXaKs":"00160",

            "isKs":"0"

}

 

  • Đầu ra:
    • Chuỗi json chứa thông tin trả về

 

 

STT

Tên trường

Kiểu

Mô tả
  1.  

maSoBhxh

string

Mã số BHXH
  1.  

trangThai

string

Trạng thái
  1.  

errorCode

string

Mã lỗi

Bảng 5: Tham số chuỗi json trả về của API lấy mã số bảo hiểm theo tiêu chí

Ví dụ:

{

    "TST_GetMaSoBhxhTheoTieuChiResponse": {

        "successful": {

            "maSoBhxh": "0113011672",

            "trangThai": 1,

            "errorCode": "00"

        }

    }

}

 

    1. API tra cứu thông tin hộ gia đình
  • Đường dẫn: /bhxh/getTraCuuThongTinHgd
  • Method: POST
  • Đầ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: Base64
    • Body: Chuỗi json chứa thông tin truyển vào

STT

Tên trường

Kiểu

Mô tả
  1.  

maTinh

 

Mã tỉnh theo quy định của tổng cục thống kê
  1.  

hoTen

string

Họ tên
  1.  

ngaySinh

string

Ngày tháng năm sinh theo thứ tự Năm – tháng – ngày viết liền. vd: 19890812
  1.  

loaiNgaySinh

string

Nhận 3 giá trị:

0: đầy đủ ngày, tháng, năm sinh

1: chỉ có năm sinh

2: chỉ có năm, tháng sinh
  1.  

gioiTinh

string

Nhận 3 giá trị:

1: Nam

2: Nữ

3: Khác
  1.  

soSo

string

Số sổ BHXH
  1.  

maThe

string

Mã thẻ BHXH
  1.  

isKs

string

Nhận 2 giá trị:

1: tra cứu theo địa chỉ khai sinh

0: tra cứu theo địa chỉ hộ khẩu

Bảng 6: Tham số truyền vào chuỗi json của API tra cứu thông tin hộ gia đình

 

Ví dụ:

{

            "maTinh":"01",

            "hoTen":"Đặng Tiến Dũng",

            "ngaySinh":"19890803",

            "loaiNgaySinh":"0",

            "soSo":"0110145363",

            "maThe":"DN4016410600026",

            "isKs":"0"

}

 

  • Đầu ra:
    • Chuỗi json chứa thông tin trả về

STT

Tên trường

Kiểu

Mô tả
  1.  

maSo

string

Mã số
  1.  

hoTen

string

Họ tên
  1.  

ngaySinh

string

Ngày tháng năm sinh theo thứ tự Năm – tháng – ngày viết liền. vd: 19890812
  1.  

loaiNgaySinh

string

Nhận 3 giá trị:

0: đầy đủ ngày, tháng, năm sinh

1: chỉ có năm sinh

2: chỉ có năm, tháng sinh
  1.  

gioiTinh

string

Nhận 3 giá trị:

1: Nam

2: Nữ

3: Khác
  1.  

maHo

string

Mã hộ gia đình
  1.  

diaChi

string

Địa chỉ
  1.  

trangThai

string

Trạng thái

Bảng 7: Tham số chuỗi json trả về của API tra cứu thông tin hộ gia đình

Ví dụ:

{

    "TST_GetTraCuuThongTinHgdResponse": {

        "successful": {

            "errorCode": 2

        }

    }

}

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

  • HCM_LGSP_TracuuthongtinBHXH_v1.0.docx

Dịch vụ tra cứu CSDL Quốc gia về thông tin bảo hiểm xã hội

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