NgothanhloiPOS API

GET /customer-cats

Lấy danh sách nhóm khách hàng. Quyền: customer.category.view_list

Fields

Field	Type	Description	Required
name			NO
is_default			NO
action			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "categories": [
            {
                "id",
                "name",
                "is_default"
            },
            ...
        ]
    }
}

POST /customer-cats

Tạo nhóm khách hàng mới. Quyền: customer.category.create

Fields

Field	Type	Description	Required
name			NO
is_default			NO
action			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "name" //Tên nhóm. Required
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- ERROR: Lỗi lưu trữ

PUT /customer-cats[/:cat_id]

Chỉnh sửa thông tin nhóm khách hàng. - Sửa tên nhóm. Quyền: customer.category.edit_name - Sửa trạng thái mặc định. Quyền: customer.category.edit_is_default

Fields

Field	Type	Description	Required
name			NO
is_default			NO
action			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "action": "editName | editIsDefault",
   "name", //Với action editName. Required
   "is_default": "Y|N" //Với action editIsDefault. Required
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- NOT_FOUND_CATEGORY: Không tìm thấy nhóm KH.
- CANNOT_UNSET_DEFAULT_CATEGORY: Không thể bỏ trạng thái mặc định.
- ERROR: Lỗi khác.

DELETE /customer-cats[/:cat_id]

Xóa nhóm khách hàng. Quyền: customer.category.delete

Fields

Field	Type	Description	Required
name			NO
is_default			NO
action			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Customers

Quản lý tài khoản khách hàng

GET /customers

Lấy danh sách khách hàng. Quyền: customer.view_list

- Để lấy theo mã vạch, truyền param: card=[param]; - Để lọc theo mã KH, tên KH, SDT, truyền các param: taxid=[taxid]&name=[name]&phone=[phone] - Truyền param visible=Y để lọc KH visible - Order: loyal_score, curdebt, curdate 2. Lấy lich sử điểm tích lũy khách hàng: truyền param view_score_history=Y&customer_id=[customer_id]. Quyền: customer.edit_score 3. Lấy danh sách khách hàng cho các chức năng khác: truyền param other_role_view=[role]. Truyền thêm param search_customer để lọc theo tên, mã, sdt khách hàng

Fields

Field	Description	Required
action		NO
name		NO
taxid		NO
searchkey		NO
card		NO
category		NO
loyal_category		NO
visible		NO
transaction_type		NO
ticketid		NO
score	Giá trị âm: số điểm cần thanh toán. Giá trị dương: Số điểm tích lũy thêm.	NO
score_content		NO
maxdebt		NO
phone		NO
region	Tỉnh/Thành Phố	NO
city	Quận\Huyện	NO
address	Địa chỉ	NO
notes		NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

1. Danh sách customer
{
   "_embedded": {
       "customers": [
           {
               "id", //Id KH
               "taxid", // Mã KH
               "name", // Tên KH
               "category_name", // Tên nhóm KH
               "loyal_cat_name", // Tên nhóm KHTT
               "loyal_score", // điểm KHTT
               "curdebt", // Nợ hiện tại
               "curdate", // Ngày nợ
               "address", //Địa chỉ
               "city", // Huyện
               "region", // Tỉnh
               "visible": "Y|N"
           },
           ...
       ]
   }
}
2. Lich sử điểm:
"_embedded": {
        "customers": [
            {
                "id",
                "admin_name", //Người thực hiện
                "score_transaction", //Điểm giao dịch
                "content", //Nội dung
                "date", //Thời gian
            },
            ...
        ]
}
3. Danh sách khách hàng cho chức năng khác (`other_role_view`):
{
    "_embedded": {
        "customers": [
            {
                "id",
                "taxid",
                "name",
                "phone" // Sẽ bị ẩn nếu không có quyền `customer.view_phone`
            }
        ]
    }
}

POST /customers

Tạo tài khoản khách hàng

Fields

