PosApp Open APIs
  1. Sản phẩm
PosApp Open APIs
  • Tổng quan
  • Thẻ PosApp
    • Mã lỗi (error code)
    • API Idempotency
    • Nạp tiền vào thẻ
      POST
    • Kiểm tra trạng thái giao dịch
      POST
  • Thông tin khác
    • Digital Signature
  • Webhook
    • Tổng quan
    • Order Schema
    • Warehouse import Schema
  • Sản phẩm
    • Tạo mới sản phẩm
      POST
    • Sửa một sản phẩm
      PATCH
    • Tồn kho sản phẩm
      POST
  • Khuyến mãi
    • Đồng giá
      • Tạo khuyến mãi
      • Sửa khuyến mãi
    • Xóa khuyến mãi
      POST
  • Đăng ký tài khoản PosApp
    • Danh sách mô hình kinh doanh
      GET
    • Đăng ký tài khoản
      POST
  • Báo cáo
  1. Sản phẩm

Tạo mới sản phẩm

Developing
Test Env
https://retail-api.posapp.vn/
Test Env
https://retail-api.posapp.vn/
POST
api/public/product-masters
API này cho phép thêm một sản phẩm mới vào hệ thống bằng cách gửi dữ liệu sản phẩm thông qua phương thức POST

Request

