Tính năng Nhập dữ liệu (Website → Nhập dữ liệu trong trình quản trị) chuyển nội dung từ website cũ sang xStore. Bạn trỏ tới một tệp JSON (địa chỉ URL hoặc tải tệp lên), xem trước kết quả chạy thử, rồi bắt đầu nhập. Công việc chạy nền, có thể huỷ, thử lại các mục lỗi và chạy lại nhiều lần mà không tạo bản sao.
Có hai cách cấp dữ liệu:
- JSON chuẩn xStore (trang này) — bạn hoặc đơn vị làm web tự xuất tệp theo cấu trúc dưới đây.
- Nền tảng có sẵn — Shopify, WooCommerce, Haravan, Sapo: xStore tự đọc và quy đổi về JSON chuẩn. Xem Nhập từ Shopify, WooCommerce, Haravan, Sapo.
Tính năng thuộc gói có khoá site_import và cần quyền site_import.manage.
1. Nhập những gì, không nhập những gì
| Nhập | Không nhập |
|---|---|
| Sản phẩm (biến thể, tuỳ chọn, ảnh, SEO, thuộc tính), thương hiệu, danh mục sản phẩm, bộ sưu tập | Khách hàng |
Tồn kho: số lượng theo biến thể và kho (inventory[], hoặc stock của biến thể) |
|
| Bài viết, danh mục bài viết, trang nội dung | Đơn hàng |
| Khuyến mãi, mã giảm giá (luôn ở trạng thái chưa kích hoạt) | Phiếu nhập/xuất kho, lô, kệ (chỉ nhập số lượng tồn, xem inventory[]) |
| Chuyển hướng 301 từ URL cũ | Đồng bộ định kỳ — đây là lần chuyển một lần, có thể chạy lại |
2. Cách một lần nhập hoạt động
- Tạo lần nhập: chọn nguồn đã tạo hoặc tạo nguồn mới (xem phần Nguồn nhập bên dưới), rồi chọn nền tảng, nội dung cần nhập và tuỳ chọn.
- Chạy thử (trạng thái
fetchingrồipreviewed): xStore đọc tệp, kiểm tra từng bản ghi, đối chiếu với những gì đã nhập trước đó và cho biết sẽ tạo mới / cập nhật / liên kết / bỏ qua bao nhiêu bản ghi, bản ghi nào không hợp lệ, và hạn mức gói có đủ không. Chưa ghi gì cả. - Bắt đầu (trạng thái
running): các bản ghi được ghi theo thứ tự phụ thuộc — thương hiệu, danh mục sản phẩm, bộ sưu tập, sản phẩm, tồn kho, danh mục bài viết, bài viết, trang, khuyến mãi, mã giảm giá, chuyển hướng. Các bản ghi được xử lý lần lượt từng bản ghi và lưu riêng; bản ghi lỗi được thử lại tối đa 3 lần rồi mới đánh dấu lỗi, không làm dừng cả lần nhập. Lần nhập chạy được không cần theo dõi: nếu một tiến trình xử lý bị dừng đột ngột, hệ thống tự khởi động lại. - Tải ảnh (vẫn là trạng thái
running): sau khi xong các bản ghi, ảnh sản phẩm, thương hiệu, danh mục, bài viết và mọi ảnh nằm trong nội dung HTML (description_html,content_html) được tải về ở bước riêng, tối đa 2 luồng song song. Mỗi ảnh chỉ tải một lần dù được dùng ở nhiều nơi. Ảnh trong nội dung được thay bằng đường dẫn mới; ảnh lỗi giữ nguyên đường dẫn cũ và được liệt kê ở thẻ Ảnh lỗi của trang chi tiết. Trang chi tiết hiển thị hai thanh tiến độ: Bản ghi và Ảnh. - Kết thúc ở một trong
completed,failed,cancelled,stopped_quota. Lần nhập chỉcompletedkhi cả bản ghi lẫn ảnh đều đã xử lý xong.
Bạn có thể huỷ (dừng sau bản ghi đang xử lý, phần đã nhập được giữ lại) và thử lại các mục lỗi khi lần nhập đã kết thúc.
Nguồn nhập
Một nguồn là một hệ thống cũ, ví dụ "Website cũ Haravan". Bạn tạo nguồn một lần (Website → Nhập dữ liệu → Nguồn nhập, hoặc ngay trong bước đầu của lần nhập), rồi chọn nó cho mọi lần nhập từ hệ thống đó, dù là URL hay tệp tải lên.
- Một hệ thống cũ, một nguồn. xStore nhớ mã cũ của từng bản ghi theo nguồn. Dùng lại cùng một nguồn thì các tệp nhập riêng lẻ nhận ra nhau: nhập lại không tạo bản sao và bản ghi trong tệp này tham chiếu được tới bản ghi của tệp khác.
- Nhập theo thứ tự bất kỳ, chia nhiều tệp (bài viết hôm nay, sản phẩm ngày mai). Một tham chiếu tới bản ghi chưa có (sản phẩm trỏ tới danh mục chưa nhập, mã giảm giá trỏ tới khuyến mãi chưa nhập...) không bị bỏ: nó được giữ lại và tự liên kết khi bản ghi đó xuất hiện, trong lần nhập này hay lần sau của cùng nguồn.
- Liên kết chỉ thêm, không ghi đè. Danh mục được thêm vào danh mục hiện có của sản phẩm (không thay thế); thương hiệu và danh mục cha chỉ được gán khi đang để trống. Khuyến mãi và mã giảm giá vẫn luôn ở trạng thái chưa kích hoạt.
- Bước xem trước có dòng "liên kết đang chờ": bao nhiêu liên kết đã chờ từ các lần nhập trước sẽ được nối ngay nhờ tệp này, và bao nhiêu tham chiếu đang chờ bản ghi không có trong tệp. Trang chi tiết lần nhập và trang Nguồn nhập cho biết số bản ghi đã liên kết và số liên kết còn chờ của mỗi nguồn.
- Xoá nguồn chỉ được khi nguồn chưa có lần nhập nào; khi xoá, các liên kết ghi nhớ của nguồn cũng mất.
- Các lần nhập đã có từ trước được chuyển tự động sang nguồn có tên đặt sẵn (theo tên miền hoặc mã tệp); bạn có thể đổi tên chúng.
3. Cấu trúc JSON chuẩn (phiên bản 1)
Tải về: JSON Schema · tệp mẫu đầy đủ.
Tệp là một đối tượng JSON gồm version, source và các danh sách (tất cả đều tuỳ chọn):
brands, product_categories, collections, products, article_categories, articles,
pages, promotions, coupons, redirects. Khoá lạ bị bỏ qua nên tệp vẫn dùng được khi
cấu trúc được mở rộng sau này.
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
version |
chuỗi | có | Luôn là "1". Phiên bản khác bị từ chối cả tệp |
source.platform |
chuỗi | có | Tên nền tảng nguồn, ví dụ xstore_json |
source.url |
chuỗi | không | Địa chỉ website cũ |
source.currency |
chuỗi | không | Mặc định VND |
next |
chuỗi | không | Địa chỉ trang kế tiếp (phân trang): phải cùng website (cùng giao thức, tên miền và cổng) với tệp đầu; tối đa 1 000 trang; bỏ qua khi tải tệp lên |
Quy tắc chung
- Tiền là số nguyên VND (không có phần thập phân, không có dấu phân cách):
120000. external_idlà khoá idempotent. Mỗi bản ghi cóexternal_idổn định, duy nhất trong từng danh sách. xStore dùng nó để biết bản ghi đã nhập chưa. Đổiexternal_idgiữa hai lần chạy sẽ tạo bản sao. Tối đa 191 ký tự. Riêng mã giảm giá dùngcode, chuyển hướng dùngfrom_path.slugđược chuẩn hoá (bỏ dấu, chữ thường, gạch nối). Bỏ trống thì sinh từ tên.old_url: địa chỉ cũ của sản phẩm/bài viết/trang, dạng URL đầy đủhttp(s)://…hoặc đường dẫn bắt đầu bằng/. Dùng để tạo chuyển hướng 301 tự động (§6).- HTML (
description_html,content_html) được làm sạch khi nhập. - Ngày giờ dạng ISO 8601; không có múi giờ được hiểu là UTC.
- Bản ghi sai cấu trúc bị bỏ qua và báo lỗi trong kết quả chạy thử; phần còn lại vẫn nhập. Hai bản ghi trùng định danh trong cùng danh sách: bản sau bị bỏ.
brands[]
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
external_id |
chuỗi | có | |
name |
chuỗi | có | |
slug |
chuỗi | không | |
logo_url |
chuỗi | không | Tải về nếu bật "tải ảnh" |
product_categories[]
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
external_id |
chuỗi | có | |
name |
chuỗi | có | |
slug |
chuỗi | không | |
parent_external_id |
chuỗi | không | Danh mục cha, tham chiếu external_id |
description_html |
chuỗi | không | |
image_url |
chuỗi | không |
collections[]
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
external_id |
chuỗi | có | |
title |
chuỗi | có | |
slug, description_html, image_url |
chuỗi | không |
products[]
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
external_id |
chuỗi | có | |
title |
chuỗi | có | |
slug |
chuỗi | không | |
old_url |
chuỗi | không | Tạo chuyển hướng 301 |
description_html |
chuỗi | không | |
brand_external_id |
chuỗi | không | Tham chiếu brands[].external_id |
category_external_ids |
mảng chuỗi | không | Tham chiếu product_categories |
collection_external_ids |
mảng chuỗi | không | Tham chiếu collections |
options[] |
mảng | không | {name, values[]}, ví dụ "Khối lượng": 250g, 500g |
variants[] |
mảng | không | Xem bảng bên dưới |
images[] |
mảng | không | {url, alt?, position?}; trùng URL bị gộp; tối đa 10 ảnh/sản phẩm được nhập |
attributes |
đối tượng | không | Cặp tên → giá trị, ví dụ {"Xuất xứ": "Đà Lạt"} |
seo |
đối tượng | không | {title?, description?} |
status |
active | draft |
không | Mặc định draft |
Mỗi biến thể trong variants[]:
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
external_id |
chuỗi | có | |
sku, barcode |
chuỗi | không | |
price |
số nguyên | không | VND, >= 0, mặc định 0 |
compare_at_price |
số nguyên | không | Giá gốc để hiển thị giảm giá |
stock |
số nguyên | không | Tồn kho >= 0, được nhập vào kho mặc định khi tạo/cập nhật sản phẩm; để trống thì không ghi gì. Là số tuyệt đối |
weight_grams |
số nguyên | không | |
option_values |
mảng chuỗi | không | Khi sản phẩm có options, mỗi biến thể phải có đúng bằng số tuỳ chọn giá trị, theo cùng thứ tự |
inventory[]
Tồn kho theo biến thể và kho. Có thể là một tệp riêng, nhập trước hoặc sau tệp sản phẩm: nếu biến thể chưa có, dòng tồn kho được giữ lại và ghi số lượng khi biến thể xuất hiện (xem phần Nguồn nhập).
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
variant_external_id |
chuỗi | một trong hai | external_id của biến thể trong products[].variants[] (cùng nguồn) |
sku |
chuỗi | một trong hai | SKU biến thể; dùng khi không có variant_external_id. xStore tìm theo biến thể đã nhập, rồi theo SKU của cửa hàng |
location_code |
chuỗi | không | Mã kho (≤ 50 ký tự). Không có hoặc không tìm thấy thì dùng kho mặc định (kèm cảnh báo nếu mã không tồn tại) |
quantity |
số nguyên | có | >= 0, số tuyệt đối (không phải số cộng thêm) |
external_id |
chuỗi | không | Mặc định variant_external_id hoặc sku:<sku>, thêm @<location_code> nếu có kho |
Mỗi (biến thể, kho) một dòng. Lần chạy lại bỏ qua dòng đã nhập, trừ khi bật Cập nhật bản ghi đã nhập.
Số lượng được ghi bằng một lần điều chỉnh tồn kho với lý do site_import; nếu số lượng không đổi thì không ghi gì.
article_categories[], articles[], pages[]
| Danh sách | Trường |
|---|---|
article_categories[] |
external_id*, name*, slug |
articles[] |
external_id*, title*, slug, old_url, category_external_ids[], author, excerpt, content_html, image_url, published_at, tags[], seo{title,description} |
pages[] |
external_id*, title*, slug, old_url, content_html, seo{title,description} |
(* bắt buộc.) Bài viết được tạo ở trạng thái nháp để bạn duyệt trước khi đăng.
promotions[], coupons[], redirects[]
| Danh sách | Trường |
|---|---|
promotions[] |
external_id*, name*, type* (percent | fixed | free_shipping | buy_x_get_y), value (nguyên, >= 0; percent tối đa 100), min_order_amount, starts_at, ends_at, applies_to{product_external_ids[], category_external_ids[]} |
coupons[] |
code*, promotion_external_id, usage_limit, starts_at, ends_at |
redirects[] |
from_path*, to_path* — chuyển hướng viết tay thêm vào danh sách |
Ví dụ rút gọn
{
"version": "1",
"source": { "platform": "xstore_json", "url": "https://old-shop.example.com", "currency": "VND" },
"brands": [{ "external_id": "b1", "name": "Aroma" }],
"product_categories": [{ "external_id": "c1", "name": "Cà phê", "slug": "ca-phe" }],
"products": [
{
"external_id": "p1",
"title": "Cà phê Arabica",
"slug": "ca-phe-arabica",
"old_url": "https://old-shop.example.com/products/ca-phe-arabica",
"brand_external_id": "b1",
"category_external_ids": ["c1"],
"options": [{ "name": "Khối lượng", "values": ["250g", "500g"] }],
"variants": [
{ "external_id": "v1", "sku": "ARA-250", "price": 120000, "option_values": ["250g"] },
{ "external_id": "v2", "sku": "ARA-500", "price": 220000, "option_values": ["500g"] }
],
"images": [{ "url": "https://old-shop.example.com/img/arabica.jpg", "position": 1 }],
"status": "active"
}
],
"promotions": [{ "external_id": "pr1", "name": "Giảm 10%", "type": "percent", "value": 10 }],
"coupons": [{ "code": "SALE10", "promotion_external_id": "pr1" }]
}
4. Tuỳ chọn
| Tuỳ chọn | Mặc định | Ý nghĩa |
|---|---|---|
update_existing |
tắt | Tắt: bản ghi đã nhập trước đó bị bỏ qua. Bật: cập nhật theo dữ liệu mới |
import_images |
bật | Tải ảnh về và lưu trên máy chủ tệp của xStore. Tắt: không nhập ảnh |
create_redirects |
bật | Tạo chuyển hướng 301 từ old_url sang địa chỉ mới |
match_existing |
bật | Liên kết thương hiệu, danh mục sản phẩm, bộ sưu tập, danh mục bài viết và trang với bản ghi đã có trong xStore (khớp theo slug, sau đó theo tên không phân biệt hoa thường) thay vì tạo trùng. Tên khớp với nhiều bản ghi thì không liên kết |
match_products_by_sku |
tắt | Liên kết sản phẩm với sản phẩm đã có nếu một SKU của biến thể trùng (SKU đầu tiên trong tệp mà đã tồn tại quyết định sản phẩm) |
Liên kết với bản ghi có sẵn. Bản ghi được liên kết không tạo mới mà dùng bản ghi đã có: mã cũ được ghi nhớ (nên bản ghi khác
tham chiếu tới nó và các liên kết đang chờ được nối), chuyển hướng 301 trỏ tới địa chỉ của bản ghi đó, và bản ghi không bị sửa
trừ khi update_existing bật. Giới hạn: danh mục được khớp theo tên bất kể danh mục cha; sản phẩm liên kết theo SKU không ghi thêm
gì (kể cả tồn kho) và không tính vào hạn mức sản phẩm; bản ghi đã nhập qua cùng nguồn thì không khớp lại (dùng bản đã ghi nhớ).
Bài viết, khuyến mãi, mã giảm giá, tồn kho và chuyển hướng không bao giờ được khớp.
Có thể giới hạn loại nội dung cần nhập (mặc định tất cả loại có trong tệp).
5. Giới hạn
| Hạng mục | Giới hạn |
|---|---|
| Kích thước tệp JSON | 50 MB mỗi trang (tệp đầu và mỗi trang next) |
Số trang theo next |
1 000 |
| Số bản ghi mỗi loại nội dung | 20 000, tính trên tất cả các trang |
| Số ảnh tải song song mỗi lần nhập | 2 (mặc định) |
| Số ảnh trong một trường HTML | 50 |
| Thời gian chờ mỗi yêu cầu tải | 60 giây |
| Dung lượng một ảnh | 20 MB |
| Số ảnh nhập mỗi sản phẩm | 10 |
| Cổng được phép khi tải URL | 80 và 443 |
| Địa chỉ được phép | Chỉ địa chỉ công khai — địa chỉ nội bộ/riêng tư bị chặn, kể cả sau khi chuyển hướng |
Hạn mức gói: chạy thử cho biết số sản phẩm và dung lượng ảnh cần dùng. Nếu vượt products
hoặc storage_mb thì nút Bắt đầu bị khoá. Nếu hạn mức hết giữa chừng, lần nhập dừng gọn với
trạng thái stopped_quota, phần đã nhập được giữ lại; giải phóng hạn mức hoặc nâng cấp rồi
Thử lại.
Mỗi lần chỉ chạy một lần nhập cho cùng một nguồn nhập (các nguồn khác nhau chạy song song được).
6. Chuyển hướng 301
Mỗi bản ghi có old_url (và create_redirects đang bật) sinh một chuyển hướng từ đường dẫn cũ sang
địa chỉ mới của sản phẩm/bài viết/trang. Đường dẫn cũ được chuẩn hoá: bỏ tên miền, chữ thường,
bắt đầu bằng /, bỏ dấu / cuối (trừ trang chủ); chuỗi truy vấn chỉ giữ khi có trong nguồn.
Quản lý tại Website → Chuyển hướng URL: tìm kiếm, thêm/sửa/xoá, xoá hàng loạt. Cửa hàng ghi nhớ kết quả tối đa 5 phút nên thay đổi có hiệu lực trong khoảng 5 phút (hiện chưa có cơ chế xoá bộ nhớ đệm ngay).
7. Khuyến mãi và mã giảm giá
Luôn được tạo ở trạng thái chưa kích hoạt, bất kể tệp ghi gì. Hãy kiểm tra rồi tự bật.
Sản phẩm áp dụng (applies_to.product_external_ids) được thêm vào khuyến mãi khi sản phẩm đó đã nhập, kể cả ở
lần nhập sau. Danh mục áp dụng (category_external_ids) được chuyển thành điều kiện "danh mục thuộc..." của
khuyến mãi; nếu khuyến mãi đã có điều kiện sản phẩm khác thì danh mục đó không được áp dụng (liên kết ghi
cảnh báo "category restriction not applied") để không ghi đè cấu hình của bạn. Mã giảm giá trỏ tới khuyến
mãi chưa nhập sẽ được tạo khi khuyến mãi xuất hiện.
8. Những điều chưa được hỗ trợ
- Tồn kho chỉ nhập số lượng (kho mặc định hoặc kho chọn bằng
location_code); lô, kệ và phiếu kho không được nhập. - Thuộc tính sản phẩm (
attributes) được gom vào một loại sản phẩm tự tạo tên "Nhập từ website cũ". - Khuyến mãi
buy_x_get_yđược nhập dưới dạng khuyến mãi mô tả (free_text) để bạn cấu hình lại. - Giới hạn lượt dùng và ngày hiệu lực của mã giảm giá chưa được nhập.
- Bài viết luôn là bản nháp.
- Sản phẩm
activemà hệ thống từ chối cho lên cửa hàng (ví dụ thiếu dữ liệu bắt buộc) được lưu ở dạng nháp kèm cảnh báo. - Chạy lại một lần nhập đã kết thúc (thử lại / tiếp tục) đưa nó về trạng thái
running.