Field	Description	Required
action		NO
name		NO
taxid		NO
searchkey		NO
card		NO
category		NO
loyal_category		NO
visible		NO
transaction_type		NO
ticketid		NO
score	Giá trị âm: số điểm cần thanh toán. Giá trị dương: Số điểm tích lũy thêm.	NO
score_content		NO
maxdebt		NO
phone		NO
region	Tỉnh/Thành Phố	NO
city	Quận\Huyện	NO
address	Địa chỉ	NO
notes		NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json

Body

{

   "name", //required
   "phone", //required
   "region", //Tỉnh/Thành Phố
   "city", //Quận/Huyện
   "address": //Địa chỉ
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//result SUCCESS
{
    "result": "SUCCESS",
    "customer": {
        "id",
        "searchkey",
        "taxid",
        "name",
        "taxcategory",
        "taxcustloyalcategory",
        "address",
        "city",
        "region",
        "phone"
    }
}

//Các lỗi xảy ra:
- EXIST_PHONE: SDT đã tồn tại
- ERROR: Lỗi khác

GET /customers[/:customer_id]

Lấy thông tin chi tiết của khách hàng. Quyền: customer.view_detail

Fields

Field	Description	Required
action		NO
name		NO
taxid		NO
searchkey		NO
card		NO
category		NO
loyal_category		NO
visible		NO
transaction_type		NO
ticketid		NO
score	Giá trị âm: số điểm cần thanh toán. Giá trị dương: Số điểm tích lũy thêm.	NO
score_content		NO
maxdebt		NO
phone		NO
region	Tỉnh/Thành Phố	NO
city	Quận\Huyện	NO
address	Địa chỉ	NO
notes		NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "result": "SUCCESS",
    "customer": {
        "id",
        "searchkey", // Từ khóa
        "taxid", // Mã số thuế
        "name",
        "card", // Mã thẻ
        "category_id", // Id nhóm KH
        "category_name", // Tên nhóm KH
        "loyal_cat_id", // Id nhóm KHTT
        "loyal_cat_name", // Tên nhóm KHTT
        "loyal_score", // Điểm KHTT
        "maxdebt", // Nợ tối đa
        "curdebt", // Nợ hiện tại
        "curdate", // Ngày GD nợ gần nhất
        "address", // Địa chỉ
        "city", // Quận/Huyện
        "region", // Tỉnh/Thành Phố
        "visible": "Y|N", // HIển thị
        "phone", // SDT, sẽ là "**********" nếu không có quyền `customer.view_phone`
        "notes"
    }
}
Lỗi có thể xảy ra: NOT_FOUND_CUSTOMER

PUT /customers[/:customer_id]

Chỉnh sửa các thông tin khách hàng theo action: - editName: Sửa tên. Quyền: customer.edit_name - editCode: Sửa mã KH, mã thẻ. Quyền: customer.edit_code - editCategory: Sửa nhóm KH. Quyền: customer.edit_category - editLoyalCategory: Sửa nhóm KHTT. Quyền: customer.edit_loyal_category - editVisible: Sửa trạng thái hiển thị. Quyền: customer.edit_visible - editScore: Cập nhật điểm tích lũy. Quyền: customer.edit_score - editMaxDebt: Sửa nợ tối đa. Quyền: customer.edit_max_debt - editPhone: Sửa SĐT. Quyền: customer.edit_phone - editAddress: Sửa địa chỉ. Quyền: customer.edit_address - editNotes: Sửa ghi chú. Quyền: customer.edit_notes

Fields

