Liên Thông Đơn Thuốc Quốc Gia: Kết Nối & Xử Lý Lỗi Đồng Bộ

Cán bộ IT y tế cấu hình kết nối hệ thống liên thông đơn thuốc quốc gia tại bệnh viện

Cán bộ IT y tế cấu hình kết nối hệ thống liên thông đơn thuốc quốc gia tại bệnh viện.

Từ ngày 01/10/2025, toàn bộ bệnh viện tại Việt Nam bắt buộc liên thông dữ liệu kê đơn lên Hệ thống thông tin quốc gia về quản lý kê đơn thuốc và bán thuốc theo đơn của Bộ Y tế. Nhiều cơ sở đã hoàn thành cấu hình phần mềm nhưng vẫn gặp tình trạng đơn treo, không đẩy được lên cổng quốc gia. Bài viết này trình bày toàn bộ cơ chế kỹ thuật, quy trình đăng ký, cấu hình mã liên thông bác sĩ, luồng API và hướng dẫn xử lý lỗi đồng bộ phổ biến nhất - từ góc độ cán bộ IT y tế và quản lý y khoa.

1. Liên Thông Đơn Thuốc Quốc Gia Là Gì?

Liên thông đơn thuốc quốc gia là quá trình kết nối tự động giữa phần mềm quản lý tại cơ sở khám chữa bệnh (HIS/EMR/phần mềm phòng khám) với hệ thống đơn thuốc quốc gia của Bộ Y tế, nhằm truyền dữ liệu đơn thuốc điện tử theo thời gian thực hoặc theo lịch hằng ngày.

Cơ quan vận hành: Cục Quản lý Dược - Bộ Y tế; cổng chính tại địa chỉ donthuocquocgia.vn.
Mục đích chính:
- Minh bạch hóa hoạt động kê đơn và bán thuốc trên toàn quốc.
- Kiểm soát lạm dụng thuốc kháng sinh, hạn chế tình trạng kháng thuốc.
- Cho phép tra cứu lịch sử dùng thuốc của người bệnh, nâng cao an toàn điều trị.
- Tạo cơ sở dữ liệu phục vụ quản lý nhà nước và dược lý cảnh giác.

Cần phân biệt rõ: kê đơn thuốc điện tử liên thông không đồng nghĩa với kê đơn điện tử nội bộ. Một cơ sở có phần mềm kê đơn điện tử nhưng không push dữ liệu lên hệ thống quốc gia vẫn bị coi là chưa tuân thủ.

2. Lộ Trình Triển Khai Bắt Buộc - Thời Hạn Pháp Lý

Tiêu chí	Bệnh viện	Cơ sở KCB khác
Thời hạn bắt buộc	01/10/2025	01/01/2026
Đối tượng	Bệnh viện công lập & tư nhân các tuyến	Phòng khám đa khoa, chuyên khoa, phòng nha, YHCT, cơ sở thẩm mỹ có hoạt động KCB
Phạm vi kê đơn	100% đơn thuốc kê tại cơ sở	100% đơn thuốc kê tại cơ sở
Nhà thuốc/quầy thuốc	Liên thông bán thuốc theo đơn hằng ngày	Liên thông bán thuốc theo đơn hằng ngày
Căn cứ pháp lý	Thông tư 27/2021/TT-BYT; Thông tư 05/2024/TT-BYT	Thông tư 27/2021/TT-BYT; Thông tư 05/2024/TT-BYT

Cơ sở không tuân thủ đúng hạn có thể bị xử phạt hành chính theo Nghị định 117/2020/NĐ-CP và ảnh hưởng đến kết quả kiểm tra, cấp phép hoạt động. Để nắm toàn bộ yêu cầu pháp lý và bước chuẩn bị, hãy xem bài lộ trình bắt buộc kê đơn thuốc điện tử.

3. Quy Trình Đăng Ký & Chuẩn Bị Tài Khoản Trên donthuocquocgia.vn

Sơ đồ luồng 4 bước đăng ký tài khoản cơ sở khám chữa bệnh trên cổng quốc gia

Quy trình 4 bước đăng ký tài khoản cơ sở khám chữa bệnh trên cổng donthuocquocgia.vn.

3.1. Đăng ký tài khoản Cơ sở KCB

