# Purchase

> Base URL: `https://pos.pages.fm/api/v1`. Authenticate with the `api_key` query parameter.

## List of purchases

`GET /shops/{SHOP_ID}/purchases`

Get list of purchases

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `page` | query | integer |  | Page number |
| `page_size` | query | integer |  | Page size |
| `status` | query | integer |  | Status Values: `-2` All status, `-1` New, `0` Confirmed, `1` Imported goods, `2` Canceled. |
| `type` | query | string |  | Type |
| `get_time_import` | query | boolean |  | Get time import |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "96bbc665-3fd5-4efc-9d8a-0110ecfa1754",
      "display_id": 6392,
      "status": 0,
      "time_import": "2025-12-02T07:41:50.363889",
      "total_quantity": 1,
      "total_remain_quantity": 1,
      "total_price": 200000,
      "total_remain_price": 200000,
      "note": "nhập kho sản phẩm",
      "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da",
      "supplier_products_id": 293,
      "supplier": {
        "id": 724,
        "name": "CT TNHH Hồng Hà",
        "custom_id": "HH"
      },
      "discount": 10000,
      "transport_fee": 10000,
      "prepaid_debt": 100000,
      "auto_create_debts": true,
      "not_create_transaction": true,
      "is_lock": null,
      "created_type": "actual_purchase",
      "tags": [
        1
      ],
      "tag_info": [
        {
          "id": 1,
          "name": "Nhập hàng để bán"
        }
      ],
      "items": [
        {
          "id": "02cb1ff3-9b21-4e1c-9288-a29c16bd907d",
          "imported_price": 200000,
          "gross_price": 200000,
          "discount": 10000,
          "quantity": 1,
          "variation_id": "20e7d183-c70c-445e-8ce2-4d7e3a378e34",
          "product_name": "Áo nam",
          "note_purchase": "áo nam thời trang",
          "selling_status": "bad",
          "variation": {
            "id": "69416fa6-4c3d-451f-897d-9faa0420c060",
            "display_id": "mauma1",
            "barcode": "mauma1",
            "product_id": "f210413c-dc84-45e5-b722-9dc72ff7c9af",
            "retail_price": 10000,
            "retail_price_after_discount": 10000,
            "remain_quantity": 9,
            "weight": 0,
            "product": {
              "display_id": "Áo nam",
              "name": "Áo nam"
            },
            "variations_warehouses": []
          }
        }
      ],
      "images": [
        "https://content.pancake.vn/user-content-dev2.pancake.vn/2022/7/7/eb376f0bf90f47d25396d49e4d547700f182981b.jpg"
      ],
      "bill_images": [],
      "user_id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
      "user": {
        "id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
        "name": "Vũ Sơn",
        "fb_id": "377936050731194",
        "avatar_url": null
      },
      "inserted_at": "2023-09-20T02:21:51Z",
      "updated_at": "2023-09-20T02:22:05Z",
      "received_at": "2023-09-21T00:00:00Z",
      "separate_by_display_ids": null
    }
  ]
}
```

## Create purchase

`POST /shops/{SHOP_ID}/purchases`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |

### Request body

Request body containing purchase information to create

- `purchase` (object, required): 
  - `note` (string): Note
  - `status` (integer, required): Status
  - `not_create_transaction` (boolean): Not create transaction
  - `auto_create_debts` (boolean): Auto create debts
  - `supplier_products_id` (integer): Supplier products ID
  - `shop_id` (integer): Shop ID
  - `warehouse_id` (string, required): Warehouse ID
  - `change_received_at` (boolean): Change received at
  - `received_at` (integer): Received at (unix timestamp)
  - `images` (string (uri)[]): Purchase images
  - `items` (object[], required): List of products

```json
{
  "purchase": {
    "note": "",
    "status": 1,
    "not_create_transaction": false,
    "auto_create_debts": true,
    "supplier_products_id": 169,
    "shop_id": 20,
    "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da",
    "change_received_at": true,
    "received_at": 1651683600,
    "images": [
      "https://statics.pancake.vn/user-content-dev2.pancake.vn/2021/12/27/18c4500c320cb2e993b3ff4b3be81165df64d3ba.png"
    ],
    "items": [
      {
        "imported_price": 100000,
        "gross_price": 100000,
        "discount": 10000,
        "quantity": 1,
        "variation_id": "29044dcf-2f4c-492f-a0a9-e447b20e21da",
        "index": 0
      }
    ]
  }
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```

## Get purchase

`GET /shops/{SHOP_ID}/purchases/{PURCHASE_ID}`

Get one purchase by ID or display ID, in the same shape as an item of the purchase list. Purchases in warehouses the caller cannot view are reported as not found.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `PURCHASE_ID` | path | string | yes | Purchase ID (UUID) or display ID |

### Responses

- `200` Success (object)
- `404` The purchase does not exist or is not visible to the caller (ErrorResponse)

```json
{
  "success": true,
  "data": {
    "id": "96bbc665-3fd5-4efc-9d8a-0110ecfa1754",
    "display_id": 6392,
    "status": 0,
    "time_import": "2025-12-02T07:41:50.363889",
    "total_quantity": 1,
    "total_remain_quantity": 1,
    "total_price": 200000,
    "total_remain_price": 200000,
    "note": "nhập kho sản phẩm",
    "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da",
    "supplier_products_id": 293,
    "supplier": {
      "id": 724,
      "name": "CT TNHH Hồng Hà",
      "custom_id": "HH"
    },
    "discount": 10000,
    "transport_fee": 10000,
    "prepaid_debt": 100000,
    "auto_create_debts": true,
    "not_create_transaction": true,
    "is_lock": null,
    "created_type": "actual_purchase",
    "tags": [
      1
    ],
    "tag_info": [
      {
        "id": 1,
        "name": "Nhập hàng để bán"
      }
    ],
    "items": [
      {
        "id": "02cb1ff3-9b21-4e1c-9288-a29c16bd907d",
        "imported_price": 200000,
        "gross_price": 200000,
        "discount": 10000,
        "quantity": 1,
        "variation_id": "20e7d183-c70c-445e-8ce2-4d7e3a378e34",
        "product_name": "Áo nam",
        "note_purchase": "áo nam thời trang",
        "selling_status": "bad",
        "variation": {
          "id": "69416fa6-4c3d-451f-897d-9faa0420c060",
          "display_id": "mauma1",
          "barcode": "mauma1",
          "product_id": "f210413c-dc84-45e5-b722-9dc72ff7c9af",
          "retail_price": 10000,
          "retail_price_after_discount": 10000,
          "remain_quantity": 9,
          "weight": 0,
          "product": {
            "display_id": "Áo nam",
            "name": "Áo nam"
          },
          "variations_warehouses": []
        }
      }
    ],
    "images": [
      "https://content.pancake.vn/user-content-dev2.pancake.vn/2022/7/7/eb376f0bf90f47d25396d49e4d547700f182981b.jpg"
    ],
    "bill_images": [],
    "user_id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
    "user": {
      "id": "cee3c05e-5f85-43c4-b27e-889b99c50097",
      "name": "Vũ Sơn",
      "fb_id": "377936050731194",
      "avatar_url": null
    },
    "inserted_at": "2023-09-20T02:21:51Z",
    "updated_at": "2023-09-20T02:22:05Z",
    "received_at": "2023-09-21T00:00:00Z",
    "separate_by_display_ids": null
  }
}
```

## Update purchase

`PUT /shops/{SHOP_ID}/purchases/{PURCHASE_ID}`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `PURCHASE_ID` | path | string | yes | Purchase ID |

### Request body

Request body containing purchase information to update

- `purchase` (object, required): 
  - `note` (string): Note
  - `status` (integer): Status Values: `-1` New, `0` Confirmed, `1` Imported goods, `2` Canceled.
  - `not_create_transaction` (boolean): Not create transaction
  - `auto_create_debts` (boolean): Auto create debts
  - `supplier_products_id` (integer): Supplier products ID
  - `warehouse_id` (string, required): Warehouse ID
  - `change_received_at` (boolean): Change received at
  - `received_at` (integer): Received at
  - `images` (string (uri)[]): Purchase images
  - `items` (object[]): List of products

```json
{
  "purchase": {
    "note": "",
    "status": 1,
    "not_create_transaction": false,
    "auto_create_debts": true,
    "supplier_products_id": 169,
    "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da",
    "change_received_at": true,
    "received_at": 1651683600,
    "images": [
      "https://statics.pancake.vn/user-content-dev2.pancake.vn/2021/12/27/18c4500c320cb2e993b3ff4b3be81165df64d3ba.png"
    ],
    "items": [
      {
        "imported_price": 100000,
        "quantity": 1,
        "variation_id": "29044dcf-2f4c-492f-a0a9-e447b20e21da"
      }
    ]
  }
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```

## Separate purchase

`POST /shops/{SHOP_ID}/purchases/separate`

Separate a purchase into multiple purchases

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |

### Request body

Request body containing purchase separation information

- `newPurchase` (object, required): New purchase information
  - `auto_create_debts` (boolean): Auto create debts
  - `discount` (integer): Discount
  - `images` (string (uri)[]): Purchase images
  - `items` (object[]): List of products
  - `not_create_transaction` (boolean): Not create transaction
  - `note` (string): Note
  - `prepaid_debt` (integer): Prepaid debt
  - `received_at` (integer): Received at
  - `status` (integer): Status
  - `supplier_products_id` (integer): Supplier products ID
  - `tags` (integer[]): Tag IDs
  - `transport_fee` (integer): Shipping fee
  - `warehouse_id` (string): Warehouse ID
- `oldPurchase` (object, required): Old purchase information
  - `id` (string, required): Purchase ID
  - `auto_create_debts` (boolean): Auto create debts
  - `discount` (integer): Discount
  - `images` (string (uri)[]): Purchase images
  - `items` (object[]): List of products
  - `not_create_transaction` (boolean): Not create transaction
  - `note` (string): Note
  - `prepaid_debt` (integer): Prepaid debt
  - `received_at` (integer): Received at
  - `status` (integer): Status
  - `supplier_products_id` (integer): Supplier products ID
  - `tags` (integer[]): Tag IDs
  - `transport_fee` (integer): Shipping fee
  - `warehouse_id` (string): Warehouse ID

```json
{
  "newPurchase": {
    "auto_create_debts": true,
    "discount": 500,
    "images": [
      "https://statics.pancake.vn/user-content-dev2.pancake.vn/2021/12/27/18c4500c320cb2e993b3ff4b3be81165df64d3ba.png"
    ],
    "items": [
      {
        "imported_price": 100000,
        "quantity": 1,
        "variation_id": "ddefd476-bc91-4151-8cd2-2cf5ad227f09",
        "index": 0
      }
    ],
    "not_create_transaction": false,
    "note": "Tách phiếu nhập",
    "prepaid_debt": 20000,
    "received_at": 1683997200,
    "status": 0,
    "supplier_products_id": 293,
    "tags": [
      1
    ],
    "transport_fee": 0,
    "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da"
  },
  "oldPurchase": {
    "auto_create_debts": true,
    "discount": 500,
    "id": "0ecbdb3b-a376-4a3d-9b8a-174ae15ae886",
    "images": [
      "https://statics.pancake.vn/user-content-dev2.pancake.vn/2021/12/27/18c4500c320cb2e993b3ff4b3be81165df64d3ba.png"
    ],
    "items": [
      {
        "imported_price": 100000,
        "quantity": 23,
        "variation_id": "ddefd476-bc91-4151-8cd2-2cf5ad227f09",
        "index": 0
      }
    ],
    "not_create_transaction": false,
    "note": "Nhập hàng để bán",
    "prepaid_debt": 20000,
    "received_at": 1683997200,
    "status": 0,
    "supplier_products_id": 293,
    "tags": [
      1
    ],
    "transport_fee": 0,
    "warehouse_id": "c52e67ad-d9d0-4276-abe4-e0c9f1f7d2da"
  }
}
```

### Responses

- `200` Success (object)

```json
{
  "success": true
}
```