Field	Description	Required
action		NO
name		NO
taxid		NO
searchkey		NO
card		NO
category		NO
loyal_category		NO
visible		NO
transaction_type		NO
ticketid		NO
score	Giá trị âm: số điểm cần thanh toán. Giá trị dương: Số điểm tích lũy thêm.	NO
score_content		NO
maxdebt		NO
phone		NO
region	Tỉnh/Thành Phố	NO
city	Quận\Huyện	NO
address	Địa chỉ	NO
notes		NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "action": "editName | editCode | editCategory | editLoyalCategory | editVisible | editScore | editMaxDebt | editPhone | editAddress | editNotes",
   "name", // Với action `editName`. Required.
   "taxid", // Với action `editCode`. Required.
   "searchkey", // Với action `editCode`. Required.
   "card", // Với action `editCode`. Optional.
   "category", //Với action `editCategory`. Optional.
   "loyal_category", //Với action `editLoyalCategory`. Optional.
   "visible": "Y|N", // Với action `editVisible`. Required.
   "transaction_type": "accumulate | exchange", //Với action `editScore`. Required.
   "ticketid", //id hóa đơn. Với action `editScore`. Required.
   "score", // Với action `editScore`. Required.
   "score_content", // Với action `editScore`. Required.
   "maxdebt", // Với action `editMaxDebt`. Required.
   "phone", // Với action `editPhone`. Required.
   "region", // Với action `editAddress`. Optional.
   "city", // Với action `editAddress`. Optional.
   "address", // Với action `editAddress`. Optional.
   "notes" // Với action `editNotes`. Optional.
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- NOT_FOUND_CUSTOMER: Không tìm thấy customer
- ERROR: Lỗi khác
- NOT_ENOUGH_SCORE: ĐTL hiện tại không đủ thanh toán. (action `editScore`)
- NOT_FOUND_TICKET: Không tìm thấy ticket. (action `editScore`)
- EXIST_PHONE: SDT đã tồn tại ở tài khoản KH khác. (action `editPhone`)

DELETE /customers[/:customer_id]

Xóa tài khoản khách hàng. Quyền: customer.delete

Fields

Field	Description	Required
action		NO
name		NO
taxid		NO
searchkey		NO
card		NO
category		NO
loyal_category		NO
visible		NO
transaction_type		NO
ticketid		NO
score	Giá trị âm: số điểm cần thanh toán. Giá trị dương: Số điểm tích lũy thêm.	NO
score_content		NO
maxdebt		NO
phone		NO
region	Tỉnh/Thành Phố	NO
city	Quận\Huyện	NO
address	Địa chỉ	NO
notes		NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

LoyalCategories

GET /customer-loyal-cats[/:cat_id]

Lấy danh sách nhóm KHTT

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "categories": [
            {
                "id",
                "name",
            },
            ...
        ]
    }
}

WarrantyInfo

Quản lý thông tin bảo hành sản phẩm.

GET /warranty-info

Lấy danh sách hoặc các thông tin liên quan đến bảo hành. Quyền: customer.warranty_info.view_list. API hỗ trợ nhiều chế độ xem khác nhau thông qua tham số other_view:

Lấy danh sách thông tin bảo hành (Mặc định):
- Cách dùng: Không cần truyền other_view.
- Lọc dữ liệu:
  - search_product: Tìm theo tên, mã, model, hoặc số serial của sản phẩm.
  - search_customer: Tìm theo tên hoặc mã của khách hàng.
  - search_ticket: Tìm theo ID hóa đơn.
  - is_active: Lọc theo trạng thái còn bảo hành (Y hoặc N).
- Sắp xếp:
  - order: Tên cột để sắp xếp (product_name, cust_name, ticketid, active_date, expired_date, person_name, created_at).
  - dir: Hướng sắp xếp (asc hoặc desc).
Lấy lịch sử thay đổi (history):
- Cách dùng: Truyền other_view=history.
- Tham số bắt buộc: warranty_id (UUID của thông tin bảo hành).
Lấy danh sách khách hàng (customer):
- Cách dùng: Truyền other_view=customer.
- Lọc dữ liệu: search_customer (tìm theo mã thẻ, mã KH, tên, hoặc SĐT).
Lấy thông tin hóa đơn (ticket):
- Cách dùng: Truyền other_view=ticket.
- Tham số bắt buộc: ticket_id (ID của hóa đơn).

Fields

Field	Type	Description	Required
ticketid			NO
cust_id			NO
cust_phone			NO
product_id			NO
image			NO
model			NO
serial_num			NO
private_code			NO
time_warranty			NO
active_date			NO
expired_date			NO
note			NO
action			NO
status			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

