openData StudioEnglish
VssID 图标

VssID 数据 API：社保手册、医保卡与待遇

Bảo hiểm xã hội Việt Nam · 身份

在 Google Play 中打开

VssID 是越南社会保险（Bảo hiểm xã hội Việt Nam）推出的官方自助应用，该机构负责全国社保与医保。公民用 BHXH 账号或通过 VNeID 登录后，即可打开电子社保手册、带可扫二维码的数字 BHYT 医保卡、缴费历程、待遇资格，以及可通过 BIDV 等合作银行充值的社保钱包。同一客户端还能用短信 OTP 提交行政手续、在地图上查找附近社保办事处，并维护医院与省市目录供定点就医。它服务于越南全国的劳动者、退休人员与家属，身份通道上与 VNeID 衔接，在诊所窗口则对标医院发放的纸质医保卡。

每位登录 VssID 的公民都对应一份以 maBhxh 为键、医保卡号为 maTheBhyt 的越南社保台账。会话携带 BHXH 登录或 VNeID code 换来的 OAuth access_token，以及身份字段 hoTen、ngaySinh、gioiTinh 与 soCMND。医保卡记录补上 ngayHieuLuc、ngayHetHan 和二维码载荷；电子手册列出带 namDong、thangDong、mucDong 的缴费行；待遇资格在 cheDoHuong 下返回；社保钱包则把 soTien 与已绑定银行账户放在一起。

就医记录按年分页为 KCB 行；目录返回 maTinh、maHuyen 以及医院代码 maBV / tenBV；行政手续用短信 otp 确认；经 BIDV 的充值把 requestId 金额记到实时钱包余额上。

诊所接诊据此确认仍有效的 BHYT 卡，薪酬台席把缴费月份对上机构手册，待遇发放只给已知钱包充值，政务一体机在交件前报出正确省市——openData Studio 把这份社保台账变成可调用的开放数据。

应用截图

  • VssID 应用截图 1
  • VssID 应用截图 2
  • VssID 应用截图 3

API 端点一览

以下端点与请求/响应示例均依据应用界面推导重构，为示意说明，并非实际抓包。

  • 用 BHXH 账号登录

    POST /v1/auth/dvc osint

    用越南社保账号登录 VssID，返回后续手册与卡片调用使用的 access_token、maBhxh 与身份字段。

    认证方式： 无需登录。请求体为 BHXH 用户名/密码。返回的 access_token 附加在后续调用上。

    • username
    • password
    • access_token
    • maBhxh
    • hoTen
    • soCMND
    POST /v1/auth/dvc HTTP/1.1
Content-Type: application/json

