Tài liệu tích hợp DLV Gen Z (Full 19 Endpoints)

Toàn bộ tài liệu kỹ thuật để kết nối hệ thống bên ngoài vào DLV Core.

Hệ thống sẵn sàng: API v2.0 hoạt động ổn định.

Xác thực (Authentication)

Gửi kèm API Key trong Header để định danh.

Header
x-api-key: "dlv_doanhnghiep_..."

GET /api/sync/products

1. Lấy danh sách Sản phẩm

Trả về sản phẩm kèm số lượng tồn kho thực tế.

[ { "name": "Cafe Sữa", "stock_qty": 50 } ]

POST /api/sync/orders

2. Tạo Đơn hàng mới

Đẩy đơn hàng từ Web/App về hệ thống POS.

                        {
                        "customer": { "name": "A Long", "phone": "098..." },
                        "items": [ { "sku": "SP1", "qty": 2 } ],
                        "total": 100000
                        }
                    

GET /api/sync/customers

3. Lấy Danh sách Khách

Lấy 100 khách mới nhất hoặc tìm theo SĐT.

[ { "name": "Anh Dương ĐZ", "phone": "0356062274", "loyaltyPoints": 150 } ]

POST /api/sync/customers

4. Thêm/Sửa Khách hàng

Đồng bộ Lead từ Landing Page về CRM.

{ "name": "Dương Lê", "phone": "0356062274", "address": "Hà Nội", "source": "Tiktok" }

GET /api/sync/report-daily

5. Báo cáo Nhanh

Tổng doanh thu, số đơn và 5 đơn mới nhất trong ngày.

{ "summary": { "revenue": 5000000, "orders": 25 }, "recent_sales": [...] }

PUT /api/sync/orders/:id/status

6. Cập nhật Trạng thái Đơn

Shipper cập nhật trạng thái: shipping, completed, cancelled.

{ "status": "shipping", "note": "Shipper đã nhận hàng" }

POST /api/sync/inventory/adjustment

7. Điều chỉnh Tồn kho nhanh

Cộng/Trừ tồn kho từ xa.

{ "sku": "SP1", "qty": -5, "reason": "Vỡ hàng" }

GET /api/sync/orders/search

8. Tra cứu Đơn hàng

Tìm theo ID đơn hoặc SĐT khách. Query: ?keyword=...

GET /api/sync/stats/revenue-chart

9. Biểu đồ Doanh thu (7 ngày)

Dữ liệu để vẽ biểu đồ cột/đường doanh thu tuần qua.

GET /api/sync/store-info

10. Thông tin Cửa hàng

Lấy Logo, Tên shop, Địa chỉ, SĐT để hiển thị lên Web vệ tinh.

{ "name": "Cafe GenZ", "address": "Từ Sơn, Bắc Ninh", "phone": "098...", "logoUrl": "https://..." }

POST /api/sync/notify

11. Gửi Thông báo

Gửi Notify đến máy POS. VD: "Bàn 5 gọi thanh toán".

{ "title": "GỌI LOA", "content": "Alo 1234" }

POST /api/sync/vouchers/check

12. Kiểm tra Voucher

Kiểm tra mã giảm giá có hợp lệ không trước khi thanh toán.

{ "code": "GIAM50K", "customerPhone": "098..." }

POST /api/sync/feedback

13. Gửi Đánh giá (Feedback)

Khách hàng đánh giá sao sau khi mua. Nếu <= 3 sao sẽ báo động Admin.

{ "saleId": "...", "rating": 5, "comment": "Ngon!" }

GET /api/sync/staff/working

14. Nhân viên đang làm việc

Xem ai đang check-in tại cửa hàng.

GET /api/sync/stats/top-products

15. Top món Bán chạy

Dùng để hiển thị mục "Best Sellers" trên Website hoặc Menu điện tử.

Query: ?days=7
[ { "name": "Trà Đào", "totalSold": 120 } ]

GET /api/sync/categories

16. Lấy Danh mục Menu

Lấy danh sách nhóm món ăn kèm hình ảnh đại diện và số lượng món.

[ { "name": "Đồ uống", "productCount": 15, "image": "url_hinh_anh..." } ]

POST /api/sync/bookings

17. Đặt Bàn (Booking)

Khách đặt bàn từ xa. Hệ thống sẽ báo "Ting Ting" cho nhân viên.

{ "name": "Anh Tùng", "phone": "098...", "date": "2025-12-31", "time": "19:00", "people": 4, "note": "Ngồi view đẹp" }

GET /api/sync/kitchen/queue

18. Màn hình Bếp (KDS)

Lấy danh sách các món cần chế biến, sắp xếp theo thời gian order.

GET /api/sync/tables/status

19. Sơ đồ Bàn (Real-time)

Biết bàn nào đang có khách, bàn nào trống.

[ { "name": "Bàn 1", "isBusy": true, "currentTotal": 250000 }, { "name": "Bàn 2", "isBusy": false } ]