1. Danh sách thông tin bảo hành:
{
    "_embedded": {
        "warranty_info": [
            {
                "id": "uuid",
                "product_id",
                "product_name",
                "model",
                "serial_num",
                "private_code",
                "image": "URL ảnh",
                "cust_id",
                "cust_name",
                "cust_phone",
                "ticketid",
                "time_warranty",
                "active_date",
                "expired_date",
                "status": "Y|N", // Còn bảo hành hay không
                "note",
                "person_id",
                "person_name", // Người tạo
                "created_at"
            },
            ...
        ]
    }
}

2. Lịch sử thay đổi (`other_view=history`):
{
    "_embedded": {
        "warranty_info": [
            {
                "id": "uuid của lịch sử",
                "person_name": "Tên người thực hiện",
                "date": "Thời gian thay đổi",
                "log": "Nội dung thay đổi"
            }
        ]
    }
}

3. Danh sách khách hàng (`other_view=customer`):
{
    "_embedded": {
        "customers": [
            {
                "id",
                "taxid",
                "name",
                "phone"
            },
            ...
        ]
    }
}

4. Thông tin hóa đơn (`other_view=ticket`):
{
    "ticket": {
        "ticket_uuid",
        "ticket_id",
        "customer_id",
        "lines": [
            { "product_id", "product_name" },
            ...
        ]
    }
}

POST /warranty-info

Tạo một thông tin bảo hành mới. Quyền: customer.warranty_info.create

Fields

Field	Type	Description	Required
ticketid			NO
cust_id			NO
cust_phone			NO
product_id			NO
image			NO
model			NO
serial_num			NO
private_code			NO
time_warranty			NO
active_date			NO
expired_date			NO
note			NO
action			NO
status			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
    "ticketid": "string",       // Required. ID hóa đơn.
    "cust_id": "string",        // Required. ID khách hàng.
    "cust_phone": "string",     // Required. SĐT khách hàng.
    "product_id": "string",     // Required. ID sản phẩm.
    "image": "string",          // Optional. Ảnh sản phẩm (base64).
    "model": "string",          // Optional. Model sản phẩm.
    "serial_num": "string",     // Optional. Số serial.
    "private_code": "string",   // Optional. Mã an ninh.
    "time_warranty": "int",     // Optional. Thời gian bảo hành (tháng).
    "active_date": "Y-m-d",     // Optional. Ngày kích hoạt.
    "expired_date": "Y-m-d",    // Optional. Ngày hết hạn.
    "note": "string"            // Optional. Ghi chú.
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- 403 Forbidden: Không có quyền.
- 422 Unprocessable Entity: Thiếu các trường bắt buộc.
- TICKET_PRODUCT_NOT_FOUND: Không tìm thấy sản phẩm tương ứng trong hóa đơn.
- SERIAL_NUMBER_EXISTS: Số serial đã được đăng ký cho một sản phẩm khác.
- CUSTOMER_NOT_FOUND: Không tìm thấy thông tin khách hàng.
- ERROR_CUSTOMER_PHONE: Số điện thoại khách hàng không hợp lệ hoặc không có.
- ERROR_UPLOAD_IMAGE: Lỗi trong quá trình tải ảnh lên.
- ERROR: Lỗi hệ thống chung.

PUT /warranty-info[/:warranty_id]

Cập nhật thông tin bảo hành. Hành động được xác định bởi tham số action.

editProduct: Sửa thông tin sản phẩm.
- Quyền: customer.warranty_info.edit_product.
editCustomer: Sửa thông tin khách hàng.
- Quyền: customer.warranty_info.edit_customer.
editStatus: Sửa trạng thái và thời hạn bảo hành.
- Quyền: customer.warranty_info.edit_status.
editNote: Sửa ghi chú.
- Quyền: customer.warranty_info.edit_note.

Fields

