STOREFRONT DEVELOPER GUIDE
Xây dựng website tài khoản và bán hàng
Chọn tác vụ, đọc contract, chạy ví dụ, kiểm tra kết quả. Không cần dùng API quản trị hoặc biết ID workspace/store của khách.
Bắt đầu tại đây
- Nhờ quản trị bật account policy và liên kết store/channel; xem điều kiện môi trường.
- Dùng client cùng origin, bootstrap session và CSRF.
- Dựng register/login/logout và profile.
- Dựng danh sách/chi tiết sản phẩm, chọn variant rồi thêm giỏ.
- Hoàn thiện quote → xác nhận → checkout, đơn hàng/tracking.
- Chạy checklist nghiệm thu, gồm hai account cách ly và retry không trùng đơn.
Reference hay hướng dẫn?
API Reference →
Endpoint, kiểu giá trị, điều kiện auth, lỗi và quy tắc retry đang hỗ trợ.
Build guide →
Cấu trúc theme và JavaScript cho từng trang.
Học gì từ Shopify?
Đối chiếu tài liệu chính thức ngày 29/09/2026. Đây là lựa chọn thiết kế cho Skai, không phải tuyên bố tương thích Shopify API.
| Shopify | Skai hiện tại / quyết định |
|---|---|
| Customer Account API: buyer profile/orders, OAuth/PKCE | Tách account khách khỏi Console. Giữ email/password + cookie/CSRF cùng origin; không đổi auth đã chốt. |
| Product query: lookup handle/id | Dùng products.find(slug=slug) trong template, cùng visibility/channel policy với products.get/paginate. |
| Cart và checkoutUrl | Skai dùng giỏ backend → quote → xác nhận → COD; chưa có hosted checkout tương đương. |
| Ajax Cart API cho theme | Ưu tiên recipe HTML/JS theo tác vụ; không gọi Admin API từ browser khách. |
| API versioning | Giữ endpoint/casing hiện có; thay đổi breaking cần phiên bản mới, adapter và migration guide. |
Trạng thái triển khai
- Đang có: email/password, profile, catalog qua object products, cart, quote/checkout COD, orders/tracking qua object orders. Reference ghi chính xác shape hiện hành, kể cả casing chưa đồng nhất.
- Đợt A: đã triển khai docs task-first, object products.get/find/paginate và trang /products/[slug] trong website draft; service/HTTP/render tests đạt. Chưa coi đây là hoàn tất lộ trình B/C.
- Đề xuất đợt B, chưa dùng: contract v1 chuẩn snake_case, schema/OpenAPI, client typed, lỗi theo field/request_id và migration legacy. Không đổi key dữ liệu Description của user.
- Đề xuất đợt C, chưa dùng: guest cart, merge giỏ và commerce mở rộng. Cần policy và security tests riêng, không chỉ bỏ login.
Đơn hàng: orders.get/find/paginate và tracking; đã bỏ API đọc đơn cũ.
Quy tắc developer cần nhớ
- Product là sản phẩm; variant là đơn vị mua. Gửi variant.id, không product.ID.
- Giá là integer minor unit theo currency. Quote là báo giá, không giữ chỗ tồn kho.
- API tự lấy scope từ host; UUID trong URL không phải quyền truy cập.
- Retry checkout cùng payload/key; không tự chấp nhận báo giá đổi.
- Không lưu cookie/token/mật khẩu vào theme config; không cache dữ liệu khách.
- Chưa có tính năng trong reference nghĩa là chưa được hỗ trợ, không suy ra từ Shopify hoặc tên mục Lingo.