NHÀ PHÁT TRIỂN

Danh mục API

Sử dụng REST/FHIR có phiên bản với xác thực rõ ràng, tính lũy đẳng (idempotency) khi cần, lỗi có phân loại và mã tương quan phục vụ vận hành.

01 / KHÁI NIỆM

Hợp đồng tích hợp

Hợp đồng

Xác định rõ đầu vào, quyền, phiên bản và môi trường áp dụng.

Độ tin cậy

Xử lý tính lũy đẳng/thử lại/hết thời gian chờ phù hợp với từng loại lỗi.

Bảo mật

Không để thông tin xác thực/khóa bí mật lọt vào nhật ký và áp dụng đặc quyền tối thiểu.

Vận hành

Mã tương quan, người phụ trách, giám sát và khôi phục phải kiểm thử được.

02 / QUY TRÌNH

Từ môi trường thử nghiệm tới bằng chứng

01Xác định yêu cầu
02Cấu hình môi trường thử nghiệm (sandbox)
03Kiểm thử luồng chuẩn
04Kiểm thử lỗi/ranh giới trách nhiệm
05Xác minh nhật ký/bằng chứng
06Rà soát trước vận hành chính thức

03 / VÍ DỤ

Tạo lịch hẹn khám từ xa / truy xuất DiagnosticReport

cURL / mã giả

POST /fhir/Appointment  # synthetic appointment
GET /fhir/DiagnosticReport?subject=Patient/synthetic-001

04 / BẢO MẬT & VẬN HÀNH

Vận hành chính thức là quyết định dựa trên bằng chứng

Tích hợp API phải chứng minh được tính lũy đẳng khi cần, xử lý lỗi có phân loại, thử lại có giới hạn, mã tương quan và khôi phục khi thành phần phụ thuộc gặp lỗi trước khi đưa vào vận hành chính thức.

HỢP ĐỒNG VÍ DỤ

Đọc hợp đồng API trước khi viết ứng dụng khách

Đây là ví dụ tổng hợp nhằm minh họa cấu trúc tài liệu; không phải tuyên bố rằng điểm kết nối vận hành chính thức mang tên này đã được công bố.

Tạo Observation · VÍ DỤ

POST /fhir/Observation · OAuth scope: observation.write · application/fhir+json · khóa lũy đẳng (idempotency key) khi hợp đồng triển khai hỗ trợ thao tác tạo có thể thử lại.

Đọc DiagnosticReport · VÍ DỤ

GET /fhir/DiagnosticReport?subject=Patient/{id} · quyền đọc theo phạm vi (scope) · phân trang/bộ lọc rõ ràng và thông tin chẩn đoán kiểu OperationOutcome khi có lỗi.

Sự kiện webhook · VÍ DỤ

Lệnh gọi lại (callback) có chữ ký, kèm mã định danh lần gửi/sự kiện, dấu thời gian và mã tương quan; bên nhận xác nhận nhanh và loại bỏ trùng lặp trước khi xử lý bất đồng bộ.

Lỗi có phân loại

400 validation_error · 401 invalid_token · 403 insufficient_scope · 409 conflict khi áp dụng · 429 rate_limited; lỗi từ thành phần phụ thuộc phải được phân biệt với lỗi phía ứng dụng khách.