Field	Type	Description	Required
ticketid			NO
cust_id			NO
cust_phone			NO
product_id			NO
image			NO
model			NO
serial_num			NO
private_code			NO
time_warranty			NO
active_date			NO
expired_date			NO
note			NO
action			NO
status			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
    "action": "editProduct | editCustomer | editStatus | editNote",
    // --- Dữ liệu cho action="editProduct" ---
    "ticketid": "string", // Required
    "product_id": "string", // Required
    "model": "string", // Optional
    "serial_num": "string", // Optional
    "private_code": "string", // Optional
    "image": "base64", // Optional

    // --- Dữ liệu cho action="editCustomer" ---
    "cust_id": "string", // Required
    "cust_phone": "string", // Required

    // --- Dữ liệu cho action="editStatus" ---
    "status": "Y|N", // Required
    "time_warranty": "int", // Optional
    "active_date": "Y-m-d", // Optional
    "expired_date": "Y-m-d", // Optional

    // --- Dữ liệu cho action="editNote" ---
    "note": "string" // Optional
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- 403 Forbidden: Không có quyền.
- 422 Unprocessable Entity: Thiếu các trường bắt buộc cho action.
- WARRANTY_INFO_NOT_FOUND: Không tìm thấy thông tin bảo hành.
- TICKET_PRODUCT_NOT_FOUND: Không tìm thấy sản phẩm trong hóa đơn (khi `action="editProduct"`).
- SERIAL_NUMBER_EXISTS: Số serial đã tồn tại (khi `action="editProduct"`).
- CUSTOMER_NOT_FOUND: Không tìm thấy khách hàng (khi `action="editCustomer"`).
- ERROR_CUSTOMER_PHONE: Số điện thoại khách hàng không hợp lệ hoặc không có.
- ERROR_DELETE_IMAGE, ERROR_UPLOAD_IMAGE, ERROR_UPDATE_IMAGE: Lỗi khi xử lý ảnh.
- ERROR: Lỗi hệ thống chung.

DELETE /warranty-info[/:warranty_id]

Xóa một thông tin bảo hành. Quyền: customer.warranty_info.delete

Fields

Field	Type	Description	Required
ticketid			NO
cust_id			NO
cust_phone			NO
product_id			NO
image			NO
model			NO
serial_num			NO
private_code			NO
time_warranty			NO
active_date			NO
expired_date			NO
note			NO
action			NO
status			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

WarrantyStatus

Quản lý phiếu bảo hành.

GET /warranty-status

Lấy danh sách phiếu bảo hành. Quyền: customer.warranty_status.view_list

Các tham số lọc:
- product_name: Tên sản phẩm.
- product_reference: Mã sản phẩm.
- customer_name: Tên khách hàng.
- customer_phone: SĐT khách hàng.
- cust_received_date: Ngày nhận từ KH.
- cust_return_date: Ngày trả KH.
- receiver: Người xử lý.
- location: ID kho.
- supplier_name: Tên NCC.
- supplier_send_date: Ngày gửi NCC.
- supplier_return_date: Ngày nhận từ NCC.
- warranty_type: Loại bảo hành.
- status: Trạng thái (pending, send, receive, success).
- start_date, end_date: Lọc theo ngày tạo.
- order: Sắp xếp (product_name, customer_name, cust_received_date, cust_return_date, supplier_name, supplier_send_date, supplier_return_date, location_name).
- dir: asc/desc.

Lấy các thông tin khác (other_view)

- other_view=history: Lấy lịch sử phiếu bảo hành. Cần warranty_id=[UUID].
- other_view=location: Lấy danh sách kho hàng.
- other_view=customer: Lấy danh sách khách hàng. Có thể lọc theo search_customer.
- other_view=product: Lấy danh sách sản phẩm. Có thể lọc theo search_product.
- other_view=supplier: Lấy danh sách nhà cung cấp. Có thể lọc theo search_supplier

Fields

Field	Type	Description	Required
products			NO
receiver			NO
location			NO
warranty_type			NO
customer_name			NO
customer_phone			NO
customer_address			NO
action			NO
product_name			NO
product_qty			NO
product_status			NO
product_img			NO
supplier_name			NO
note			NO
cust_received_date			NO
supplier_send_date			NO
status			NO
repair_cost			NO
warranty_expenses			NO
progress_note_text			NO
progress_note_img			NO
other_cost			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