{
  "username": "0123456789",
  "password": "********"
}
    {
  "access_token": "eyJhbGciOiJIUzI1NiJ9.example",
  "maBhxh": "7912345678",
  "hoTen": "Nguyen Van An",
  "soCMND": "079123456789"
}

  • 兑换 VNeID OAuth code

    GET /v1/auth/vneid-code osint

    把 VNeID 授权码换成作为公民会话的 VssID access_token。

    认证方式： 无需登录的 OAuth 回调。查询参数携带 VNeID 的 code（client_id=vssid），返回 access_token。

    • code
    • client_id
    • redirect_uri
    • response_type
    • access_token
    • token_type
    • maBhxh
    GET /v1/auth/vneid-code?code=spl_abc123&client_id=vssid HTTP/1.1
    {
  "access_token": "eyJhbGciOiJIUzI1NiJ9.example",
  "token_type": "Bearer",
  "maBhxh": "7912345678"
}

  • 读取电子社保手册

    GET /v1/ss-book opendata

    返回已登录公民的电子社保手册：maBhxh、法定姓名、出生日期、性别、证件号与地址，对应电子手册界面。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • maBhxh
    • hoTen
    • ngaySinh
    • gioiTinh
    • soCMND
    • diaChi
    GET /v1/ss-book HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "maBhxh": "7912345678",
  "hoTen": "Nguyen Van An",
  "ngaySinh": "1990-04-12",
  "gioiTinh": "Nam",
  "soCMND": "079123456789",
  "diaChi": "Q.1, TP.HCM"
}

  • 读取 BHYT 医保卡

    GET /v1/health-card opendata

    返回应用中展示的数字 BHYT 卡：卡号、持卡人身份、有效期与定点医院，供诊所接诊使用。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • maTheBhyt
    • hoTen
    • ngaySinh
    • gioiTinh
    • ngayHieuLuc
    • ngayHetHan
    • noiKham
    GET /v1/health-card HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "maTheBhyt": "DN4791234567890",
  "hoTen": "Nguyen Van An",
  "ngaySinh": "1990-04-12",
  "gioiTinh": "Nam",
  "ngayHieuLuc": "2026-01-01",
  "ngayHetHan": "2026-12-31",
  "noiKham": "BV Cho Ray"
}

  • 读取 BHYT 卡二维码

    GET /v1/health-card/qr opendata

    返回仍有效 BHYT 卡的可扫二维码载荷，供诊所接诊代替纸质卡。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • maTheBhyt
    • qr
    • hoTen
    GET /v1/health-card/qr HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "maTheBhyt": "DN4791234567890",
  "qr": "DN4791234567890|Nguyen Van An|19900412|1|20260101-20261231",
  "hoTen": "Nguyen Van An"
}

  • 分页缴费历程

    GET /v1/contributions/history opendata

    分页返回公民社保缴费历程（quaTrinh）：年份、月份、缴费额与单位，来自手册缴费界面。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • quaTrinh
    • namDong
    • thangDong
    • mucDong
    • donVi
    GET /v1/contributions/history HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "quaTrinh": [
    {
      "namDong": 2026,
      "thangDong": 9,
      "mucDong": 4680000,
      "donVi": "Cong ty TNHH ABC"
    }
  ]
}

  • 读取待遇资格

    GET /v1/benefits/entitlements opendata

    返回公民当前持有的社保待遇（cheDoHuong）：待遇代码、名称、状态与金额，对应待遇界面。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • cheDoHuong
    • maCheDo
    • tenCheDo
    • trangThai
    • soTien
    GET /v1/benefits/entitlements HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "cheDoHuong": [
    {
      "maCheDo": "OM_DAU",
      "tenCheDo": "Om dau",
      "trangThai": "DANG_HUONG",
      "soTien": 3500000
    }
  ]
}

  • 读取社保钱包账户

    GET /v1/ss-wallet/account openbanking

    返回已绑定的社保钱包账户：银行、掩码账号、持有人姓名与 LINKED 状态，供充值前使用。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • accountNo
    • bankCode
    • hoTen
    • status
    GET /v1/ss-wallet/account HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "accountNo": "970418xxxxxx1234",
  "bankCode": "BIDV",
  "hoTen": "Nguyen Van An",
  "status": "LINKED"
}

  • 读取社保钱包余额

    GET /v1/ss-wallet/balance openbanking

    返回钱包首页在充值或提现前展示的实时 soTien（越南盾）。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • soTien
    • currency
    GET /v1/ss-wallet/balance HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "soTien": 1250000,
  "currency": "VND"
}

  • 发起社保钱包充值

    POST /v1/ss-wallet/cash-in openfinance

    向社保钱包发起 BIDV（或其他已绑定银行）充值，返回 requestId 与手续费，供公民用银行 OTP 确认。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。 完成充值需在银行 OTP 后确认。

    • soTien
    • bankCode
    • requestId
    • fee
    • status
    POST /v1/ss-wallet/cash-in HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "soTien": 500000,
  "bankCode": "BIDV"
}
    {
  "requestId": "ci-9c21e4",
  "soTien": 500000,
  "fee": 0,
  "status": "PENDING_OTP"
}

  • 发送行政手续 OTP

    POST /v1/procedures/otp osint

    发送确认行政手续的短信 OTP，再提交卷宗。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • thuTucId
    • soDienThoai
    • otpRequestId
    • status
    POST /v1/procedures/otp HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "thuTucId": "GDDT_653",
  "soDienThoai": "0901234567"
}
    {
  "otpRequestId": "otp-8f21a4",
  "status": "SENT"
}

  • 按年分页就医记录

    GET /v1/visits/by-year opendata

    按年分页公民 KCB（就医）记录：就诊日、医院、诊断与金额。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。 查询参数：year。

    • year
    • visits
    • ngayKham
    • benhVien
    • chanDoan
    • soTien
    GET /v1/visits/by-year?year=2026 HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "year": 2026,
  "visits": [
    {
      "ngayKham": "2026-09-12",
      "benhVien": "BV Cho Ray",
      "chanDoan": "Kham tong quat",
      "soTien": 180000
    }
  ]
}

  • 列出省市与医院

    GET /v1/catalog/provinces opendata

    返回查询与申报界面使用的行政区目录：省、县与医院。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • tinh
    • maTinh
    • tenTinh
    • huyen
    • maHuyen
    • tenHuyen
    • benhVien
    • maBV
    • tenBV
    GET /v1/catalog/provinces HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "tinh": [{"maTinh": "79", "tenTinh": "TP. Ho Chi Minh"}],
  "huyen": [{"maHuyen": "760", "tenHuyen": "Quan 1"}],
  "benhVien": [{"maBV": "79001", "tenBV": "BV Cho Ray"}]
}

  • 读取 BHYT 卡续期报价

    GET /v1/payments/card-renewal openfinance

    返回续办 BHYT 卡的报价：应付金额、当前到期日与期限，供应用内支付前使用。

    认证方式： 来自 POST /v1/auth/dvc 或 VNeID code 换取的会话 access_token，用于后续第一方调用。

    • maTheBhyt
    • soTien
    • ngayHetHan
    • kyHan
    GET /v1/payments/card-renewal HTTP/1.1
