Tài liệu kỹ thuật

Kết nối EcomWeb vào hệ thống của bạn.

Mọi lệnh, module và đường dẫn dữ liệu trên trang này đều lấy từ @ecomweb/cli và @ecomweb/sdk đang phát hành.

Bắt đầu miễn phí Xem trang nhà phát triển

Bắt đầu

Từ con số không đến lần đọc dữ liệu đầu tiên.

Trình cài đặt của công cụ dòng lệnh lo phần tài khoản, cửa hàng và khóa truy cập. Bốn bước dưới đây thường mất khoảng năm phút.

Chạy trình cài đặt
npx @ecomweb/cli setup hỏi email, gửi mã xác thực sáu số, rồi tạo và lưu khóa truy cập ngay sau khi xác thực.
Chọn cửa hàng
Chọn một cửa hàng sẵn có hoặc tạo mới. Mã cửa hàng được ghi lại làm cửa hàng đang dùng cho mọi lệnh sau đó.
Đọc thử dữ liệu
ecomweb products list --output table xác nhận khóa truy cập, cửa hàng và quyền đọc đều đã đúng.
Gắn vào website
Cài @ecomweb/sdk rồi đọc đúng dữ liệu đó ngay trong giao diện bán hàng.

npx @ecomweb/cli setup

# check what the CLI is pointing at
ecomweb auth status
ecomweb stores list --output table

Yêu cầu: Node.js từ phiên bản 18 trở lên.

Xác thực và cấu hình

Một khóa truy cập, ba cách nạp vào.

Cấu hình nằm trong ~/.config/ecomweb/ với quyền tệp 0600. Cờ trên dòng lệnh được ưu tiên trước, sau đó tới biến môi trường, cuối cùng mới tới tệp cấu hình.

Biến môi trường

Biến	Ý nghĩa
`ECOMWEB_API_KEY`	Khóa truy cập, thay cho giá trị trong tệp cấu hình.
`ECOMWEB_STORE_REF`	Mã cửa hàng, thay cho cửa hàng đang chọn.
`ECOMWEB_API_URL`	Địa chỉ API, dùng khi trỏ sang môi trường khác.

Vài điểm cần nhớ

Mỗi môi trường nên là một hồ sơ riêng: ecomweb setup --profile staging, rồi thêm --profile staging vào lệnh.
ecomweb auth status cho biết đang dùng tài khoản nào và cửa hàng nào đang được chọn.
Trong bộ công cụ JavaScript, publicHttp dùng cho dữ liệu công khai của cửa hàng, còn authHttp mang phiên đăng nhập của khách hàng.
Không đưa khóa truy cập vào mã nguồn giao diện: khóa thuộc về máy chủ, dòng lệnh hoặc quy trình tự động.

# non-interactive flow, for CI
ecomweb auth register --email team@example.com
ecomweb auth verify --email team@example.com --code 123456
ecomweb init --store-name "Cua Hang Mau"

# or skip the config file entirely
export ECOMWEB_API_KEY=ew_live_...
export ECOMWEB_STORE_REF=cua-hang-mau
ecomweb products list --quiet

Công cụ dòng lệnh

Mọi phần của cửa hàng đều có lệnh tương ứng.

Các lệnh chia theo nhóm tài nguyên. Mỗi nhóm đều có list, get, create, update và delete khi tài nguyên cho phép, cùng bộ cờ dùng chung bên dưới.

Nhóm lệnh

Nhóm	Quản lý
`products`	Sản phẩm, biến thể, thống kê và các thao tác hàng loạt.
`orders`	Đơn hàng, chuyển trạng thái, đóng gói, giao hàng và hủy đơn.
`customers`	Khách hàng, địa chỉ và thống kê theo khách hàng.
`categories · collections`	Danh mục và bộ sưu tập dùng để sắp xếp catalog.
`promotions · reviews`	Chương trình khuyến mãi và đánh giá của khách hàng.
`blog-posts · blog-categories · blog-tags · blog-settings`	Bài viết, phân loại và thiết lập cho phần nội dung.
`store-pages · store-menus · store-settings`	Trang nội dung, trình đơn và thiết lập của cửa hàng.
`shipping-methods · shipping-zones · shipping-programs`	Phương thức, khu vực và chương trình giao hàng.
`banners · assets`	Ảnh bìa, hình ảnh và video, kèm thao tác tải lên và gắn vào bản ghi.
`analytics · stores · auth · health`	Số liệu bán hàng, chuyển cửa hàng, phiên đăng nhập và kiểm tra kết nối.

