Bệnh nhân

Hồ sơ hành chính tối thiểu của bệnh nhân: đủ để nhận ra một người và gọi điện, không có CCCD, email, địa chỉ, dị ứng hay ngày sinh đầy đủ.

Mô tả	HTTP request
Lấy danh sách bệnh nhân	`GET /patients`
Lấy một bệnh nhân	`GET /patients/{id}`

Gộp hồ sơ. Khi phòng khám gộp hai hồ sơ trùng, hồ sơ bị gộp trở thành tombstone có mergedIntoId, còn lịch hẹn, hóa đơn và liệu trình của nó được chuyển sang hồ sơ còn lại (và cũng có updatedAt mới).
Số điện thoại là null khi phòng khám chưa có số.

Lấy danh sách bệnh nhân

GET/api/integration/v1/patients

Các bệnh nhân của phòng khám, theo thứ tự cập nhật tăng dần. Hồ sơ đã gộp vào hồ sơ khác vẫn có mặt, ở dạng tombstone kèm mergedIntoId. Cần quyền patients:read.

Tham số truy vấn

Tham số	Mô tả
`updatedSince`string · date-timetuỳ chọn	Chỉ lấy bản ghi có `updatedAt` từ thời điểm này trở đi, gồm cả đúng thời điểm này. ISO 8601 có múi giờ, ví dụ `2026-10-01T00:00:00.000Z`. Cách dùng: Đồng bộ liên tục.
`cursor`stringtuỳ chọn	Giá trị `nextCursor` của trang trước, nguyên văn. Bỏ trống ở trang đầu. Xem Phân trang.
`limit`integertuỳ chọn	Từ 1 đến 500. Mặc định `200`.

Phản hồi 200

Một trang bệnh nhân: { requestId, patients, nextCursor }. Mỗi phần tử của patients có các trường của một bệnh nhân, hoặc là một tombstone. nextCursor khác null nghĩa là còn trang sau.

Lỗi

Mã lỗi	Khi nào
`INVALID_UPDATED_SINCE`400	`updatedSince` không phải thời điểm ISO 8601 có múi giờ, hoặc xuất hiện nhiều lần.
`INVALID_CURSOR`400	`cursor` không hợp lệ, hoặc do API khác cấp ra.
`INVALID_LIMIT`400	`limit` không phải số nguyên từ 1 đến 500.
`UNKNOWN_PARAMETER`400	Tham số không có trong bảng trên, kể cả gõ sai tên.
`INSUFFICIENT_SCOPE`403	Key không có quyền `patients:read`.

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

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/patients?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /patients?limit=2

{
  "requestId": "req_7c1f3a",
  "patients": [
    {
      "id": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "code": "BN-000412",
      "name": "Nguyễn Văn A",
      "phone": "0900000001",
      "gender": "MALE",
      "birthYear": 1984,
      "patientType": "OLD",
      "status": "ACTIVE",
      "registeredDate": "2026-03-02",
      "createdAt": "2026-03-02T01:30:00.000Z",
      "updatedAt": "2026-10-04T08:12:45.120Z",
      "deletedAt": null
    },
    {
      "id": "c9a1d7e2-0b34-4c6f-8a51-6e7f3b2d9c08",
      "deletedAt": "2026-10-05T03:00:00.000Z",
      "updatedAt": "2026-10-05T03:00:00.000Z",
      "mergedIntoId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10"
    }
  ],
  "nextCursor": "djF8cGF0aWVudHN8MjAyNi0xMC0wNVQwMzowMDowMC4wMDBafGM5YTFkN2UyLTBiMzQtNGM2Zi04YTUxLTZlN2YzYjJkOWMwOA"
}

Lấy một bệnh nhân

GET/api/integration/v1/patients/{id}

Trả một bệnh nhân theo id, hoặc tombstone nếu hồ sơ đã được gộp. Cần quyền patients:read.

Tham số đường dẫn

Tham số	Mô tả
`id`stringbắt buộc	`id` của bệnh nhân: trường `id` của một phần tử trong Lấy danh sách bệnh nhân.

Phản hồi 200

{ requestId, patient }. patient là bệnh nhân (các trường dưới đây) hoặc một tombstone.

Một bệnh nhân

Trường	Ý nghĩa
`id`string	Mã ổn định của bệnh nhân, không bao giờ đổi. Dùng làm khoá chống trùng.
`code`string	Mã hồ sơ hiển thị. Chỉ để tham chiếu.
`name`string	Họ tên bệnh nhân.
`phone`string \| null	Số điện thoại dạng `0…`; `null` nếu phòng khám chưa có số.
`gender`enum	`MALE` nam `FEMALE` nữ `OTHER` khác `UNKNOWN` chưa rõ
`birthYear`integer \| null	Năm sinh; `null` nếu chưa có. Không trả ngày tháng sinh đầy đủ.
`patientType`enum	`NEW` khách mới `OLD` khách cũ `RE_EXAMINATION` tái khám theo hẹn
`status`enum	`ACTIVE` đang sử dụng `INACTIVE` phòng khám đã vô hiệu hoá hồ sơ này
`registeredDate`date	Ngày lập hồ sơ (giờ phòng khám), `YYYY-MM-DD`. Không phải ngày khám đầu tiên: hồ sơ có thể được lập trước khi khám.
`createdAt`date-time	Thời điểm tạo bản ghi (UTC).
`updatedAt`date-time	Thời điểm bản ghi thay đổi lần cuối (UTC). Khoá sắp xếp, cùng với `id`, của việc đồng bộ.
`deletedAt`null	Luôn `null` với bản ghi còn tồn tại.

Bản ghi đã xoá (tombstone)

Trường	Ý nghĩa
`id`string	`id` của hồ sơ đã gộp.
`deletedAt`date-time	Thời điểm bản ghi bị xoá hoặc gộp (UTC). Có giá trị nghĩa là đây là tombstone: hãy xoá bản ghi này ở phía bạn.
`updatedAt`date-time	Thời điểm bản ghi thay đổi lần cuối (UTC). Khoá sắp xếp, cùng với `id`, của việc đồng bộ.
`mergedIntoId`string \| null	`id` của hồ sơ còn lại sau khi gộp; `null` nếu hồ sơ bị xoá mà không phải do gộp. Lịch hẹn, hóa đơn và liệu trình của hồ sơ cũ đã được chuyển sang hồ sơ này.

Lỗi

Mã lỗi	Khi nào
`UNKNOWN_PARAMETER`400	Yêu cầu có tham số truy vấn. API này chỉ nhận `id` trong đường dẫn.
`INSUFFICIENT_SCOPE`403	Key không có quyền `patients:read`.
`NOT_FOUND`404	Không có bản ghi với `id` này, hoặc nó thuộc phòng khám khác. Hai trường hợp trả giống hệt nhau.

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

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/patients/$PATIENT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /patients/{id}

{
  "requestId": "req_7c1f3a",
  "patient": {
    "id": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "code": "BN-000412",
    "name": "Nguyễn Văn A",
    "phone": "0900000001",
    "gender": "MALE",
    "birthYear": 1984,
    "patientType": "OLD",
    "status": "ACTIVE",
    "registeredDate": "2026-03-02",
    "createdAt": "2026-03-02T01:30:00.000Z",
    "updatedAt": "2026-10-04T08:12:45.120Z",
    "deletedAt": null
  }
}

200 Hồ sơ đã gộp

{
  "requestId": "req_7c1f3a",
  "patient": {
    "id": "c9a1d7e2-0b34-4c6f-8a51-6e7f3b2d9c08",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z",
    "mergedIntoId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10"
  }
}