Authorization: Bearer eyJhbGciOi...
    {
  "maTheBhyt": "DN4791234567890",
  "soTien": 804600,
  "ngayHetHan": "2026-12-31",
  "kyHan": "12T"
}

数据类别

  • 身份
  • 医保卡
  • 缴费
  • 待遇
  • 钱包
  • 手续
  • 目录

数据使用场景与案例

  • 诊所接诊核验资格

    医院前台读取 GET /v1/health-card（maTheBhyt、hoTen、ngaySinh、ngayHetHan）和 GET /v1/health-card/qr，用扫描到的二维码确认仍有效的 BHYT 卡后再开就诊，而不是依赖可能已过期的纸质卡。

  • 缴费与待遇对账

    薪酬或工会工具拉取 GET /v1/ss-book（maBhxh、hoTen），加上 GET /v1/contributions/history（namDong、thangDong、mucDong）和 GET /v1/benefits/entitlements，把申报月份与待遇资格对上机构台账。

  • 社保钱包充值台席

    待遇发放控制台读取 GET /v1/ss-wallet/account 与 GET /v1/ss-wallet/balance，再 POST /v1/ss-wallet/cash-in，只给 soTien 与已绑定 BIDV 账户已知的钱包充值。

  • 手续 OTP 与医院目录

    政务一体机为行政手续发送 POST /v1/procedures/otp，并把 GET /v1/catalog/provinces 与 GET /v1/visits/by-year 拼在一起，让工作人员在交件前报出正确省市与去年 KCB 就医。

常见问题

VssID 如何对公民 API 调用进行认证？

POST /v1/auth/dvc 用 BHXH 账号登录。GET /v1/auth/vneid-code 用 VNeID OAuth code（client_id=vssid）换取 access_token。之后的请求把该令牌带到第一方路由上。

哪些端点暴露社保手册与 BHYT 卡？

GET /v1/ss-book 返回电子社保手册（maBhxh、hoTen）。GET /v1/health-card 返回 BHYT 卡（maTheBhyt、ngayHieuLuc、ngayHetHan）。GET /v1/health-card/qr 返回诊所接诊扫描的二维码。GET /v1/contributions/history 分页 namDong、thangDong 与 mucDong。

VssID 的社保钱包是什么？

GET /v1/ss-wallet/account 与 GET /v1/ss-wallet/balance 返回已绑定账户和 soTien。POST /v1/ss-wallet/cash-in 发起 BIDV 充值并返回 requestId 与手续费。完成充值走银行 OTP 确认步骤。

能否看到待遇资格与就医记录？

可以。GET /v1/benefits/entitlements 返回 cheDoHuong。GET /v1/visits/by-year 分页 KCB 就医。GET /v1/catalog/provinces 列出 maTinh / maHuyen / 医院。POST /v1/procedures/otp 确认行政手续。

与 VssID 相似的应用

  • VNeID — VNeID 是越南公安部的国家数字身份应用：公民把它当作电子身份证钱包，VssID 通过 OAuth 把它当作单点登录通道。
  • DigiLocker — DigiLocker 是印度政府的证件钱包，公民把已签发的身份与证明存在手机上，与 VssID 的电子社保手册和 BHYT 卡同类。
  • Pak Identity — Pak Identity 是巴基斯坦 NADRA 的公民身份应用，覆盖 CNIC 证件、数字身份保险库与家庭记录，相当于 VssID 保险身份钱包的南亚对照。
  • Налоги ФЛ — Налоги ФЛ 是俄罗斯联邦税务局面向自然人纳税人的官方柜面，同属通过政府身份通道登录的国家级自助应用。

更多身份类应用

相关主题

  • vssid api
  • vssid 数据 api
  • 越南社保 api
  • bhxh api
  • bhyt 卡 api
  • vssid 钱包
  • vssid 缴费历程
  • vneid vssid

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

  • 每个项目均签 NDA 与 SOW
  • 3–7 天交付
  • 验收通过后才付款
  • 仅在授权范围内作业

获取报价