1. Danh sách phiếu bảo hành:
{
    "_embedded": {
        "warranty_status": [
            {
                "id", // uuid
                "reference",
                "product_name",
                "product_status",
                "product_qty",
                "product_img", // Array URL
                "customer_name",
                "customer_phone",
                "customer_address",
                "person_name", // Người tạo
                "receiver", // Người xử lý
                "location_id", // ID kho
                "location_name", // Tên kho
                "cust_received_date", // Ngày nhận từ khách hàng
                "cust_return_date", // Ngày trả khách hàng
                "repair_cost", // Chi phí sửa chữa
                "other_cost", // Số hóa đơn thu tiền
                "supplier_name", // Tên NCC
                "supplier_send_date", // Ngày gửi NCC
                "supplier_return_date", // Ngày nhận từ NCC
                "warranty_expenses", // Chi phí bảo hành
                "warranty_type", // Loại bảo hành
                "note", // Ghi chú
                "failure_reason", // Nội dung đánh dấu phiếu
                "status", // Trạng thái
                "created_at" // Ngày tạo
            },
            ...
        ]
    }
}

2. Lịch sử:
{
    "_embedded": {
        "warranty_status": [
            {
                "id",
                "person_name",
                "date",
                "log"
            }
        ]
    }
}

3. Danh sách kho hàng (`other_view=location`):
{
    "_embedded": {
        "locations": [
            {
                "id",
                "name"
            }
        ]
    }
}

4. Danh sách khách hàng (`other_view=customer`):
{
    "_embedded": {
        "customers": [
            {
                "id",
                "taxid",
                "name",
                "phone"
            }
        ]
    }
}

5. Danh sách sản phẩm (`other_view=product`):
{
    "_embedded": {
        "products": [
            { "id", "name", "reference" }
        ]
    }
}

6. Danh sách nhà cung cấp (`other_view=supplier`):
{
    "_embedded": {
        "suppliers": [ { "id", "name" } ]
    }
}

POST /warranty-status

Tạo phiếu bảo hành mới. Quyền: customer.warranty_status.create

Fields

Field	Type	Description	Required
products			NO
receiver			NO
location			NO
warranty_type			NO
customer_name			NO
customer_phone			NO
customer_address			NO
action			NO
product_name			NO
product_qty			NO
product_status			NO
product_img			NO
supplier_name			NO
note			NO
cust_received_date			NO
supplier_send_date			NO
status			NO
repair_cost			NO
warranty_expenses			NO
progress_note_text			NO
progress_note_img			NO
other_cost			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
    "products": [ // Required. Danh sách sản phẩm bảo hành (JSON string)
        {
            "product_name": "string", // Required. Tên sản phẩm 
            "product_qty": "int", // Required. Số lượng sản phẩm
            "product_status": "string", // Required. Tình trạng sản phẩm
            "product_img": "string", // Optional. JSON string chứa mảng base64 ảnh
            "supplier_name": "string", // Optional. Tên NCC
            "note": "string" // Optional. Ghi chú
        }
    ],
    "receiver": "string", // Required. Người xử lý
    "location": "string", // Required. ID kho hàng
    "warranty_type": "string", // Optional. Loại bảo hành: `customer` || `company`
    "customer_name": "string", // Optional. Tên khách hàng
    "customer_phone": "string", // Optional. SĐT khách hàng
    "customer_address": "string" // Optional. Địa chỉ khách hàng
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- 403 Forbidden: Không có quyền.
- 422 Unprocessable Entity: Thiếu trường bắt buộc (products, product_name, product_qty, product_status).
- ERROR_UPLOAD_IMAGE: Lỗi upload ảnh.
- ERROR: Lỗi hệ thống.

PUT /warranty-status[/:warranty_id]

Cập nhật thông tin phiếu bảo hành theo action.

