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:

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

  1. 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.
  2. Chạy thử (trạng thái fetching rồi previewed): 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ả.
  3. 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.
  4. 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.
  5. Kết thúc ở một trong completed, failed, cancelled, stopped_quota. Lần nhập chỉ completed khi 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.

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

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ợ