Liệu trình

Gói liệu trình của bệnh nhân: số buổi đã làm trên tổng số và số tiền đã thu.

Mô tả	HTTP request
Lấy danh sách liệu trình	`GET /therapy-plans`
Lấy một liệu trình	`GET /therapy-plans/{id}`

Trạng thái được suy ra như trên màn hình của phòng khám: COMPLETED khi đã làm đủ số buổi, IN_PROGRESS khi đã làm ít nhất một buổi, CANCELLED khi bị huỷ.

Lấy danh sách liệu trình

GET/api/integration/v1/therapy-plans

Các gói liệu trình, theo thứ tự cập nhật tăng dần. completedSessions và paidAmount đổi khi ghi nhận buổi hoặc thu tiền, và khi đó updatedAt cũng đổi. Cần quyền therapy: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 liệu trình: { requestId, therapyPlans, nextCursor }. Mỗi phần tử của therapyPlans có các trường của một liệu trình, 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 `therapy: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/therapy-plans?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /therapy-plans?limit=2

{
  "requestId": "req_7c1f3a",
  "therapyPlans": [
    {
      "id": "7b2e4d90-1a63-4c85-b7f0-3d9a6c1e8b52",
      "code": "LT-20261001-001",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "name": "Liệu trình châm cứu 10 buổi",
      "sessionCount": 10,
      "completedSessions": 4,
      "status": "IN_PROGRESS",
      "totalPrice": 3500000,
      "paidAmount": 3500000,
      "createdAt": "2026-10-01T02:00:00.000Z",
      "updatedAt": "2026-10-12T07:30:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Lấy một liệu trình

GET/api/integration/v1/therapy-plans/{id}

Trả một liệu trình theo id, hoặc tombstone nếu liệu trình đã bị xoá. Cần quyền therapy:read.

Tham số đường dẫn

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

Phản hồi 200

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

Một liệu trình

Trường	Ý nghĩa
`id`string	Mã ổn định của liệu trình, không bao giờ đổi. Dùng làm khoá chống trùng.
`code`string	Mã liệu trình 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.
`name`string	Tên liệu trình.
`sessionCount`integer	Tổng số buổi của liệu trình.
`completedSessions`integer	Số buổi đã thực hiện.
`status`enum	`NEW` chưa làm buổi nào `IN_PROGRESS` đang thực hiện `COMPLETED` đã đủ số buổi `CANCELLED` đã huỷ
`totalPrice`integer	Tổng giá của liệu trình (đồng).
`paidAmount`integer	Số tiền đã thu cho liệu trình (đồng); giảm khi hoàn trả hóa đơn thu tiền.
`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 liệu trình đã 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 `therapy: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/therapy-plans/$THERAPY_PLAN_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /therapy-plans/{id}

{
  "requestId": "req_7c1f3a",
  "therapyPlan": {
    "id": "7b2e4d90-1a63-4c85-b7f0-3d9a6c1e8b52",
    "code": "LT-20261001-001",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "name": "Liệu trình châm cứu 10 buổi",
    "sessionCount": 10,
    "completedSessions": 4,
    "status": "IN_PROGRESS",
    "totalPrice": 3500000,
    "paidAmount": 3500000,
    "createdAt": "2026-10-01T02:00:00.000Z",
    "updatedAt": "2026-10-12T07:30:00.000Z",
    "deletedAt": null
  }
}

200 Liệu trình đã xoá

{
  "requestId": "req_7c1f3a",
  "therapyPlan": {
    "id": "9e3a5c17-2d48-4f60-a1b9-7c0d6e8f4b35",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}