Truy cập dữ liệu

App đọc/ghi dữ liệu shop qua Open API hiện có (tài liệu Open API): cùng endpoint, format response, phân trang và quy tắc cập nhật. Code đang chạy với API key chỉ cần đổi cách lấy credential.

// Trước: key cố định, toàn quyền, dễ lộ khi nằm trong code frontend
fetch(`https://pos.pages.fm/api/v1/shops/${SHOP_ID}/orders?api_key=${STATIC_KEY}`);

// Trong app: SDK tự gắn app token
await pos.api.get(`/shops/${pos.shop.id}/orders`);

#App token

POS tự cấp app token khi extension chạy; app không cần và không nên có API key cố định.

• Token gắn với một shop, một user, một app và version đang chạy.
• SDK gửi token qua header Authorization: Bearer <token>. Tham số ?api_key=<token> vẫn được chấp nhận để tương thích code Open API cũ, nhưng không khuyến nghị vì URL dễ lọt vào log.
• Token bị thu hồi ngay khi: app bị tắt hoặc gỡ, admin đổi access, user đăng xuất hoặc bị đổi phiên đăng nhập. User bị xóa khỏi shop hoặc đổi role thì có hiệu lực từ request kế tiếp.

#Quyền hiệu lực

Quyền của app token = quyền của user đang dùng ∩ access của app (bản admin đã duyệt)

Quyền của user áp dụng giống hệt khi user thao tác trên POS: role, quyền theo kho, quyền theo bảng/trường CRM, bộ phận, giờ làm việc, IP được phép, module đang bật và gói dịch vụ.

access của app thu hẹp thêm: method được dùng (mặc định chỉ GET), kho, nguồn đơn, trạng thái đơn, thời điểm tạo đơn, danh mục/thương hiệu sản phẩm, trường đơn bị ẩn. Xem Manifest › access.

Hệ quả:

• Cùng một app, người có quyền rộng thấy nhiều dữ liệu hơn người có quyền hẹp.
• Request chạy được bằng Shop API Key có thể bị từ chối với app token. Đây là hành vi đúng.
• App nên xử lý lỗi 403 thay vì giả định mọi người dùng đều có quyền.

#Nhóm luôn bị chặn

Các nhóm sau chỉ dùng được từ phiên đăng nhập trên giao diện POS, mọi loại API key và app token đều bị từ chối:

• Quản lý nhân sự: thêm/sửa nhân viên, phân quyền.
• Liên kết tài khoản Google.
• Quản lý API key.
• Quản lý app và cấp app token.

#Endpoint được gọi

• Chỉ dùng các endpoint có trong tài liệu Open API. Endpoint nội bộ của giao diện POS có thể đổi bất kỳ lúc nào và sẽ bị chặn với app token.
• Mọi đường dẫn phải thuộc shop hiện tại: /shops/{shop_id}/....
• Thiếu dữ liệu hoặc thao tác cần thiết: gửi yêu cầu bổ sung vào Open API thay vì dùng endpoint nội bộ.

Endpoint chính của các resource có extension point:

#Dữ liệu ngữ cảnh

pos.data chứa dữ liệu tối thiểu POS đang hiển thị (ví dụ mã và trạng thái đơn hay phiếu nhập đang mở) để extension không phải gọi API ngay khi khởi động. Dữ liệu này đã được lọc theo access của app. Cần thêm dữ liệu thì gọi Open API.

#Giới hạn tần suất

• Tính theo app + user + shop + endpoint; nhiều extension của cùng app dùng chung hạn mức: dưới 30 lượt đọc (GET) và dưới 100 lượt ghi mỗi giây.
• Vượt giới hạn: HTTP 429. Thử lại sau, tăng dần thời gian chờ (ví dụ 1 s, 2 s, 4 s), tối đa 3 lần.
• Không gọi API trong vòng lặp render. Gom request, dùng phân trang và AbortSignal để huỷ request cũ khi người dùng đổi bộ lọc.

#Audit

Mọi thao tác ghi bằng app token được lưu với user thật, app và version. Các trường tự động như người tạo, người sửa ghi theo user đang dùng.

#Mã lỗi

Cột code là trường error_code trong body, SDK đưa vào PosApiError.code.

#Gọi hệ thống bên ngoài

• Khai origin trong network.allowed_origins; request tới origin khác bị chặn.
• Server bên ngoài phải bật CORS cho origin sandbox của app, là header Origin trong request app gửi tới khi chạy bản đã kích hoạt. Ở chế độ phát triển, origin là địa chỉ bạn nhập khi bật (ví dụ http://localhost:5174); muốn thử thì bật CORS cho cả origin này.
• Không gửi app token ra ngoài, trừ backend của trang tự host. Hệ thống bên ngoài cần dữ liệu POS thì app đọc qua Open API rồi gửi phần cần thiết.
• Không đặt secret trong code app. Mọi người dùng mở được app đều tải được bundle. Cần gọi hệ thống có secret thì đặt một backend trung gian của shop, xác thực người gọi bằng cách riêng.

#Tác vụ chạy nền

App chỉ chạy khi có người đang mở POS. Tác vụ định kỳ, đồng bộ hoặc xử lý sự kiện khi không ai mở POS cần backend riêng của shop:

• Gọi Open API bằng User API Key (khuyến nghị, quyền theo user) hoặc Shop API Key như hiện nay.
• Nhận sự kiện thay đổi qua webhook của shop (Cấu hình › Webhook - API).

Dự kiến giai đoạn 2: service key theo app (chạy dưới danh nghĩa một user được chỉ định, áp access của app) và webhook đăng ký theo app có ký HMAC.

#Dữ liệu riêng của app

Phiên bản này chưa có kho lưu trữ riêng cho app. Lựa chọn:

• Bảng CRM tuỳ biến của shop, đọc/ghi qua Open API: có sẵn phân quyền theo bảng và trường.
• Backend riêng của shop.
• localStorage trong trang iframe: chỉ lưu trên trình duyệt hiện tại, phù hợp cho tuỳ chọn giao diện.