Cờ dùng chung

--output json|table|csv: Định dạng kết quả. Mặc định là json.
--fields · --exclude · --full: Chọn, bỏ bớt hoặc lấy đầy đủ các trường trong kết quả.
--dry-run: Xem trước tác động mà không ghi bất kỳ thay đổi nào.
--quiet: Chỉ in dữ liệu, bỏ phần thông báo phụ.
--profile: Chạy lệnh với một hồ sơ cấu hình khác.
--store-ref · --api-key · --api-url: Ghi đè cửa hàng, khóa truy cập và địa chỉ API cho riêng lệnh đang chạy.

# read
ecomweb products list --status active --output table --fields id,name,status
ecomweb orders list --status pending --limit 50

# write from JSON, preview before applying
ecomweb products create --stdin --dry-run < product.json
ecomweb products create --stdin < product.json

# same command against another environment
ecomweb products list --profile staging

Các lệnh ghi nhận dữ liệu JSON qua --stdin hoặc --file, nên có thể nối thẳng kết quả của lệnh này vào lệnh khác.

ecomweb --help liệt kê toàn bộ nhóm lệnh; thêm --help ngay sau tên một nhóm để xem lệnh và cờ của riêng nhóm đó.

Bộ công cụ JavaScript

Một lần khởi tạo, mười tám nhóm dữ liệu.

createEcomwebSdk nhận hai bộ gửi yêu cầu và trả về các nhóm dữ liệu đã gõ kiểu sẵn cho TypeScript.

Cách bộ công cụ hoạt động

Cài đặt: thêm "@ecomweb/sdk": "github:travistech20/ecomweb-sdk" vào package.json.
IHttpClient là giao diện gồm get, post, put, patch và delete, mỗi hàm trả về ApiResponse<T>. Bạn tự bọc fetch, axios hoặc thư viện quen dùng.
unwrap ném lỗi khi yêu cầu thất bại, unwrapOrNull trả về null cho 404, ensureSuccess chỉ kiểm tra kết quả. Lỗi ném ra là ApiClientError kèm statusCode và code.
Các hàm đọc chi tiết như products.getBySlug trả về null khi không tìm thấy, hợp với notFound() của Next.js.

Các nhóm dữ liệu

products
collections
categories
cart
orders
blog
stores
search
banners
shipping
promotions
paymentMethods
reviews
customers
addresses
contentPages
menus
redirects

import { createEcomwebSdk, ApiClientError } from "@ecomweb/sdk";
import { http } from "./http"; // any IHttpClient: fetch, axios, ky...

const sdk = createEcomwebSdk({ publicHttp: http, authHttp: http });

try {
  const product = await sdk.products.getBySlug("cua-hang-mau", "ao-linen", {
    include_variants: true,
  });

  // getBySlug returns null on 404 instead of throwing
  if (!product) notFound();
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(error.statusCode, error.message);
  }
}

Dữ liệu cửa hàng

Đường dẫn dữ liệu đọc ra được ngay từ tên.

Mọi đường dẫn đều gắn với mã cửa hàng. Phần /public phục vụ dữ liệu công khai; phần /tenant cần phiên đăng nhập của khách hàng. Phản hồi luôn gồm ba trường success, data và error.

