Lịch hẹn

Lịch hẹn của phòng khám, gồm lịch bệnh nhân tự đặt qua ứng dụng hoặc website.

Mô tả	HTTP request
Lấy danh sách lịch hẹn	`GET /appointments`
Lấy một lịch hẹn	`GET /appointments/{id}`

scheduledAt là thời điểm UTC. Phòng khám lưu giờ hẹn theo giờ tường (UTC+7); API đã đổi sang UTC để bạn không cần biết múi giờ của phòng khám.
Dùng status, đừng dùng giờ. REQUESTED là bệnh nhân đặt chờ xác nhận; ERROR là dữ liệu lỗi và nên bỏ qua.

Lấy danh sách lịch hẹn

GET/api/integration/v1/appointments

Các lịch hẹn, gồm cả lịch bệnh nhân tự đặt, theo thứ tự cập nhật tăng dần. Lịch đã huỷ vẫn được trả về với status là CANCELLED; chỉ lịch bị xoá mới là tombstone. Cần quyền appointments: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 lịch hẹn: { requestId, appointments, nextCursor }. Mỗi phần tử của appointments có các trường của một lịch hẹ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 `appointments: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/appointments?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /appointments?limit=2

{
  "requestId": "req_7c1f3a",
  "appointments": [
    {
      "id": "a41f9c0e-7d25-4b8a-9c36-0e5b1d7a2f44",
      "code": "LH-20261020-003",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "phone": "0900000001",
      "scheduledAt": "2026-10-20T02:30:00.000Z",
      "status": "BOOKED",
      "doctorName": "BS. Trần Thị B",
      "room": "Phòng 2",
      "reason": "Tái khám",
      "createdAt": "2026-10-15T07:00:00.000Z",
      "updatedAt": "2026-10-15T07:00:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Lấy một lịch hẹn

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

Trả một lịch hẹn theo id, hoặc tombstone nếu lịch đã bị xoá. Cần quyền appointments:read.

Tham số đường dẫn

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

Phản hồi 200

{ requestId, appointment }. appointment là lịch hẹn (các trường dưới đây) hoặc một tombstone.

Một lịch hẹn

Trường	Ý nghĩa
`id`string	Mã ổn định của lịch hẹn, không bao giờ đổi. Dùng làm khoá chống trùng.
`code`string	Mã lịch hẹn hiển thị. Chỉ để tham chiếu.
`patientId`string \| null	`id` của bệnh nhân trong `/patients`; `null` nếu chưa gắn với hồ sơ bệnh nhân.
`phone`string \| null	Số điện thoại để ghép khi lịch chưa gắn hồ sơ; `null` nếu không có.
`scheduledAt`date-time \| null	Giờ hẹn (UTC); `null` nếu không xác định được. Giờ phòng khám = UTC+7.
`status`enum	`REQUESTED` bệnh nhân đặt, chờ xác nhận `BOOKED` đã xác nhận `ARRIVED` đã đến `IN_PROGRESS` đang khám `FINISHED` đã khám xong `CANCELLED` đã huỷ `ERROR` lỗi dữ liệu, bỏ qua
`doctorName`string	Tên bác sĩ phụ trách; chuỗi rỗng nếu chưa chỉ định.
`room`string	Phòng khám; chuỗi rỗng nếu chưa xếp.
`reason`string	Lý do hẹn, văn bản tự do, có thể chứa thông tin sức khỏe; chuỗi rỗng nếu không có.
`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 lịch hẹn đã xoá.
`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ộ.

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 `appointments: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/appointments/$APPOINTMENT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /appointments/{id}

{
  "requestId": "req_7c1f3a",
  "appointment": {
    "id": "a41f9c0e-7d25-4b8a-9c36-0e5b1d7a2f44",
    "code": "LH-20261020-003",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "phone": "0900000001",
    "scheduledAt": "2026-10-20T02:30:00.000Z",
    "status": "BOOKED",
    "doctorName": "BS. Trần Thị B",
    "room": "Phòng 2",
    "reason": "Tái khám",
    "createdAt": "2026-10-15T07:00:00.000Z",
    "updatedAt": "2026-10-15T07:00:00.000Z",
    "deletedAt": null
  }
}

200 Lịch hẹn đã xoá

{
  "requestId": "req_7c1f3a",
  "appointment": {
    "id": "d2b8f6a1-4c97-4e03-b5a8-1f6e9d3c7a20",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}