# Lô hạn sử dụng

> Base URL: `https://pos.pages.fm/api/v1`. Xác thực bằng tham số truy vấn `api_key`.

## Danh sách lô hạn sử dụng

`GET /shops/{SHOP_ID}/lots`

Lấy danh sách lô hạn sử dụng của sản phẩm (sản phẩm có loại `LOT`). Mỗi lô có mã lô (`custom_id`), ngày sản xuất, hạn sử dụng và được gắn với một hoặc nhiều mẫu mã của sản phẩm qua `lot_variations`.

Các giá trị thời gian (`expire_date`, `manufacturing_date`, ...) theo múi giờ UTC.

### Tham số

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Mã shop |
| `page` | query | integer |  | Số trang |
| `page_size` | query | integer |  | Kích thước trang |
| `search` | query | string |  | Tìm theo mã lô, mã sản phẩm/ID hiển thị sản phẩm hoặc mã mẫu mã/ID hiển thị mẫu mã |
| `warehouse_ids[]` | query | string[] |  | Lọc các lô có bản ghi tồn tại các kho này (lô chưa có bản ghi tồn ở kho nào vẫn được trả về) |
| `remain_quantity` | query | string |  | Lọc theo số lượng có thể bán của lô, JSON gồm: - `type`: `greaterOrEqual` \| `smallerOrEqual` \| `between` - `value`: số lượng (dùng với `greaterOrEqual` / `smallerOrEqual`) - `minValue`, `maxValue`: khoảng số lượng (dùng với `between`) - `warehouseId`: mã kho, `all` cho tất cả kho - `isFilterTotal`: `true` để so sánh tổng các kho, ngược lại so sánh từng bản ghi tồn theo kho |
| `actual_remain_quantity` | query | string |  | Lọc theo tồn kho (số lượng thực tế trong kho) của lô, JSON cùng định dạng với `remain_quantity` |
| `min_retail_price` | query | integer |  | Lọc các lô có mẫu mã được gắn với giá bán lớn hơn hoặc bằng giá trị này |
| `max_retail_price` | query | integer |  | Lọc các lô có mẫu mã được gắn với giá bán nhỏ hơn hoặc bằng giá trị này |
| `expiry_date` | query | string |  | Lọc theo hạn sử dụng, chỉ trả về các lô còn số lượng có thể bán (`remain_quantity > 0`) ở ít nhất một kho: - `in_date`: còn hạn - `out_of_date`: hết hạn - JSON `{"start_date": <unix>, "end_date": <unix>}`: hạn sử dụng nằm trong khoảng (unix timestamp tính bằng giây) |
| `range` | query | string |  | Lọc theo khoảng thời gian, JSON `{"key": ..., "since": <unix>, "until": <unix>}` (unix timestamp tính bằng giây, `until` mặc định là hiện tại). `key`: - `inserted_at`: theo thời gian tạo (mặc định) - `manufacturing`: theo ngày sản xuất - `expire`: theo hạn sử dụng |
| `sort_field` | query | string |  | Sắp xếp, JSON `{"field": ..., "order": "ascend" \| "descend"}`. `field`: `mfg` (ngày sản xuất), `exp` (hạn sử dụng), `inserted_at` (thời gian tạo), `updated_at` (thời gian cập nhật). Mặc định: hạn sử dụng giảm dần, sau đó thời gian tạo giảm dần |

### Phản hồi

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "d0e4a4b0-0c6d-4dc1-8252-447bba021b3e",
      "custom_id": "LO-XA",
      "expire_date": "2027-10-11T17:00:00",
      "manufacturing_date": "2026-10-11T17:00:00",
      "inserted_at": "2026-10-12T07:35:10.000000",
      "updated_at": "2026-10-12T07:35:10.000000",
      "product": {
        "id": "da9b9e28-af65-4456-916e-ac8f8eb00334",
        "name": "TEST6972#2",
        "type": "LOT",
        "image": null,
        "tags": [],
        "custom_id": "SP-L",
        "display_id": 13721,
        "bonus_products": [],
        "brand_id": null,
        "creator_id": "84616be7-7a6b-4f58-af37-2c64d9ee04a9",
        "inserted_at": "2026-10-12T07:29:45",
        "is_published": true,
        "is_sell_negative": null,
        "limit_quantity_to_warn": 0,
        "limit_quantity_to_warn_by_warehouse": null,
        "manipulation_warehouses": [],
        "materials": [],
        "measure_group_id": null,
        "note": null,
        "note_product": "",
        "product_attributes": [],
        "supplier_product_ids": [],
        "warning_by_variation": false,
        "categories": []
      },
      "lot_variations": [
        {
          "id": "a560ac18-8d5b-46ef-82f6-bf1474ad1c8f",
          "variation_id": "daf62728-ae6f-4354-94e4-4a12855c4293",
          "inserted_at": "2026-10-12T07:35:10.000000",
          "updated_at": "2026-10-12T07:35:10.000000"
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 30,
  "total_entries": 1,
  "total_pages": 1
}
```