Open API cho phép hệ thống của bạn (ERP, website, phần mềm kế toán, công cụ nội bộ) đọc và ghi dữ liệu của cửa hàng trên Pancake POS: đơn hàng, sản phẩm, tồn kho, khách hàng, phiếu nhập, phiếu xuất, khuyến mãi, báo cáo.
Địa chỉ API
Mọi endpoint nằm dưới địa chỉ:
https://pos.pages.fm/api/v1Đường dẫn trong tài liệu tính từ địa chỉ này: GET /shops/{SHOP_ID}/orders là https://pos.pages.fm/api/v1/shops/{SHOP_ID}/orders. {SHOP_ID} là mã số của cửa hàng.
Yêu cầu đầu tiên
- Tạo API key theo hướng dẫn Xác thực.
- Lấy danh sách cửa hàng mà key dùng được, kèm mã cửa hàng:
curl "https://pos.pages.fm/api/v1/shops?api_key=API_KEY"- Lấy 20 đơn hàng mới nhất của một cửa hàng:
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY&page_size=20&page_number=1"- Tạo đơn hàng: gửi JSON trong nội dung yêu cầu.
curl -X POST "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY" \
-H "Content-Type: application/json" \
-d '{"bill_full_name": "Nguyễn Văn A", "bill_phone_number": "0912345678", "items": [{"variation_id": "VARIATION_ID", "quantity": 1}]}'Các trường của từng endpoint nằm ở phần tham chiếu, ví dụ Đơn hàng.
Định dạng dữ liệu
- Gửi và nhận JSON (
Content-Type: application/json), mã hóa UTF-8. - Phản hồi có
success(truehoặcfalse); dữ liệu thường nằm trongdata. Cấu trúc cụ thể ghi ở từng endpoint. - Thời gian theo định dạng ISO 8601, giờ UTC, ví dụ
2026-01-15T03:20:00. - Số tiền là số nguyên theo đơn vị lưu của POS, phần lớn tiền tệ lưu theo 1/100 đơn vị: xem Số tiền.
- Tham số dạng mảng trong query lặp lại tên kèm
[]:filter_status[]=1&filter_status[]=2.
Số tiền
Số tiền là số nguyên theo đơn vị lưu của tiền tệ. API không quy đổi: response trả đúng số đang lưu, endpoint đơn hàng, sản phẩm, nhập hàng lưu nguyên số bạn gửi.
- Tiền tệ lưu nguyên đơn vị:
VND,TWD,LAK,PHP,MMK,JPY,INR,COP,IDR,CLP,PYG. Số tiền bằng số hiển thị trên POS. - Mọi tiền tệ khác (
USD,CAD,EUR,THB,KRW…) nhân 100. Chia 100 để ra số hiển thị trên POS; nhân 100 trước khi gửi. currencycủa cửa hàng,order_currencycủa đơn có thể làVND100,PHP100: mã nội bộ của POS (không phải ISO 4217), tiền lưu theo 1/100 đồng, peso nên cũng nhân 100. Mã ISO tương ứng làVND,PHP. Đơn gửiorder_currencyVNDvào cửa hàngVND100được lưu là đơn ngoại tệ VND.
Ví dụ: giá CAD 12.50 trả về là 1250 và phải gửi lên là 1250, không phải 12.5.
Số tiền theo tiền tệ nào:
- Tiền của đơn (sản phẩm, tổng tiền, phí, thanh toán, COD) theo
order_currencycủa đơn. Đơn tạo không truyền trường này nhận tiền tệ của cửa hàng. - Giá sản phẩm, mẫu mã, giá vốn, giá nhập, phiếu nhập và cấu hình cửa hàng theo
currencycủa cửa hàng (GET /shops). Giá vốn trong sản phẩm của đơn vàcost_surchargecũng vậy, kể cả khi đơn dùng tiền tệ khác. retail_price_by_currency[].retailPriceByCurrencytheocurrencycủa cùng phần tử.
Ví dụ cửa hàng VND có đơn USD: USD 10.00 lưu là 1000, còn giá sản phẩm vẫn là đồng nguyên.
Không nhân: phần trăm và tỉ lệ (tax_rate, discount_each_product khi is_discount_percent là true), số lượng, cân nặng. Trường tiền trong sản phẩm của hóa đơn điện tử (items[].variation_info của /list_einvoices) trả theo số hiển thị.
Phân trang
Endpoint trả danh sách nhận page_size cùng page_number hoặc page (xem tham số của từng endpoint) và trả về:
| Trường | Ý nghĩa |
|---|---|
data |
Danh sách bản ghi của trang |
page_number |
Trang hiện tại, bắt đầu từ 1 |
page_size |
Số bản ghi mỗi trang |
total_entries |
Tổng số bản ghi |
total_pages |
Tổng số trang |
Đọc hết danh sách bằng cách tăng page_number tới total_pages. Khi đồng bộ định kỳ, chỉ đọc phần thay đổi thay vì đọc lại toàn bộ. Với đơn hàng: updateStatus=updated_at cùng startDateTime, endDateTime (unix timestamp).
Cách đọc phần tham chiếu
- Endpoint được nhóm theo nghiệp vụ ở thanh bên: Cửa hàng, Bán hàng, Sản phẩm & kho, Khách hàng & khuyến mãi, Tài chính, Báo cáo & quảng cáo.
- Mỗi endpoint có tham số, nội dung yêu cầu, phản hồi theo mã HTTP và ví dụ
curl. Bấm vào thuộc tính có dấu mở rộng để xem thuộc tính con. - Đối tượng dùng chung (đơn hàng, sản phẩm, payload webhook…) nằm ở Mô hình dữ liệu.
- Mỗi trang có bản Markdown; llms.txt giúp công cụ AI đọc đúng tài liệu.