Truy cập cổng donthuocquocgia.vn -> chọn "Đăng ký tài khoản" -> loại "Cơ sở khám chữa bệnh".
Thông tin cần khai báo: mã cơ sở KCB (do Sở Y tế cấp), số giấy phép hoạt động, thông tin người đại diện pháp lý, địa chỉ, số điện thoại liên hệ IT.
Tài khoản sau khi tạo chuyển trạng thái "Chờ phê duyệt" - cơ quan quản lý (Sở Y tế hoặc Cục Quản lý Dược) duyệt trong vòng 3-5 ngày làm việc.
Sau phê duyệt, hệ thống cấp mã định danh cơ sở (Facility ID) - cần lưu lại để cấu hình phần mềm.

3.2. Tạo mã liên thông cho bác sĩ kê đơn

Trong tài khoản cơ sở: vào mục Quản lý bác sĩ -> Thêm bác sĩ -> nhập số chứng chỉ hành nghề, họ tên, chuyên khoa.
Hệ thống sinh Mã liên thông bác sĩ (Prescriber Code) - mã này phải được nhập vào hồ sơ bác sĩ trong phần mềm HIS/EMR nội bộ để gắn với mỗi đơn thuốc khi push lên hệ thống.
Lưu ý: bác sĩ thỉnh giảng, bác sĩ hợp đồng ngắn hạn cũng cần có mã liên thông riêng nếu kê đơn tại cơ sở.

3.3. Đăng ký phần mềm kết nối (Software Registration)

Đơn vị cung cấp phần mềm phải có Mã phần mềm được Cục Quản lý Dược xác nhận.
Cơ sở cần xác nhận trong tài khoản: "Sử dụng phần mềm X - mã XXX" để liên kết Facility ID với phần mềm.

4. Kỹ Thuật Kết Nối & Đẩy Đơn Lên Hệ Thống Quốc Gia

Sau khi hoàn tất đăng ký, cán bộ IT y tế thực hiện kết nối API theo 5 bước kỹ thuật dưới đây:

Cấu hình endpoint & xác thực:
- Phần mềm quản lý cần được cấu hình URL endpoint API của Cục Quản lý Dược (môi trường Production).
- Xác thực bằng OAuth2 Bearer Token - token được cấp sau khi đăng nhập hệ thống bằng Facility ID + mật khẩu tài khoản cơ sở.
- Token có thời hạn hiệu lực; phần mềm phải tự động làm mới (refresh) trước khi hết hạn.
Chuẩn hóa dữ liệu đơn thuốc theo schema quốc gia:
- Mỗi đơn thuốc phải đáp ứng cấu trúc JSON/XML chuẩn: mã đơn nội bộ, Prescriber Code bác sĩ, mã thuốc theo danh mục quốc gia (mã ATC hoặc mã DM-YT), liều dùng, số ngày, mã người bệnh (CCCD hoặc mã bảo hiểm y tế).
- Thuốc không có trong danh mục quốc gia sẽ bị từ chối - cần cập nhật mapping danh mục định kỳ.
Push đơn (POST request):
- Sau khi bác sĩ ký số/xác nhận đơn trong HIS, phần mềm tự động POST lên endpoint /prescription/create.
- Hệ thống quốc gia trả về Mã đơn quốc gia (National Prescription ID) nếu thành công - mã này được in lên đơn cho người bệnh và nhà thuốc tra cứu.
Đồng bộ trạng thái bán thuốc (nhà thuốc):
- Nhà thuốc khi bán thuốc theo đơn: quét hoặc nhập Mã đơn quốc gia -> phần mềm nhà thuốc POST lên endpoint /dispensing/confirm.
- Hệ thống cập nhật trạng thái đơn từ "Đã kê" -> "Đã cấp phát".
Reconciliation hằng ngày:
- Cuối ngày, phần mềm gửi báo cáo tổng hợp (daily reconciliation) để đối chiếu số lượng đơn kê với số đơn đã liên thông thành công.

5. Xử Lý Lỗi: Đơn Treo, Lỗi Đồng Bộ & Bị Từ Chối Liên Thông

Bác sĩ và dược sĩ phối hợp xử lý lỗi đồng bộ đơn thuốc điện tử trên hệ thống

Bác sĩ và dược sĩ phối hợp xử lý lỗi đồng bộ đơn thuốc điện tử trên hệ thống quốc gia.

5.1. Đơn treo (Pending / không nhận phản hồi)

