Trang này liệt kê toàn bộ endpoint /public/v1/* — đủ để dựng một website Next.js hoặc ứng dụng React Native mà không cần truy cập trực tiếp cơ sở dữ liệu.

Xác thực#

Mọi request đều gửi kèm header X-Xstore-Key:

curl -H "X-Xstore-Key: pk_live_..." \
  "https://api.xstore.vn/public/v1/products?limit=12"

Khoá tạo trong trang quản trị Cài đặt → Khoá API. Khoá này công khai theo thiết kế: nó chỉ mở ra dữ liệu vốn đã công khai, và bản dựng Next.js hay ứng dụng di động của bạn sẽ gửi nó tới mọi khách truy cập. Điều đó là bình thường — đừng cố giấu nó. Khoá bị lộ hay dùng sai thì thu hồi, không cần đổi tên miền hay tài khoản.

Khoá xác định cửa hàng, nên bạn không cần header Host — đó là lý do ứng dụng di động gọi thẳng api.xstore.vn được.

Có hai loại khoá và chúng không thay thế cho nhau.

Khoá	Lấy ở	Dùng cho	Bí mật?
pk_live_…	Cài đặt → Khoá API	đọc dữ liệu công khai qua /public/v1 (trang này)	không — gửi tới mọi khách
sk_live_…	Nhà phát triển → Khoá API	API quản trị, và xstore theme để dựng giao diện Liquid	có — đừng commit, đừng đưa vào mã client

Khoá sk_live_ gửi ở header Authorization: Bearer sk_live_… và chỉ làm được đúng những quyền bạn tick khi tạo. Xem Phát triển trên máy để dùng nó với giao diện Liquid.

Phân trang#

Mọi endpoint danh sách trả về cùng một phong bì:

{ "items": [ ... ], "next_cursor": "2026-08-01 12:00:00|p001", "has_more": true }

Gửi lại next_cursor ở lần gọi sau. next_cursor là null khi đã hết dữ liệu.

Hai quy ước dễ sai#

url là đường dẫn dùng được, hoặc null — không bao giờ tự ghép. Nếu url là null, hãy hiển thị chữ thường, đừng tạo thẻ <a>. Tự ghép /san-pham/{slug} sẽ tạo ra liên kết chết ngay khi cửa hàng đổi cấu trúc URL. Ngoại lệ duy nhất là bài viết: bài viết không có cột url, đường dẫn luôn là /bai-viet/<slug>.

Số tiền là số nguyên VND. Một vài trường (discount_value) trả về dạng chuỗi — hãy ép kiểu trước khi so sánh.

Base URL: https://api.xstore.vn/public/v1
Header bắt buộc: X-Xstore-Key

Endpoint đọc#

Endpoint gắn thêm từ /public/*#

Cùng một handler, hai đường dẫn. Chữ ký chi tiết xem trang xStore JS.