Header Params
X-API-Key
string 
optional
Api key dùng để xác thực
Body Params multipart/form-data
product_name
string 
required
Tên sản phẩm
Example:
Sản phẩm 1
short_name
string 
optional
Tên ngắn gọn
Example:
SP1
product_code
string 
optional
Mã sản phẩm ( nếu không có hệ thống sẽ tự động tạo ra mã)
product_barcode
string  | null 
optional
Mã barcode sản phẩm
Example:
119821732
description
string 
optional
Mô tả
Example:
Tạo mới SP1
available
integer 
required
Trạng thái sản phẩm 0: tắt, 1: Hoạt động
Example:
1
product_tax
number 
optional
Thuế sản phẩm
>= 0
Example:
0
category_name
string 
required
Tên nhóm sản phẩm (hệ thống sẽ kiểm tra nếu tên chưa có thì hệ thống sẽ tạo mới ngược lại nếu tên nhóm đã tồn tại thì hệ thống sẽ tự động gán sản phẩm cùng vs nhóm sản phẩm đã tồn tại)
Example:
Nước
allow_overselling
boolean 
required
Cho phép bán khi sản phẩm hết hàng
Example:
true
product_price
number 
required
Giá sản phẩm
>= 0
Example:
20000
product_type
integer 
required
Mặc định truyền lên 1
Lưu ý: Đối với mặt hàng là combo thì gửi lên với giá trị là 5
Default:
1
Example:
1
automatically_create_inventory_items
boolean  | null 
optional
Cờ tự động tạo mặt hàng tồn kho: 1: có, 0: không
Lưu ý: Gửi lên 0 nếu không dùng kho
Example:
true
inventory_management_flg
boolean 
optional
Cờ có quản lý kho hay không cũng là cờ nguyên vật liệu: 1: có, 0: không
Lưu ý: Gửi lên 0 nếu không dùng kho
Lưu ý 2: Nếu đã gửi lên cờ automatically_create_inventory_items = 1 thì không cần gửi cờ này nữa vì hệ thống sẽ tự động tích cờ inventory_management_flg này
Example:
true
alert_flg
boolean 
optional
Cờ bật cảnh báo tồn kho: 1 là bật, 0: tắt (Nếu bạn dùng với kho có thể bật hoặc tắt mặc định là sẽ tắt)
Lưu ý: gửi lên 0 nếu không dùng kho
Example:
false
alert_minval
number  | null 
optional
Cờ cảnh báo tồn kho dưới mức ( Nếu bạn bật alert_flg thì có thể gửi lên cở này)
Lưu ý: Không cần gửi lên nếu không dùng kho
Example:
0
alert_maxval
number  | null 
optional
Cờ cảnh báo tồn kho trên mức ( Nếu bạn bật alert_flg thì có thể gửi lên cở này)
Lưu ý: Không cần gửi lên nếu không dùng kho
Example:
0
reseller_flg
boolean 
required
Cờ cho phép bán lẻ mặc định 1 ( Hiển thị trên màn hình bán hàng)
Example:
true
allow_online_sale
boolean 
required
Cờ cho phép bán hàng online mặc định 0
Lưu ý: Hiển thị mặt hàng trên web order thì hãy gửi lên 1
Example:
false
last_input_price
number  | null 
optional
Giá nhập sản phẩm
Example:
0
cost_price
number  | null 
optional
Giá vốn sản phẩm
Example:
0
unit_list
array [object {7}] 
required
Chứa các đơn vị tính gửi lên dạng mảng
Lưu ý: Trong mảng thì luôn phải tồn tại 1 phần tử mảng với key is_primary = 1 để hệ thống có thể xác định xem đơn vị tính nào bán mặc định
Example:
["{\n \"unit_name\": \"cái\",\n \"unit_exchange\": 1,\n \"is_primary\": 1,\n \"sell_flg\": 1,\n \"price\": 20000,\n \"product_barcode\": null\n}","{\n \"unit_name\": \"lốc\",\n \"unit_exchange\": 1,\n \"is_primary\": 0,\n \"sell_flg\": 0,\n \"price\": 25000,\n \"product_barcode\": null\n}"]
unit_name
string 
optional
unit_exchange
number 
optional
price
number 
optional
is_primary
number 
optional
1: mặc định đơn vị tính, 0: Khác
sell_flg
number 
optional
1: có, 0: ko
old_price
number 
optional
product_barcode
string 
optional
thumbnails
array [object {8}]  | null 
optional
Hình ảnh sản phẩm (Gửi lên nếu sản phẩm có hỉnh ảnh)
thumbnail_image
object 
optional
thumbnail_image_x
number 
optional
Mặc định 0
thumbnail_image_y
number 
optional
Mặc định 0
thumbnail_image_w
number 
optional
Gửi lên chiều rộng của hình ảnh
thumbnail_image_h
number 
optional
Gửi lên chiều cao của hình ảnh
thumbnail_image_resize_to_width
number 
optional
Mặc định 0
is_image_change
number 
optional
Mặc định 0
thumbnail_image_resize_to_height
number 
optional
Mặc định 0
feature
string 
optional
Sản phẩm có nhiều biến thể, ví dụ: Màu sắc, Kích thước, Vật liệu, Kiểu dáng, Khác
Lưu ý: Nếu tạo biến thể thì hãy gửi trường này còn chỉ tạo sản phẩm thôi thì không cần gửi
Example:
[ { "name": "Kích thước", "value": [ "l", "s", "m" ] }, { "name": "Màu sắc", "value": [ "xanh", "đỏ", "cam" ] } ]
variants
array [object {6}] 
optional
Nếu bạn có gửi lên feature thì bắt buộc phải thêm key này sẽ chứa các dữ liệu của biến thể như giá bán, giá vốn, giá nhập,...
Lưu ý: Nếu tạo biến thể thì hãy gửi trường này còn chỉ tạo sản phẩm thôi thì không cần gửi
Example:
["{\n \"product_id\": \"0\",\n \"product_name\": \"s / đỏ\",\n \"product_code\": null,\n \"units\": [\n {\n \"product_barcode\": \"null\",\n \"price\": \"0\",\n \"old_price\": \"0\",\n \"cost_price\": \"0\",\n \"last_input_price\": \"0\",\n \"unit_name\": \"cái\",\n \"unit_exchange\": \"1\",\n \"is_primary\": \"true\"\n }\n ],\n \"last_input_price\": \"0\",\n \"cost_price\": \"0\"\n}","{\n \"product_id\": \"0\",\n \"product_name\": \"m / đỏ\",\n \"product_code\": null,\n \"units\": [\n {\n \"product_barcode\": \"null\",\n \"price\": \"0\",\n \"old_price\": \"0\",\n \"cost_price\": \"0\",\n \"last_input_price\": \"0\",\n \"unit_name\": \"cái\",\n \"unit_exchange\": \"1\",\n \"is_primary\": \"true\"\n }\n ],\n \"last_input_price\": \"0\",\n \"cost_price\": \"0\"\n}","{\n \"product_id\": \"0\",\n \"product_name\": \"l / đỏ\",\n \"product_code\": null,\n \"units\": [\n {\n \"product_barcode\": \"null\",\n \"price\": \"0\",\n \"old_price\": \"0\",\n \"cost_price\": \"0\",\n \"last_input_price\": \"0\",\n \"unit_name\": \"cái\",\n \"unit_exchange\": \"1\",\n \"is_primary\": \"true\"\n }\n ],\n \"last_input_price\": \"0\",\n \"cost_price\": \"0\"\n}"]
product_id
number 
optional
Mặc định 0
product_name
string 
optional
Tên biến thể ví dụ: L / Xanh
product_code
string 
optional
Mã biến thể
last_input_price
number 
optional
Giá nhập
cost_price
number 
optional
Giá vốn
units
array [object {5}] 
optional
combo
array [object {5}] 
optional
Tạo combo
Lưu ý: Khi muốn tạo combo thì mới gửi lên trường này còn tạo sản phẩm thì không gửi lên
Lưu ý 2: Key này sẽ truyền lên dạng string array ví dụ "['a','b','c']"
Example:
["[\n {\n \"title\": \"combo nước\",\n \"group_local_id\": \"17422693572593021570685368544\",\n \"select_type\": 1,\n \"max_choose\": 1,\n \"products\": [\n {\n \"local_id\": \"17422693869154621570685368413\",\n \"group_local_id\": \"17422693572593021570685368544\",\n \"product_master_id\": 1119256,\n \"product_id\": 1120566,\n \"name\": \"number 1\",\n \"product_type\": 1,\n \"quantity\": 1,\n \"price\": 0,\n \"unit_id\": 115691,\n \"unit_name\": \"chai\",\n \"unit_exchange\": 1,\n \"quantitative\": 1,\n \"product_master_unit\": [\n {\n \"id\": 1329639,\n \"product_id\": 1120566,\n \"product_master_id\": 1119256,\n \"unit_id\": 115691,\n \"unit_name\": \"chai\",\n \"unit_exchange\": 1,\n \"is_primary\": 1,\n \"cost_price\": 0,\n \"sell_flg\": 1,\n \"product_barcode\": \"\",\n \"available\": 1,\n \"price\": 25000\n }\n ],\n \"combo_price\": 25000,\n \"vat_price\": 0,\n \"hide_component\": false\n },\n {\n \"local_id\": \"17422693906354711570685368811\",\n \"group_local_id\": \"17422693572593021570685368544\",\n \"product_master_id\": 1119252,\n \"product_id\": 1120562,\n \"name\": \"Nutri\",\n \"product_type\": 1,\n \"quantity\": 1,\n \"repeat_type\": 0,\n \"price\": 0,\n \"editable_flg\": 0,\n \"unit_id\": 115691,\n \"unit_name\": \"chai\",\n \"unit_exchange\": 1,\n \"quantitative\": 1,\n \"product_master_unit\": [\n {\n \"id\": 1329636,\n \"product_id\": 1120562,\n \"product_master_id\": 1119252,\n \"shop_id\": 1570685368,\n \"unit_id\": 115691,\n \"unit_name\": \"chai\",\n \"unit_exchange\": 1,\n \"is_primary\": 1,\n \"cost_price\": 0,\n \"product_material\": \"[]\",\n \"sell_flg\": 1,\n \"product_barcode\": \"\",\n \"available\": 1,\n \"old_price\": 0,\n \"default_inventory_management_flg\": false,\n \"price\": 25000\n }\n ],\n \"combo_price\": 25000,\n \"vat_price\": 0,\n \"hide_component\": false\n }\n ]\n }\n]"]
title
string 
optional
group_local_id
string 
optional
Mã này bạn sẽ tự gen với giá trị là 1 dãy số
select_type
number 
optional
0: Không cho chọn, 1: Chọn một, 2: Chọn nhiều
max_choose
number 
optional
select_type = 1 thì giá trị này sẽ = 1 select_type = 2 giá trị này sẽ là tùy ý ngược lại select_type = 0 thì giá trị này sẽ = 0
products
array [object {15}] 
optional

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://retail-api.posapp.vn/api/public/product-masters' \
--header 'X-API-Key;' \
--form 'product_name="Sản phẩm 1"' \
--form 'short_name="SP1"' \
--form 'product_code=""' \
--form 'product_barcode="119821732"' \
--form 'description="Tạo mới SP1"' \
--form 'available="1"' \
--form 'product_tax="0"' \
--form 'category_name="Nước"' \
--form 'allow_overselling="true"' \
--form 'product_price="20000"' \
--form 'product_type="1"' \
--form 'automatically_create_inventory_items="true"' \
--form 'inventory_management_flg="true"' \
--form 'alert_flg="false"' \
--form 'alert_minval="0"' \
--form 'alert_maxval="0"' \
--form 'reseller_flg="true"' \
--form 'allow_online_sale="false"' \
--form 'last_input_price="0"' \
--form 'cost_price="0"' \
--form 'unit_list="{
    \"unit_name\": \"cái\",
    \"unit_exchange\": 1,
    \"is_primary\": 1,
    \"sell_flg\": 1,
    \"price\": 20000,
    \"product_barcode\": null
}"' \
--form 'unit_list="{
    \"unit_name\": \"lốc\",
    \"unit_exchange\": 1,
    \"is_primary\": 0,
    \"sell_flg\": 0,
    \"price\": 25000,
    \"product_barcode\": null
}"' \
--form 'thumbnails=""' \
--form 'feature="[
    {
        \"name\": \"Kích thước\",
        \"value\": [
            \"l\",
            \"s\",
            \"m\"
        ]
    },
    {
        \"name\": \"Màu sắc\",
        \"value\": [
            \"xanh\",
            \"đỏ\",
            \"cam\"
        ]
    }
]"' \
--form 'variants="{
    \"product_id\": \"0\",
    \"product_name\": \"s / đỏ\",
    \"product_code\": null,
    \"units\": [
        {
            \"product_barcode\": \"null\",
            \"price\": \"0\",
            \"old_price\": \"0\",
            \"cost_price\": \"0\",
            \"last_input_price\": \"0\",
            \"unit_name\": \"cái\",
            \"unit_exchange\": \"1\",
            \"is_primary\": \"true\"
        }
    ],
    \"last_input_price\": \"0\",
    \"cost_price\": \"0\"
}"' \
--form 'variants="{
    \"product_id\": \"0\",
    \"product_name\": \"m / đỏ\",
    \"product_code\": null,
    \"units\": [
        {
            \"product_barcode\": \"null\",
            \"price\": \"0\",
            \"old_price\": \"0\",
            \"cost_price\": \"0\",
            \"last_input_price\": \"0\",
            \"unit_name\": \"cái\",
            \"unit_exchange\": \"1\",
            \"is_primary\": \"true\"
        }
    ],
    \"last_input_price\": \"0\",
    \"cost_price\": \"0\"
}"' \
--form 'variants="{
    \"product_id\": \"0\",
    \"product_name\": \"l / đỏ\",
    \"product_code\": null,
    \"units\": [
        {
            \"product_barcode\": \"null\",
            \"price\": \"0\",
            \"old_price\": \"0\",
            \"cost_price\": \"0\",
            \"last_input_price\": \"0\",
            \"unit_name\": \"cái\",
            \"unit_exchange\": \"1\",
            \"is_primary\": \"true\"
        }
    ],
    \"last_input_price\": \"0\",
    \"cost_price\": \"0\"
}"' \
--form 'combo="[
    {
        \"title\": \"combo nước\",
        \"group_local_id\": \"17422693572593021570685368544\",
        \"select_type\": 1,
        \"max_choose\": 1,
        \"products\": [
            {
                \"local_id\": \"17422693869154621570685368413\",
                \"group_local_id\": \"17422693572593021570685368544\",
                \"product_master_id\": 1119256,
                \"product_id\": 1120566,
                \"name\": \"number 1\",
                \"product_type\": 1,
                \"quantity\": 1,
                \"price\": 0,
                \"unit_id\": 115691,
                \"unit_name\": \"chai\",
                \"unit_exchange\": 1,
                \"quantitative\": 1,
                \"product_master_unit\": [
                    {
                        \"id\": 1329639,
                        \"product_id\": 1120566,
                        \"product_master_id\": 1119256,
                        \"unit_id\": 115691,
                        \"unit_name\": \"chai\",
                        \"unit_exchange\": 1,
                        \"is_primary\": 1,
                        \"cost_price\": 0,
                        \"sell_flg\": 1,
                        \"product_barcode\": \"\",
                        \"available\": 1,
                        \"price\": 25000
                    }
                ],
                \"combo_price\": 25000,
                \"vat_price\": 0,
                \"hide_component\": false
            },
            {
                \"local_id\": \"17422693906354711570685368811\",
                \"group_local_id\": \"17422693572593021570685368544\",
                \"product_master_id\": 1119252,
                \"product_id\": 1120562,
                \"name\": \"Nutri\",
                \"product_type\": 1,
                \"quantity\": 1,
                \"repeat_type\": 0,
                \"price\": 0,
                \"editable_flg\": 0,
                \"unit_id\": 115691,
                \"unit_name\": \"chai\",
                \"unit_exchange\": 1,
                \"quantitative\": 1,
                \"product_master_unit\": [
                    {
                        \"id\": 1329636,
                        \"product_id\": 1120562,
                        \"product_master_id\": 1119252,
                        \"shop_id\": 1570685368,
                        \"unit_id\": 115691,
                        \"unit_name\": \"chai\",
                        \"unit_exchange\": 1,
                        \"is_primary\": 1,
                        \"cost_price\": 0,
                        \"product_material\": \"[]\",
                        \"sell_flg\": 1,
                        \"product_barcode\": \"\",
                        \"available\": 1,
                        \"old_price\": 0,
                        \"default_inventory_management_flg\": false,
                        \"price\": 25000
                    }
                ],
                \"combo_price\": 25000,
                \"vat_price\": 0,
                \"hide_component\": false
            }
        ]
    }
]"'