editProduct: Sửa thông tin sản phẩm. Quyền: customer.warranty_status.edit_product.
- Params: product_name (req), product_qty (req), product_status, product_img (JSON string base64), supplier_name, note.
editCustomer: Sửa thông tin khách hàng. Quyền: customer.warranty_status.edit_customer.
- Params: customer_name (req), customer_phone (optional), customer_address (optional).
editReceiveDate: Sửa ngày nhận. Quyền: customer.warranty_status.edit_receive_date.
- Params: cust_received_date (req).
editSupplier: Sửa NCC. Quyền: customer.warranty_status.edit_supplier.
- Params: supplier_name (req).
editSendDate: Sửa ngày gửi NCC. Quyền: customer.warranty_status.edit_send_date.
- Params: supplier_send_date (req).
editStatus: Chuyển trạng thái (không thể chuyển về pending). Quyền: customer.warranty_status.edit_status.
- Params: status (req: send, receive, success).
editCost: Sửa chi phí. Quyền: customer.warranty_status.edit_cost.
- Params: repair_cost (optional), warranty_expenses (optional).
addProgressNote: Thêm ghi chú tiến độ. Quyền: customer.warranty_status.add_progress_note.
- Params: progress_note_text (optional), progress_note_img (optional).
forwardWarranty: Chuyển tiếp bảo hành. Quyền: customer.warranty_status.forward_warranty.
- Params: receiver (req), location (req).
sendToSupplier: Gửi đi NCC. Quyền: customer.warranty_status.send_to_supplier.
- Params: supplier_name (req).
receivedFromSupplier: Nhận từ NCC. Quyền: customer.warranty_status.received_from_supplier.
- Params: location (req), warranty_expenses (optional), repair_cost (optional).
completeWarranty: Hoàn tất bảo hành. Quyền: customer.warranty_status.complete_warranty.
- Params: other_cost (optional).
editOtherCost: Sửa số hóa đơn. Quyền: customer.warranty_status.edit_other_cost.
- Params: other_cost (optional).

Fields

Field	Type	Description	Required
products			NO
receiver			NO
location			NO
warranty_type			NO
customer_name			NO
customer_phone			NO
customer_address			NO
action			NO
product_name			NO
product_qty			NO
product_status			NO
product_img			NO
supplier_name			NO
note			NO
cust_received_date			NO
supplier_send_date			NO
status			NO
repair_cost			NO
warranty_expenses			NO
progress_note_text			NO
progress_note_img			NO
other_cost			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Content-Type	application/vnd.customers.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

// 1. editProduct - Sửa thông tin sản phẩm
{
    "action": "editProduct",
    "product_name": "string", // Required. Tên sản phẩm
    "product_qty": "int", // Required. Số lượng
    "product_status": "string", // Optional. Tình trạng sản phẩm
    "product_img": "string", // Optional. JSON string chứa mảng base64 images
    "note": "string" // Optional. Ghi chú
}

// 2. editCustomer - Sửa thông tin khách hàng
{
    "action": "editCustomer",
    "customer_name": "string", // Required. Tên khách hàng
    "customer_phone": "string", // Optional. SĐT khách hàng
    "customer_address": "string" // Optional. Địa chỉ khách hàng
}

// 3. editReceiveDate - Sửa ngày nhận từ khách hàng
{
    "action": "editReceiveDate",
    "cust_received_date": "Y-m-d H:i:s" // Required. Ngày nhận
}

// 4. editSupplier - Sửa thông tin nhà cung cấp
{
    "action": "editSupplier",
    "supplier_name": "string" // Required. Tên NCC
}

// 5. editSendDate - Sửa ngày gửi NCC
{
    "action": "editSendDate",
    "supplier_send_date": "Y-m-d H:i:s" // Required. Ngày gửi
}

// 6. editStatus - Chuyển trạng thái phiếu
{
    "action": "editStatus",
    "status": "pending | send | receive | success" // Required. Trạng thái mới
}

// 7. editCost - Sửa chi phí
{
    "action": "editCost",
    "repair_cost": "float", // Optional. Chi phí sửa chữa
    "warranty_expenses": "float" // Optional. Chi phí bảo hành
}

