Hóa đơn

Hóa đơn thu tiền kèm các dòng. Tiền luôn là số nguyên, đơn vị đồng.

Mô tả	HTTP request
Lấy danh sách hóa đơn	`GET /receipts`
Lấy một hóa đơn	`GET /receipts/{id}`

Doanh thu = tổng paidAmount của các hóa đơn có deletedAt là null và status khác CANCELLED, REFUNDED, theo receiptDate trong khoảng ngày cần tính. Đúng bằng “Doanh thu” trong Báo cáo của phòng khám; tổng total cùng điều kiện là “Doanh thu dự kiến”.
Hóa đơn đã huỷ hoặc hoàn trả vẫn được trả về kèm status, để bạn phân biệt “hóa đơn bị huỷ” với “chưa đồng bộ”. Hoàn trả luôn là hoàn toàn bộ số đã thu.

Lấy danh sách hóa đơn

GET/api/integration/v1/receipts

Các hóa đơn kèm từng dòng, theo thứ tự cập nhật tăng dần. Hóa đơn đã huỷ hoặc hoàn trả vẫn được trả về, kèm status. Cần quyền receipts: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 hóa đơn: { requestId, receipts, nextCursor }. Mỗi phần tử của receipts có các trường của một hóa đơ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 `receipts: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/receipts?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /receipts?limit=2

{
  "requestId": "req_7c1f3a",
  "receipts": [
    {
      "id": "e7d3b1a4-52c8-4f19-a0b6-9c4d8e2f1a37",
      "code": "HD-20261004-002",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "encounterId": "3f0c9a52-6d1b-4e7a-9b1e-2a4c8d5e7f10",
      "total": 350000,
      "paidAmount": 350000,
      "paymentMethod": "CASH",
      "status": "PAID",
      "receiptDate": "2026-10-04",
      "lines": [
        {
          "name": "Khám chuyên khoa",
          "quantity": 1,
          "unitPrice": 200000,
          "total": 200000,
          "sourceType": "SERVICE"
        },
        {
          "name": "Vitamin B1",
          "quantity": 10,
          "unitPrice": 15000,
          "total": 150000,
          "sourceType": "MEDICATION"
        }
      ],
      "createdAt": "2026-10-04T08:10:00.000Z",
      "updatedAt": "2026-10-04T08:10:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Lấy một hóa đơn

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

Trả một hóa đơn kèm các dòng theo id, hoặc tombstone nếu hóa đơn đã bị xoá. Cần quyền receipts:read.

Tham số đường dẫn

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

Phản hồi 200

{ requestId, receipt }. receipt là hóa đơn (các trường dưới đây) hoặc một tombstone.

Một hóa đơn

Trường	Ý nghĩa
`id`string	Mã ổn định của hóa đơn, không bao giờ đổi. Dùng làm khoá chống trùng.
`code`string	Số hóa đơ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.
`encounterId`string \| null	`encounterUuid` của lượt khám mà hóa đơn thu tiền; `null` với hóa đơn bán lẻ hoặc thu tiền liệu trình.
`total`integer	Tổng phải trả của hóa đơn sau chiết khấu (đồng).
`paidAmount`integer	Số tiền đã thu (đồng), gồm cả tạm ứng đã trừ và các lần thu nợ. Với hóa đơn `REFUNDED` đây là số đã thu trước khi hoàn.
`paymentMethod`string	Phương thức thu lúc lập hóa đơn, chữ hoa. Thường gặp `CASH` (tiền mặt), `BANK_TRANSFER` (chuyển khoản). Có thể có giá trị khác; đừng giả định danh sách đóng.
`status`enum	`PAID` đã thu đủ `PARTIAL` còn nợ `UNPAID` chưa thu `CANCELLED` đã huỷ (chưa thu đồng nào) `REFUNDED` đã hoàn trả toàn bộ
`receiptDate`date	Ngày thu (giờ phòng khám), `YYYY-MM-DD`: ngày mà doanh thu được tính.
`lines`array	Các dòng của hóa đơ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 hóa đơ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 `receipts: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/receipts/$RECEIPT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /receipts/{id}

{
  "requestId": "req_7c1f3a",
  "receipt": {
    "id": "e7d3b1a4-52c8-4f19-a0b6-9c4d8e2f1a37",
    "code": "HD-20261004-002",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "encounterId": null,
    "total": 350000,
    "paidAmount": 100000,
    "paymentMethod": "BANK_TRANSFER",
    "status": "PARTIAL",
    "receiptDate": "2026-10-04",
    "lines": [
      {
        "name": "Liệu trình châm cứu",
        "quantity": 1,
        "unitPrice": 350000,
        "total": 350000,
        "sourceType": "MANUAL"
      }
    ],
    "createdAt": "2026-10-04T08:10:00.000Z",
    "updatedAt": "2026-10-06T03:00:00.000Z",
    "deletedAt": null
  }
}

200 Hóa đơn đã xoá

{
  "requestId": "req_7c1f3a",
  "receipt": {
    "id": "f1c4a7d9-8e25-4b63-9d0a-5c2e7b1f3a86",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}