Giới thiệu

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

1. Tạo API key theo hướng dẫn Xác thực.
2. 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"

3. 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"

4. 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 (true hoặc false); dữ liệu thường nằm trong data. 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.
• Tham số dạng mảng trong query lặp lại tên kèm []: filter_status[]=1&filter_status[]=2.

#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ề:

Đọ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.

#Liên quan

• POS Apps gọi cùng Open API này ngay trong POS, bằng app token do POS cấp thay cho API key.
• MCP để Claude, Codex, Cursor dùng Open API qua câu lệnh thường ngày.