Responses

🟢200Success
application/json
Body
angular_build_version
string 
required
msg
string 
required
data
object 
required
Example
{
    "data": {
        "shop_id": 1570685368,
        "product_master_id": 1120411,
        "product_master_root_id": 1120411,
        "product_name": "sản phẩm test 2",
        "short_name": null,
        "product_code": "SP06005",
        "product_barcode": null,
        "description": "Tạo mới SP1",
        "available": 1,
        "product_category_id": 19908,
        "product_tax": 0,
        "product_price": 20000,
        "last_input_price": 0,
        "primary_unit_id": 115674,
        "primary_unit_name": "cái",
        "product_thumbnail1": null,
        "product_thumbnail2": null,
        "product_thumbnail3": null,
        "product_thumbnail4": null,
        "status": 1,
        "reseller_flg": 0,
        "invalid": 0,
        "feature": "",
        "products": [
            {
                "shop_id": 1570685368,
                "product_id": 1121743,
                "product_root_id": 1121743,
                "product_master_id": 1120411,
                "product_name": "sản phẩm test 2",
                "short_name": null,
                "product_code": "SP06005",
                "product_master_code": "SP06005",
                "product_price": 1000,
                "product_tax": 0,
                "product_type": 1,
                "product_barcode": null,
                "product_category_id": 19908,
                "allow_overselling": 0,
                "inventory_management_flg": 1,
                "product_manufacturing_flg": 0,
                "automatically_create_inventory_items": 0,
                "alert_flg": 0,
                "alert_maxval": null,
                "alert_minval": null,
                "unit_id": 115674,
                "unit_name": "cái",
                "reseller_flg": 0,
                "invalid": 0,
                "order_index_product": 45,
                "allow_online_sale": 0,
                "regdate": "2025-03-18 10:23:35",
                "units": [
                    {
                        "id": 1331234,
                        "shop_id": 1570685368,
                        "product_master_id": 1120411,
                        "product_id": 1121743,
                        "unit_id": 115674,
                        "unit_name": "cái",
                        "unit_exchange": 1,
                        "price": 1000,
                        "cost_price": 0,
                        "alert_flg": null,
                        "is_primary": 1,
                        "sell_flg": 1,
                        "default_inventory_management_flg": false,
                        "regdate": "2025-03-18 10:23:35",
                        "last_price": null,
                        "last_pricedate": null,
                        "product_material": null,
                        "product_barcode": null,
                        "old_price": null,
                        "available": 1
                    }
                ]
            }
        ]
    },
    "msg": "",
    "angular_build_version": "82933025dee6ad6ea4d8"
}
Modified at 2025-06-18 10:32:31
Previous
Warehouse import Schema
Next
Sửa một sản phẩm
Built with