Mã lỗi gói dữ liệu
KQTBV-GOI-006
Không nhận dạng được cấu trúc XMLThẻ gốc phải là GIAMDINHHS (dạng bao) hoặc thẻ gốc bảng theo QĐ 3176 (TONG_HOP, CHI_TIET_THUOC, …).
Mã theo hợp đồng giao diện: L02 — Tệp bảng kê của lô không đọc được hoặc thiếu trường bắt buộc (Lô; bên xử lý: Hệ thống sản xuất)
Toàn bộ mã lỗi
| Mã | Mã giao diện | Ý nghĩa | Cách xử lý |
|---|---|---|---|
| KQTBV-0000 | — | Lỗi không xác định ở máy chủ | Hệ thống gặp lỗi chưa phân loại; thông điệp kèm mã tra cứu. Thử lại sau ít phút; lặp lại thì báo quản trị hệ thống kèm mã tra cứu và thời điểm — không gửi kèm dữ liệu người bệnh. |
| KQTBV-0001 | — | Tham số yêu cầu không hợp lệ | Một giá trị gửi lên sai định dạng hoặc ngoài khoảng cho phép (tên tham số ghi trong thông điệp). Sửa đúng giá trị — ngày dạng yyyy-MM-dd, mã theo danh mục — rồi gửi lại. |
| KQTBV-0002 | — | Không tìm thấy | Đối tượng được hỏi không có hoặc nằm ngoài phạm vi của tài khoản. Kiểm lại mã/đường dẫn và phạm vi đơn vị của tài khoản; cần thì nhờ quản trị cấp phạm vi. |
| KQTBV-0003 | — | Không có quyền | Vai của tài khoản không được làm thao tác này (hoặc ngoài phạm vi đơn vị/khoa). Đề nghị người quản trị tài khoản cấp đúng vai; không dùng chung tài khoản của người khác. |
| KQTBV-0004 | — | Xung đột dữ liệu | Đối tượng vừa bị người/tiến trình khác thay đổi hoặc đã tồn tại. Tải lại trang để xem trạng thái mới nhất rồi làm lại thao tác. |
| KQTBV-0005 | — | Chức năng chưa được cài đặt hoặc cấu hình | Phần cấu hình cần cho chức năng này chưa có trên môi trường (ví dụ kho lõi, cấu hình nguồn đã ký, tài liệu kịch bản đã ký của cơ sở). Báo quản trị hệ thống; thông điệp nói rõ phần nào còn thiếu. |
| KQTBV-8001 | — | Dữ liệu mã hoá không toàn vẹn | Bản mã, tham số mã hoá hoặc khoá đã bị thay đổi nên kiểm toàn vẹn không đạt — dữ liệu không được giải mã. Không gửi lại bản đó; tạo lại gói từ nguồn. Ở máy chủ: báo quản trị hệ thống kiểm khoá và bản lưu. |
| KQTBV-8002 | — | Khoá mã hoá không hợp lệ hoặc thiếu cấu hình khoá | Khoá sai độ dài hoặc thiếu thông tin xác thực kho khoá. Quản trị hệ thống kiểm tệp khoá/cấu hình kho khoá theo tài liệu cài đặt; người dùng nghiệp vụ không cần thao tác. |
| KQTBV-8003 | — | Dữ liệu mã hoá sai định dạng | Gói phải được mã hoá lớp tiếp nhận theo đúng định dạng khi cấp hệ thống đã bật bắt buộc, hoặc tệp khoá công khai trên máy chủ sai dạng. Cập nhật công cụ tác tử đơn vị lên bản mới nhất; lỗi phía máy chủ thì báo quản trị cấp hệ thống. |
| KQTBV-8004 | — | Phiên bản hoặc thuật toán mã hoá không được hỗ trợ | Gói dùng phiên bản định dạng mã hoá mà máy chủ không nhận. Cập nhật công cụ tác tử đơn vị lên bản mới nhất rồi gửi lại. |
| KQTBV-8005 | — | Không rõ phiên bản khoá tiếp nhận | Gói được mã hoá bằng phiên bản khoá tiếp nhận mà máy chủ không biết. Tải lại danh sách khoá tiếp nhận công khai (công cụ tác tử tự làm khi ghim khoá gốc) rồi gửi lại. |
| KQTBV-8006 | — | Khoá tiếp nhận đã thu hồi hoặc hết hạn | Phiên bản khoá tiếp nhận dùng để mã hoá gói đã thu hồi/hết hạn. Công cụ tác tử tải danh sách khoá mới và mã hoá lại; gửi lại gói từ nguồn. |
| KQTBV-8008 | — | Kho khoá đang niêm phong | Kho khoá chưa mở niêm phong đủ số nút nên không cấp được khoá. Quản trị hệ thống mở niêm phong theo quy trình; người dùng thử lại sau. |
| KQTBV-8009 | — | Kho khoá từ chối truy cập | Danh tính dịch vụ không có chính sách cho đường dẫn khoá này. Quản trị hệ thống kiểm chính sách và danh tính dịch vụ trong kho khoá theo tài liệu cài đặt. |
| KQTBV-8010 | — | Không kết nối được kho khoá | Mạng tới kho khoá lỗi, phiên hết hạn hoặc phản hồi không hợp lệ. Thử lại sau; kéo dài thì quản trị hệ thống kiểm dịch vụ kho khoá. |
| KQTBV-8101 | — | Không ghi được vùng dữ liệu thô | Cổng tạm thời không ghi được gói (hệ thống bận hoặc hết dung lượng). Gửi lại sau khoảng thời gian ghi ở Retry-After; công cụ tác tử tự thử lại. Kéo dài thì báo quản trị hệ thống. |
| KQTBV-8102 | — | Gói đã nhận trước đó | Nội dung gói trùng một gói đã nhận của cùng cơ sở — không nhận lại (chống trùng). Không cần làm gì; muốn sửa dữ liệu thì gửi gói mới có nội dung đã sửa. |
| KQTBV-GOI-001 | X02 | Thiếu MA_LK | Mỗi hồ sơ phải có thẻ MA_LK (mã liên kết đợt điều trị) trong Bảng 1. Kiểm dữ liệu kết xuất từ HIS. |
| KQTBV-GOI-002 | X03 | Mã cơ sở trong XML không khớp khoá API | Thẻ MACSKCB (hoặc MA_CSKCB trong Bảng 1) phải đúng mã cơ sở của khoá đang dùng. Kiểm cấu hình mã cơ sở trong HIS trước khi gửi lại. |
| KQTBV-GOI-003 | X01 | XML không hợp lệ | Tệp phải là XML well-formed, mã hoá UTF-8, không DTD/thực thể ngoài, kích cỡ trong giới hạn. Dạng chấp nhận: bao GIAMDINHHS/THONGTINHOSO/DANHSACHHOSO/HOSO/FILEHOSO (NOIDUNGFILE base64) hoặc XML phẳng từng bảng theo QĐ 3176. |
| KQTBV-GOI-004 | X01 | XML chứa DTD/thực thể ngoài | Cổng cấm DOCTYPE, thực thể ngoài (XXE) và thực thể lồng (XML bomb). Kết xuất XML thuần từ HIS, không kèm DTD. |
| KQTBV-GOI-005 | — | Gói vượt giới hạn kích cỡ | XML tối đa 100 MB, PDF tối đa 50 MB mỗi tệp [tham số, QD-073]. Gói XML cả ngày của bệnh viện lớn luôn vượt (XML 130 thật 128 KB–1 MB mỗi lượt): chia theo BYTE — gom hồ sơ vào mỗi gói tới tối đa 90 MB rồi mở gói mới (khoảng 90 hồ sơ nội trú dài tới vài trăm hồ sơ ngoại trú), mỗi gói một bản kê khai riêng; công cụ tác tử đơn vị của cấp hệ thống tự chia, HIS tự gửi thì cộng dồn cỡ từng hồ sơ. Header X-Kqtbv-Goi-Toi-Da-Byte cho hạn mức byte đang áp. Không gửi lại nguyên tệp đã bị từ chối. |
| KQTBV-GOI-006 | L02 | Không nhận dạng được cấu trúc XML | Thẻ gốc phải là GIAMDINHHS (dạng bao) hoặc thẻ gốc bảng theo QĐ 3176 (TONG_HOP, CHI_TIET_THUOC, …). |
| KQTBV-GOI-007 | — | NOIDUNGFILE base64 hỏng | Nội dung FILEHOSO/NOIDUNGFILE phải là base64 hợp lệ của XML bảng. Kiểm bước mã hoá base64 trong HIS. |
| KQTBV-GOI-008 | — | Gói không có hồ sơ nào | DANHSACHHOSO phải có ít nhất một HOSO với FILEHOSO Bảng 1 (TONG_HOP). |
| KQTBV-GOI-009 | — | Thiếu hoặc sai khoá API | Gửi header X-Kqtbv-Khoa: <tiền tố>.<khoá> do cấp hệ thống cấp cho đơn vị. Khoá chỉ hiện một lần lúc tạo; nếu mất, giám đốc đơn vị tạo khoá mới trên Portal và thu hồi khoá cũ. |
| KQTBV-GOI-010 | — | Khoá API không có phạm vi này | Khoá cần phạm vi day-xml130 để đẩy XML, day-pdf để đẩy PDF. Giám đốc đơn vị tạo khoá với đủ phạm vi trên Portal. |
| KQTBV-GOI-011 | P01 | Tệp PDF không hợp lệ | Tệp phải bắt đầu bằng %PDF- và có kích cỡ trong giới hạn. Xuất lại từ HIS ở định dạng PDF chuẩn (không phải ảnh đổi đuôi). |
| KQTBV-GOI-012 | P01 | PDF chứa mã nhúng bị từ chối | PDF không được chứa JavaScript, hành động Launch hoặc mã nhúng (/JS, /JavaScript, /Launch). Xuất lại PDF ở chế độ tĩnh/PDF-A. |
| KQTBV-GOI-013 | — | Tên tệp hoặc mã không hợp lệ | Tên tệp/MA_LK chỉ gồm chữ, số, gạch ngang, gạch dưới, dấu chấm; không chứa đường dẫn (../, /, \). |
| KQTBV-GOI-014 | — | Không tìm thấy gói | Mã gói không tồn tại hoặc không thuộc đơn vị của khoá. Kiểm lại goi_id trả về lúc nhận (202). |
| KQTBV-GOI-015 | — | Nội dung rỗng | Thân yêu cầu không có dữ liệu. Gửi tệp XML/PDF trong thân yêu cầu (application/xml, application/pdf) hoặc phần multipart 'tep'. |
| KQTBV-GOI-016 | — | Khoá API hết hạn hoặc đã thu hồi | Quản trị hệ thống tạo khoá mới cho đơn vị trên Portal (/quan-tri/khoa-api) và cập nhật vào bộ kết nối. |
| KQTBV-GOI-017 | — | Content-Type không được hỗ trợ | Dùng application/xml hoặc text/xml cho XML; application/pdf cho PDF; hoặc multipart/form-data với phần 'tep'. |
| KQTBV-GOI-018 | — | Chưa có hồ sơ XML tương ứng | Đẩy XML 130 (Bảng 1 có MA_LK) trước rồi mới đẩy PDF hồ sơ bệnh án cho MA_LK đó. |
| KQTBV-GOI-019 | — | Lỗi hệ thống khi xử lý gói | Gửi lại sau ít phút; nếu lặp lại, báo cấp hệ thống kèm goi_id (không gửi nội dung gói qua email). |
| KQTBV-GOI-020 | — | Không có lược đồ cho nhóm dữ liệu này | Mã nhóm (đoạn cuối đường dẫn /api/tinh/v1/goi-mo-rong/{ma_bang}) chưa được khai trong cấu hình (Postgres, miền goi-mo-rong). Kiểm lại đúng mã nhóm cấp hệ thống đã công bố. |
| KQTBV-GOI-021 | — | Thiếu cột bắt buộc | Dòng tiêu đề CSV phải có đủ mọi cột bắt buộc của lược đồ nhóm này (xem đặc tả cấu hình miền goi-mo-rong). Đối chiếu lại tên cột (không dấu, chữ thường, gạch dưới). |
| KQTBV-GOI-022 | — | Có cột lạ ngoài lược đồ | Dòng tiêu đề CSV chỉ được chứa đúng các cột đã khai trong lược đồ, không thêm cột nào khác. Bỏ cột thừa hoặc báo cấp hệ thống để xin bổ sung lược đồ. |
| KQTBV-GOI-023 | — | Có dòng dữ liệu sai kiểu hoặc thiếu giá trị bắt buộc | Xem số dòng và tên cột trong thông điệp lỗi; sửa đúng kiểu (số/ngày yyyy-MM-dd) rồi gửi lại cả tệp. |
| KQTBV-GOI-024 | — | Bản kê khai (manifest) không hợp lệ | Công cụ đơn vị gửi kèm mỗi gói một bản kê khai (số hồ sơ, danh sách tệp, băm SHA-256, phiên bản công cụ, phiên bản đặc tả). Lỗi này nghĩa là bản kê khai thiếu (khi cấp hệ thống đã yêu cầu bắt buộc), đọc không được, hoặc số hồ sơ/băm khai báo khác với nội dung tệp thực nhận. Cập nhật công cụ đơn vị lên bản mới nhất rồi gửi lại; nếu vẫn lệch, báo cấp hệ thống kèm goi_id. |
| KQTBV-GOI-025 | — | Thiếu hoặc sai chữ ký chống phát lại | Khi cấp hệ thống đã bật bắt buộc chống phát lại, mỗi yêu cầu phải kèm header X-Kqtbv-Khoa-Ky: v1:<mốc thời gian giây>:<chuỗi dùng một lần>:<chữ ký HMAC-SHA256 hex> ký bằng CHÍNH bí mật khoá API trên chuỗi "PHƯƠNG_THỨC\nĐƯỜNG_DẪN\nMỐC_THỜI_GIAN\nCHUỖI_MỘT_LẦN\nBĂM_SHA256_THÂN_GÓI" (kèm X-Kqtbv-Bam-Than). Mốc thời gian lệch quá hạn cho phép, chuỗi dùng một lần đã dùng trong cửa sổ trước đó (phát lại), hoặc chữ ký sai đều bị từ chối. Công cụ tác tử đơn vị chính thức của cấp hệ thống tự ký khi có bí mật khoá; cập nhật lên bản mới nhất. |
| KQTBV-GOI-026 | — | Địa chỉ IP không có trong danh sách cho phép của cơ sở | Cấp hệ thống đã cấu hình danh sách IP cho phép cho cơ sở này (tuỳ chọn). Gửi từ đúng địa chỉ đã đăng ký, hoặc báo cấp hệ thống cập nhật danh sách nếu địa chỉ máy chủ HIS đã đổi. |
| KQTBV-GOI-028 | — | Đơn vị không hoạt động (Ngừng hoặc Tạm dừng) | Khoá API vẫn còn hạn, chưa thu hồi, nhưng đơn vị của khoá đang ở trạng thái «Ngừng» hoặc «Tạm dừng» trong danh mục đơn vị của cấp hệ thống nên cổng không nhận dữ liệu của đơn vị này. Đầu mối dữ liệu đơn vị liên hệ quản trị cấp hệ thống để kích hoạt lại đơn vị; sau khi kích hoạt lại, khoá đang dùng chạy lại ngay, không phải đổi khoá. Đang thử theo tài liệu mẫu thì kiểm lại mã cơ sở: tệp ví dụ dùng đơn vị mẫu 38999, phải thay bằng mã cơ sở của mình. |
| KQTBV-GOI-029 | — | Gói của bộ kết nối HIS sai hình thức hoặc ngoài cấu hình nguồn đã ký | Gói không đúng hợp đồng contracts/ket-noi-his/goi.schema.json (phiên bản lược đồ, tên bảng/cột, số dòng, băm dòng), hoặc (ly_do «ngoai-cau-hinh») không khớp cấu hình nguồn ĐÃ KÝ mà máy chủ kho giữ cho cơ sở: mã nguồn, bảng đang bật, danh sách cột cho phép đúng thứ tự, phiên bản cấu hình không cũ hơn bản hiện hành. Không gửi lại nguyên gói; chạy kqtbv-ket-noi-his --cap-nhat-cau-hinh-nguon để tải cấu hình mới, cập nhật bộ kết nối lên bản mới nhất rồi chạy lại vòng đọc — bộ kết nối dựng lại gói từ điểm mốc. |
| KQTBV-GOI-030 | — | Chữ ký gói của bộ kết nối HIS không hợp lệ | Khoá ký thiết bị của bộ kết nối chưa được đăng ký ở máy chủ kho, đăng ký cho cơ sở khác, đã thu hồi hoặc hết hạn. Chạy kqtbv-ket-noi-his --sinh-khoa-ky-goi, gửi khoá công khai và vân tay cho quản trị kho đăng ký (đối chiếu vân tay qua kênh khác), rồi chạy lại. |
| KQTBV-GOI-031 | — | Gói của bộ kết nối HIS bị chặn chống phát lại | Số thứ tự gói không lớn hơn số cuối cổng đã nhận cho bảng này. Bộ kết nối tự đồng bộ theo số cuối trong phản hồi và gửi lại ở lượt sau; lặp lại nhiều lần thì kiểm có hai bộ kết nối cùng đọc một nguồn không. |
| KQTBV-HM-001 | — | Vượt hạn mức tần suất | Cổng nhận tối đa 60 yêu cầu mỗi phút cho một khoá API, cho dồn tới 120 [tham số, QD-076]. Đọc header Retry-After và gửi lại sau đúng số giây đó (lùi dần), đừng gửi dồn lại ngay. Khoá KHÔNG bị thu hồi và cũng không bị khoá vĩnh viễn. |
| KQTBV-HM-002 | — | Địa chỉ bị chặn tạm thời vì bị từ chối quá nhiều | Địa chỉ của bạn có quá 20 yêu cầu bị từ chối (401/403/404) trong một phút nên bị chặn 5 phút [tham số, QD-076]. Thường là do gọi sai đường dẫn hoặc thiếu xác thực hàng loạt: sửa đường dẫn và xác thực rồi thử lại sau Retry-After. |
| KQTBV-XUAT-001 | — | Yêu cầu xuất chưa đủ người duyệt | Xuất dữ liệu cần đủ số người duyệt khác nhau theo quy định. Mời thêm người có vai duyệt xuất duyệt yêu cầu. |
| KQTBV-XUAT-002 | — | Không được tự duyệt yêu cầu của mình | Người tạo yêu cầu xuất không được duyệt chính yêu cầu đó. Nhờ người khác có vai duyệt xuất. |
| KQTBV-XUAT-003 | — | Đã có quyết định trên yêu cầu này | Mỗi người chỉ duyệt hoặc từ chối một lần. Không cần thao tác thêm; xem trạng thái yêu cầu. |
| KQTBV-XUAT-004 | — | Yêu cầu xuất đã hết hạn duyệt | Yêu cầu không được duyệt kịp trong thời hạn. Tạo yêu cầu xuất mới. |
| KQTBV-XUAT-005 | — | Yêu cầu xuất còn chờ duyệt | Chưa đủ số người đồng ý nên chưa tạo gói được. Chờ đủ người duyệt rồi tạo gói. |
| KQTBV-XUAT-006 | — | Thiếu căn cứ xuất dữ liệu định danh | Xuất vùng có định danh phải ghi rõ điều kiện/căn cứ cho phép. Bổ sung căn cứ rồi tạo lại yêu cầu. |
| KQTBV-XUAT-007 | — | Khoá công khai của người nhận không hợp lệ | Khoá phải ở dạng PEM khoá công khai hợp lệ của người nhận. Lấy lại khoá công khai từ người nhận (đối chiếu vân tay qua kênh khác) rồi đăng ký lại. |
| KQTBV-XUAT-008 | — | Liên kết tải đã hết hạn hoặc bị thu hồi | Liên kết tải gói xuất chỉ dùng trong thời hạn cấp. Đề nghị người quản lý xuất cấp liên kết mới. |
| KQTBV-XUAT-009 | — | Liên kết tải đã hết lượt | Liên kết đã dùng đủ số lượt tải cho phép. Đề nghị cấp liên kết mới nếu thật sự cần tải lại. |
| KQTBV-XUAT-010 | — | Bảng không được phép xuất | Tên bảng sai dạng hoặc không thuộc nguồn được phép cho yêu cầu này. Chọn đúng bảng trong danh mục được phép. |
| KQTBV-XUAT-011 | — | Yêu cầu xuất không ở trạng thái phù hợp | Thao tác không áp dụng cho trạng thái hiện tại của yêu cầu (ví dụ đã từ chối, đã tạo gói). Xem trạng thái yêu cầu; cần thì tạo yêu cầu mới. |
Mã lỗi theo hợp đồng giao diện
| Mã | Diễn giải | Mức | Bên xử lý |
|---|---|---|---|
| L01 | Tệp bảng kê của lô không tồn tại | Lô | Hệ thống sản xuất |
| L02 | Tệp bảng kê của lô không đọc được hoặc thiếu trường bắt buộc | Lô | Hệ thống sản xuất |
| L03 | Phiên bản chuẩn dữ liệu không thuộc danh mục khai báo cho đơn vị | Lô | Đơn vị và nền tảng |
| L04 | Số tệp thực nhận không khớp bảng kê | Lô | Hệ thống sản xuất |
| L05 | Tệp đánh dấu hoàn thành không tồn tại | Lô | Hệ thống sản xuất |
| T01 | Mã kiểm tra của tệp không khớp giá trị trong bảng kê | Hồ sơ | Hệ thống sản xuất |
| T02 | Tệp bị cắt hoặc hỏng trong quá trình truyền | Hồ sơ | Nền tảng |
| X01 | Tệp XML không đúng lược đồ của phiên bản chuẩn áp dụng | Hồ sơ | Hệ thống sản xuất |
| X02 | Trường bắt buộc theo chuẩn không có giá trị | Hồ sơ | Hệ thống sản xuất |
| X03 | Giá trị của trường không thuộc miền giá trị cho phép | Hồ sơ | Hệ thống sản xuất |
| X04 | Quan hệ giữa các bảng dữ liệu không nhất quán | Hồ sơ | Hệ thống sản xuất |
| P01 | Bản đã ký không mở được | Hồ sơ | Hệ thống sản xuất |
| P02 | Bản đã ký không đúng loại theo loại hồ sơ | Hồ sơ | Hệ thống sản xuất |
| P03 | Thiếu thông tin phiên bản mẫu in | Hồ sơ | Hệ thống sản xuất |
| K01 | Thiếu tệp chữ ký số của một hoặc nhiều biểu mẫu | Hồ sơ | Hệ thống sản xuất |
| K02 | Chữ ký số không kiểm chứng được | Hồ sơ | Hệ thống sản xuất |
| K03 | Chuỗi chứng thư không đầy đủ | Hồ sơ | Hệ thống sản xuất |
| K04 | Không xác định được trạng thái chứng thư tại thời điểm ký | Hồ sơ | Hệ thống sản xuất |
| A01 | Giao diện không phản hồi | Giao diện | Hệ thống sản xuất |
| A02 | Giao diện phản hồi vượt thời gian cho phép | Giao diện | Hệ thống sản xuất |
| A03 | Xác thực với giao diện không thành công | Giao diện | Hai bên |
| A04 | Phản hồi của giao diện thiếu trường bắt buộc | Giao diện | Hệ thống sản xuất |
| A05 | Gọi lại giao diện với cùng tham số trả về kết quả khác | Giao diện | Hệ thống sản xuất |
| N01 | Giao dịch loại hoàn hoặc điều chỉnh không có mã giao dịch gốc | Bản ghi | Hệ thống sản xuất |
| N02 | Trường hình thức thanh toán không có giá trị | Bản ghi | Hệ thống sản xuất |
| N03 | Mã giao dịch trùng trong phạm vi đơn vị | Bản ghi | Hệ thống sản xuất |
| N04 | Trường giá vốn của lô không có giá trị | Bản ghi | Hệ thống sản xuất |
| N05 | Tổng tiền thu không khớp doanh thu đã thu theo dữ liệu chi phí, vượt ngưỡng cho phép | Kỳ | Hai bên |