// 8. addProgressNote - Thêm ghi chú tiến độ
{
    "action": "addProgressNote",
    "progress_note_text": "string", // Optional. Nội dung ghi chú
    "progress_note_img": "string" // Optional. Base64 image
}

// 9. forwardWarranty - Chuyển tiếp bảo hành
{
    "action": "forwardWarranty",
    "receiver": "string", // Required. Người nhận xử lý
    "location": "int" // Required. ID kho
}

// 10. sendToSupplier - Gửi sản phẩm đi NCC
{
    "action": "sendToSupplier",
    "supplier_name": "string" // Required. Tên NCC
}

// 11. receivedFromSupplier - Nhận sản phẩm từ NCC
{
    "action": "receivedFromSupplier",
    "location": "int", // Required. ID kho nhận
    "warranty_expenses": "float", // Optional. Chi phí bảo hành
    "repair_cost": "float" // Optional. Chi phí sửa chữa
}

// 12. completeWarranty - Hoàn tất bảo hành, trả khách
{
    "action": "completeWarranty",
    "other_cost": "string" // Optional. Số hóa đơn thu tiền (nếu có)
}

// 13. editOtherCost - Sửa số hóa đơn
{
    "action": "editOtherCost",
    "other_cost": "string" // Required. Số hóa đơn thu tiền
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//SUCCESS
{"result":"SUCCESS"}

//ERROR
- 403 Forbidden
- 422 Unprocessable Entity
- WARRANTY_STATUS_NOT_FOUND: Không tìm thấy phiếu bảo hành.
- WARRANTY_ALREADY_COMPLETED: Không thể thao tác khi phiếu đã hoàn thành.
- WARRANTY_NOT_COMPLETED: Không thể sửa số hóa đơn khi phiếu chưa hoàn thành (chỉ cho action `editOtherCost`).
- INVALID_STATUS_TRANSITION: Chuyển trạng thái không hợp lệ.
- SEND_DATE_UPDATE_NOT_ALLOWED: Không được sửa ngày gửi khi trạng thái là `pending` hoặc `send`.
- WARRANTY_ALREADY_SENT: Không thể thao tác khi phiếu đã được gửi cho NCC.
- WARRANTY_NOT_SENT: Không thể thao tác khi phiếu chưa được gửi cho NCC.
- WARRANTY_ALREADY_RECEIVED: Không thể thao tác khi phiếu đã được nhận từ NCC.
- WARRANTY_NOT_RECEIVED: Không thể thao tác khi phiếu chưa được nhận từ NCC.
- LOCATION_NOT_FOUND: Không tìm thấy kho.
- ERROR

DELETE /warranty-status[/:warranty_id]

Xóa phiếu bảo hành. Chỉ có thể xóa khi trạng thái là pending. Quyền: customer.warranty_status.delete

Fields

Field	Type	Description	Required
products			NO
receiver			NO
location			NO
warranty_type			NO
customer_name			NO
customer_phone			NO
customer_address			NO
action			NO
product_name			NO
product_qty			NO
product_status			NO
product_img			NO
supplier_name			NO
note			NO
cust_received_date			NO
supplier_send_date			NO
status			NO
repair_cost			NO
warranty_expenses			NO
progress_note_text			NO
progress_note_img			NO
other_cost			NO

Request

Headers

Header	Value
Accept	application/vnd.customers.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.customers.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Documentation

Customers (v1)

Categories

GET /customer-cats

Fields

Request

Headers

Response

Status Codes

Headers

Body

POST /customer-cats

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

PUT /customer-cats[/:cat_id]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

DELETE /customer-cats[/:cat_id]

Fields

Request

Headers

Response

Status Codes

Headers

Customers

GET /customers

Fields

Request

Headers

Response

Status Codes

Headers

Body

POST /customers

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

GET /customers[/:customer_id]

Fields

Request

Headers

Response

Status Codes

Headers

Body

PUT /customers[/:customer_id]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

DELETE /customers[/:customer_id]

Fields

Request

Headers

Response

Status Codes

Headers

LoyalCategories

GET /customer-loyal-cats[/:cat_id]