Nguyên nhân	Cách xử lý
Token xác thực hết hạn, phần mềm không auto-refresh	Kiểm tra cơ chế refresh token trong cấu hình; cập nhật phiên bản phần mềm nếu chưa hỗ trợ auto-refresh
Timeout kết nối mạng (firewall, proxy nội bộ chặn HTTPS ra ngoài)	Kiểm tra firewall/proxy cho phép outbound HTTPS đến domain Cục Quản lý Dược; whitelist IP endpoint
Hệ thống quốc gia đang bảo trì	Theo dõi thông báo bảo trì trên cổng; đơn sẽ được xếp hàng retry tự động sau khi hệ thống khôi phục

5.2. Lỗi từ chối (HTTP 4xx / rejection)

Mã lỗi phổ biến	Nguyên nhân	Cách xử lý
PRESCRIBER_NOT_FOUND	Mã liên thông bác sĩ chưa đăng ký hoặc nhập sai trong HIS	Kiểm tra lại Prescriber Code trong hồ sơ bác sĩ; đối chiếu với mã trên cổng quốc gia
DRUG_CODE_INVALID	Mã thuốc không có trong danh mục quốc gia hoặc mapping sai	Cập nhật bảng mapping danh mục thuốc; liên hệ nhà cung cấp phần mềm để đồng bộ danh mục mới nhất
FACILITY_NOT_APPROVED	Tài khoản cơ sở chưa được phê duyệt hoặc bị tạm khóa	Kiểm tra trạng thái tài khoản trên donthuocquocgia.vn; liên hệ Sở Y tế hoặc Cục Quản lý Dược
DUPLICATE_PRESCRIPTION	Đơn đã push thành công lần trước, phần mềm push lại do lỗi logic	Kiểm tra bảng trạng thái đơn nội bộ; thêm kiểm tra idempotency trước khi retry
PATIENT_ID_INVALID	CCCD/mã BHYT của người bệnh sai định dạng	Kiểm tra logic validate ID trước khi push; rà soát dữ liệu đầu vào ở bước tiếp đón

Lưu ý: các mã lỗi trên là ví dụ minh họa theo nguyên tắc chung của API REST; tên mã lỗi thực tế cần đối chiếu với tài liệu API chính thức của Cục Quản lý Dược.

5.3. Đơn đã gửi nhưng nhà thuốc không tra cứu được

Kiểm tra trạng thái đơn trên cổng (donthuocquocgia.vn -> Tra cứu đơn).
Nếu trạng thái "Pending": đơn chưa được xử lý xong ở phía hệ thống quốc gia - chờ 5-15 phút rồi thử lại.
Nếu không có kết quả: đơn chưa được push thành công - kiểm tra log phần mềm nội bộ, tìm lỗi tại bước POST.

5.4. Khôi phục hàng loạt đơn treo sau sự cố

Phần mềm phải có tính năng retry queue: tự động xếp hàng các đơn push thất bại và retry theo lịch (ví dụ mỗi 5 phút, tối đa 3 lần).
Sau khi khắc phục sự cố (kết nối, token, danh mục), chạy manual bulk retry cho toàn bộ đơn trong trạng thái FAILED/PENDING trong ngày.
Ghi log đầy đủ (request body, response code, timestamp) để phục vụ audit trail.

6. Yêu Cầu Kỹ Thuật & Bảo Mật Dữ Liệu

Checklist kỹ thuật cần hoàn tất trước khi go-live liên thông:

Về bảo mật dữ liệu:

Dữ liệu đơn thuốc chứa thông tin sức khỏe cá nhân - phải mã hóa HTTPS (TLS 1.2 trở lên) trên toàn bộ kênh truyền.
Token xác thực không lưu trong log; giới hạn quyền tài khoản API ở mức tối thiểu cần thiết.
Định kỳ xoay vòng (rotate) credentials tài khoản cơ sở theo chính sách bảo mật nội bộ.

7. Trách Nhiệm Của Nhà Thuốc & Cơ Sở Bán Lẻ Thuốc Theo Đơn