Phương thức	Đường dẫn	Nội dung
`GET`	`/public/stores/{storeRef}`	Thông tin và cấu hình cửa hàng.
`GET`	`/public/stores/{storeRef}/products/slug/{slug}`	Chi tiết sản phẩm theo slug, kèm biến thể khi cần.
`GET`	`/public/stores/{storeRef}/categories`	Danh mục của cửa hàng.
`GET`	`/public/stores/{storeRef}/collections/slug/{slug}`	Bộ sưu tập theo slug.
`GET`	`/search/public/{storeRef}/catalog`	Tìm kiếm sản phẩm và gợi ý khi gõ.
`GET · POST · PUT · DELETE`	`/public/stores/{storeRef}/cart`	Giỏ hàng của khách chưa đăng nhập, phân biệt bằng tiêu đề x-session-id.
`POST`	`/public/stores/{storeRef}/orders`	Tạo đơn cho khách chưa đăng nhập.
`GET`	`/tenant/stores/{storeRef}/customers/orders`	Đơn hàng của khách đã đăng nhập.
`GET`	`/public/stores/{storeRef}/content-pages/{slug}`	Trang nội dung do người vận hành soạn trong trang quản trị.
`GET`	`/public/stores/{storeRef}/menus/ref/{ref}`	Trình đơn điều hướng của cửa hàng.

Bộ công cụ JavaScript đã bọc sẵn các đường dẫn này. Bảng trên dành cho lúc bạn cần gọi thẳng bằng ngôn ngữ khác hoặc gỡ lỗi.

Dựng giao diện bán hàng

Dữ liệu ở phía máy chủ, tương tác ở phía trình duyệt.

Cách chia việc dưới đây giữ cho trang danh sách và trang chi tiết tải nhanh, trong khi giỏ hàng vẫn phản hồi tức thì.

Đọc sản phẩm, danh mục và trang nội dung trong server component bằng publicHttp; trang tĩnh hóa được và không lộ khóa truy cập.
Giữ giỏ hàng ở client component: mỗi yêu cầu tới nhóm cart cần một x-session-id ổn định cho khách chưa đăng nhập.
Xuất ảnh đúng kích thước bằng buildTransformQuery và toRenderUrl thay vì tải ảnh gốc rồi thu nhỏ trong trình duyệt.
Giữ đường dẫn cũ còn sống bằng nhóm redirects, và lấy trình đơn từ nhóm menus để người vận hành tự đổi trong trang quản trị.

Xem thêmCửa hàng mẫu Trang nhà phát triển

Trợ lý AI và tự động hóa

Xem schema, chạy thử, rồi mới ghi.

Công cụ dòng lệnh được thiết kế để trợ lý lập trình dùng được: kết quả mặc định là JSON, còn mọi lệnh ghi đều chạy thử được trước.

Lấy schema
ecomweb describe <tài nguyên> --operation create hoặc update trả về danh sách trường hợp lệ trước khi ghi bất cứ thứ gì.
Chạy thử
Thêm --dry-run để xem thay đổi sẽ tác động tới đâu mà không ghi vào cửa hàng.
Ghi thật và ghi lại kết quả
Chạy lại lệnh không kèm --dry-run; kết quả JSON đủ để đối chiếu và lưu vào nhật ký.

# 1 · schema first, before writing anything
ecomweb describe products --operation update

# 2 · preview the change, nothing is written yet
ecomweb products update 42 --stdin --dry-run < patch.json

# 3 · apply it, JSON output the agent can parse
ecomweb products update 42 --stdin --quiet < patch.json

Nguyên tắc chung: giới hạn phạm vi từng lệnh, thử trên hồ sơ riêng của môi trường thử, và xin xác nhận của con người trước những thay đổi ảnh hưởng tới giá bán, tồn kho hoặc đơn hàng.

Hỗ trợ

Cần thêm chi tiết cho trường hợp của bạn?

Tài liệu này bám theo phiên bản công cụ đang phát hành. Nếu bạn cần một luồng tích hợp chưa có ở đây, hãy nói với đội ngũ.

Bắt đầu miễn phí Liên hệ đội ngũ

Chạy trình cài đặt

Chọn cửa hàng

Đọc thử dữ liệu

Gắn vào website