Bắt đầu

Giới thiệu

Địa chỉ API, định dạng dữ liệu, phân trang và yêu cầu đầu tiên.

Xem Markdown

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ỉ:

Text
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:
Terminal
curl "https://pos.pages.fm/api/v1/shops?api_key=API_KEY"
  1. Lấy 20 đơn hàng mới nhất của một cửa hàng:
Terminal
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY&page_size=20&page_number=1"
  1. Tạo đơn hàng: gửi JSON trong nội dung yêu cầu.
Terminal
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.
  • 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.
  • currency của cửa hàng, order_currency củ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ửi order_currency VND vào cửa hàng VND100 đượ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_currency củ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 currency của cửa hàng (GET /shops). Giá vốn trong sản phẩm của đơn và cost_surcharge cũng vậy, kể cả khi đơn dùng tiền tệ khác.
  • retail_price_by_currency[].retailPriceByCurrency theo currency củ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.

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.

Khám phá tài liệu