Nhà thuốc, quầy thuốc không được bán thuốc kê đơn nếu không có mã đơn quốc gia hợp lệ - giao dịch không liên thông có thể bị coi là bán thuốc không hợp lệ theo quy định.
Phần mềm quản lý nhà thuốc phải kết nối cổng quốc gia để xác thực đơn trước khi cấp phát (kiểm tra trạng thái đơn, số lần cấp phát để tránh dùng lại đơn).
Báo cáo bán thuốc hằng ngày: push dữ liệu dispensing lên hệ thống trước 23:59 mỗi ngày.
Nhà thuốc trong bệnh viện và nhà thuốc cộng đồng bên ngoài đều thuộc phạm vi bắt buộc - không có ngoại lệ theo quy mô.

8. Vai Trò Của Phần Mềm Quản Lý Trong Tuân Thủ Liên Thông Tự Động

Một hệ thống phần mềm quản lý bệnh viện (HIS) tích hợp sẵn module đồng bộ đơn thuốc điện tử với hệ thống quốc gia giúp cơ sở y tế:

Tự động push đơn ngay sau khi bác sĩ ký số - không cần thao tác thủ công.
Hiển thị trạng thái liên thông trực tiếp trên màn hình kê đơn (thành công/lỗi/đang chờ).
Tự động cập nhật danh mục thuốc từ hệ thống quốc gia.
Cảnh báo ngay khi bác sĩ chưa có mã liên thông trước khi cho phép ký đơn.

Nhờ đó, cán bộ IT y tế không phải can thiệp thủ công vào từng đơn và tỷ lệ đơn treo giảm đáng kể.

Phần mềm quản lý bệnh viện MyHospital tích hợp sẵn module liên thông đơn thuốc quốc gia, hỗ trợ push tự động, retry queue và dashboard giám sát trạng thái đồng bộ theo thời gian thực.

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

Liên thông đơn thuốc quốc gia có bắt buộc với phòng khám tư nhân nhỏ không?

Có. Theo Thông tư 27/2021/TT-BYT và Thông tư 05/2024/TT-BYT, tất cả cơ sở khám chữa bệnh có hoạt động kê đơn thuốc - bao gồm phòng khám chuyên khoa tư nhân, phòng nha, cơ sở y học cổ truyền - phải hoàn thành liên thông trước ngày 01/01/2026.

Mã liên thông bác sĩ lấy ở đâu và mất bao lâu để được cấp?

Mã liên thông bác sĩ (Prescriber Code) được tạo bởi quản trị viên tài khoản cơ sở trên cổng donthuocquocgia.vn, trong mục Quản lý bác sĩ. Mã được sinh ngay sau khi nhập số chứng chỉ hành nghề hợp lệ - không cần chờ phê duyệt riêng.

Đơn thuốc bị treo do timeout thì dữ liệu đơn có bị mất không?

Không. Đơn thuốc treo do timeout chỉ là chưa được xác nhận bởi hệ thống quốc gia - dữ liệu đơn vẫn còn nguyên trong phần mềm nội bộ. Sau khi kết nối được khôi phục, phần mềm sẽ retry và đơn được push lại. Tuy nhiên cần đảm bảo phần mềm có cơ chế retry queue và log đầy đủ để không bỏ sót đơn.

Nhà thuốc ngoài bệnh viện có thể bán thuốc theo đơn điện tử liên thông không?

Có. Nhà thuốc cộng đồng cần cấu hình phần mềm quản lý nhà thuốc để kết nối cổng quốc gia, tra cứu và xác thực mã đơn quốc gia trước khi cấp phát thuốc. Sau khi bán, phần mềm phải push dữ liệu dispensing lên hệ thống để cập nhật trạng thái đơn.

Phần mềm kê đơn điện tử nội bộ có sẵn đã đủ điều kiện tuân thủ chưa?

Chưa đủ. Phần mềm phải có khả năng kết nối API thực tế với hệ thống quốc gia và truyền dữ liệu lên cổng donthuocquocgia.vn. Cơ sở chỉ kê đơn điện tử lưu nội bộ mà không push lên hệ thống quốc gia vẫn bị coi là chưa tuân thủ quy định liên thông.

Nếu hệ thống quốc gia bảo trì, cơ sở có thể tiếp tục kê đơn không?

Có. Bác sĩ vẫn kê đơn bình thường trong phần mềm nội bộ. Các đơn thuốc được xếp vào retry queue và tự động push lên hệ thống quốc gia ngay khi bảo trì kết thúc. Cơ sở nên theo dõi thông báo bảo trì trên cổng donthuocquocgia.vn để chủ động xử lý.