iClinic Developers

Lượt khám

Các lần bệnh nhân đến khám trong một khoảng ngày. Khác bốn API còn lại, lượt khám lọc theo ngày khám và chia trang bằng số trang (Phân trang).

Lấy danh sách lượt khám

GET/api/integration/v1/encounters

Trả về các lượt khám có visitDate trong khoảng [from, to], mới nhất trước. Cần quyền encounters:read.

Mặc định không có lượt khám đã huỷ. Để đánh dấu lịch hẹn “Đã huỷ”, gọi với status=all (mọi trạng thái) hoặc status=CANCELLED.

Tham số truy vấn

Tham sốMô tả
fromstring · datebắt buộc Ngày khám bắt đầu, YYYY-MM-DD, theo giờ phòng khám.
tostring · datetuỳ chọn Ngày khám kết thúc, gồm cả ngày này. Mặc định: hôm nay. Khoảng from–to tối đa 31 ngày.
statusstring · enumtuỳ chọn Bỏ trống: mọi trạng thái trừ CANCELLED. all: tất cả, gồm cả đã huỷ. Hoặc một trong NEW ONGOING FINISHED REOPENED LOCKED CANCELLED. Không phân biệt hoa thường.
pageintegertuỳ chọn Số trang, bắt đầu từ 0. Mặc định 0.
pageSizeintegertuỳ chọn Từ 1 đến 500. Mặc định 200.

Phản hồi 200

Rê chuột hoặc dùng Tab trên một dòng để xem trường đó nằm ở đâu trong JSON.

TrườngÝ nghĩa
requestIdstringMã yêu cầu, trùng header X-Request-Id. Gửi kèm khi cần hỗ trợ.
totalintegerTổng số lượt khám khớp bộ lọc, trên mọi trang.
encountersarrayCác lượt khám của trang hiện tại. Cùng from, to, page, pageSize được trả lại nguyên như đã gửi (sau khi áp mặc định).

Một lượt khám

TrườngÝ nghĩa
encounterUuidstringKhoá chống trùng. Mã ổn định của lượt khám, không bao giờ đổi.
idstringMã hiển thị (mã hồ sơ). Chỉ để tham chiếu; có thể được cấp lại nên đừng dùng làm khoá chống trùng.
patientNamestringTên bệnh nhân.
phonestring | nullSố điện thoại; null nếu phòng khám chưa có số.
visitDatedateNgày khám YYYY-MM-DD theo giờ phòng khám. Hệ thống lưu ngày, không lưu giờ khám.
checkedInAtdate-time | nullThời điểm tiếp nhận (UTC) khi biết được, ngược lại null. Đừng coi null là chưa đến — hãy dựa vào status.
completedAtdate-time | nullThời điểm kết thúc khám (UTC) hoặc null.
statusenum
  • NEW đã đến / tiếp nhận
  • ONGOING đang khám
  • FINISHED đã khám xong
  • REOPENED mở lại
  • LOCKED đã khoá hồ sơ
  • CANCELLED đã huỷ
patientTypeenum
  • NEW khách mới
  • OLD khách cũ
  • RE_EXAMINATION tái khám theo hẹn
diagnosisstringChẩn đoán; chuỗi rỗng nếu chưa có.
icd10CodestringMã ICD-10; chuỗi rỗng nếu chưa có.
patientIdstring | nullThêm từ 1.1.0. id của bệnh nhân trong /patients; null nếu lượt khám chưa gắn với hồ sơ bệnh nhân.
followUpDatedate | nullThêm từ 1.1.0. Ngày tái khám bác sĩ hẹn, YYYY-MM-DD; null nếu không hẹn.
updatedAtdate-timeThêm từ 1.1.0. Thời điểm lượt khám thay đổi lần cuối (UTC).

Lỗi

Mã lỗiKhi nào
INVALID_DATE400Thiếu hoặc sai định dạng from, to.
INVALID_RANGE400to trước from, hoặc khoảng quá 31 ngày.
INVALID_STATUS400status không hợp lệ.
INVALID_PAGE400page hoặc pageSize sai.
INSUFFICIENT_SCOPE403Key không có quyền encounters:read.

Mọi API còn có thể trả 401, 429 và 5xx, xem Mã lỗi.

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/encounters?from=2026-09-14&to=2026-09-19&status=all&page=0&pageSize=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"
200 Phản hồi
{
  "requestId": "req_7c1f3a",
  "from": "2026-09-14",
  "to": "2026-09-19",
  "page": 0,
  "pageSize": 200,
  "total": 1,
  "encounters": [
    {
      "id": "BA-000123",
      "encounterUuid": "3f0c9a52-6d1b-4e7a-9b1e-2a4c8d5e7f10",
      "patientName": "Nguyễn Văn A",
      "phone": "0900000001",
      "visitDate": "2026-09-19",
      "checkedInAt": "2026-09-19T02:14:05.000Z",
      "completedAt": null,
      "status": "ONGOING",
      "patientType": "OLD",
      "diagnosis": "Tăng huyết áp",
      "icd10Code": "I10",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "followUpDate": "2026-09-26",
      "updatedAt": "2026-09-19T03:02:40.000Z"
    }
  ]
}