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

```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](/developers/api/authentication).
2. Lấy danh sách cửa hàng mà key dùng được, kèm mã cửa hàng:

```bash
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:

```bash
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.

```bash
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](/developers/api/order).

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

| 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](/developers/api/schemas).
- Mỗi trang có bản Markdown; [llms.txt](/developers/api/llms.txt) giúp công cụ AI đọc đúng tài liệu.

## Liên quan

- [POS Apps](/developers/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](/developers/mcp) để Claude, Codex, Cursor dùng Open API qua câu lệnh thường ngày.