Cho chủ hệ thống MARZI

Vận hành sàn Marzi Market

Sàn là app thứ ba, gom sản phẩm của các cửa hàng. MARZI thu phí sàn theo phần trăm tiền hàng. Trang này nói cách bật cửa hàng lên sàn, ký thỏa thuận, nhận tiền của khách và xử lý đơn. Hình minh họa dùng dữ liệu giả.

1. Sàn hoạt động thế nào

Cửa hàng lên sàn khi được bật Hiển thị trên sàn. Sản phẩm của họ lấy trực tiếp từ website của cửa hàng (hoặc kho của MARZI) và hiện cạnh sản phẩm của các cửa hàng khác.
Một giỏ nhiều cửa hàng: đơn của khách được tách theo từng cửa hàng, mỗi phần có trạng thái riêng.
Cửa hàng đã ký thỏa thuận phí sàn (và có website nhận đơn, có tài khoản nhận đơn) thì phần đơn của họ được gửi về website và app quản lý của họ.
Cửa hàng chưa ký thì phần đơn ở lại hệ thống MARZI: bạn xử lý ở trang Đơn sàn.
Khách thanh toán khi nhận hàng, hoặc chuyển khoản bằng mã QR vào tài khoản của MARZI (đơn chờ tiền, tiền về mới gửi cho cửa hàng).

Đơn không bao giờ bị mất

Đơn luôn được lưu ở MARZI trước. Chỉ khi website của cửa hàng nhận đơn thì phần đó mới chuyển sang cửa hàng. Website lỗi, đang bảo trì hoặc từ chối (ví dụ hết hàng) thì phần đó ở lại MARZI kèm lý do hiện trong chi tiết đơn.

2. Đưa cửa hàng lên sàn

Trong bảng điều khiển: Khách hàng → chọn cửa hàng → thẻ Hồ sơ cửa hàng.

Hồ sơ cửa hàng: bật hiển thị trên sàn, loại, tỉnh/thành, mô tả ngắn, logo, giấy phép và mã số thuế.

Hiển thị trên sàn: bật. Cửa hàng cần có mã doanh nghiệp và mô tả ngắn (ít nhất 3 ký tự).
Loại cửa hàng, tỉnh/thành, mô tả ngắn, logo (địa chỉ https): hiện trong danh sách cửa hàng của sàn. Không có logo thì app hiện chữ cái đầu của tên.
Giấy phép kinh doanh và mã số thuế: hiện ở màn "Thông tin cửa hàng" trong app người mua của cửa hàng đó (đây là thông tin duy nhất ngoài tên cửa hàng mà app người mua hiện).
Tắt cửa hàng (bỏ "Đang hoạt động") là cửa hàng biến khỏi sàn sau chừng một phút.

Cửa hàng có website cần connector hoạt động (xem hướng dẫn kết nối website) để sản phẩm hiện trên sàn.

3. Ký thỏa thuận phí sàn

Cùng trang cửa hàng, thẻ Bán trên sàn MARZI. Chỉ chủ hệ thống ký, đổi hoặc kết thúc; đại lý chỉ xem.

Ô	Ý nghĩa
Phí sàn (% tiền hàng)	Từ 0,1 đến 50 (tối đa hai số lẻ). Tính trên tiền hàng, không tính phí giao. Tỉ lệ được lưu theo từng đơn lúc đặt: đổi tỉ lệ sau không đổi các đơn cũ.
Tài khoản nhận đơn trên website	Mã thành viên (member) mà cửa hàng tạo riêng trên website để nhận đơn sàn. Đơn sàn hiện trên website (và app quản lý) dưới tên thành viên đó, kèm ghi chú `[Sàn MARZI MK-…]`; họ tên, điện thoại, địa chỉ là của người mua thật. Để trống thì đơn vẫn ở lại MARZI dù đã ký.

Cửa hàng không có website chưa nhận được đơn sàn trong app quản lý nên đơn của họ vẫn ở lại MARZI dù đã ký (thẻ có cảnh báo).
Kết thúc thỏa thuận: từ đó đơn mới của cửa hàng ở lại MARZI; đơn cũ không đổi.
Việc ký, đổi, kết thúc được ghi ở Nhật ký.

4. Tài khoản nhận tiền của sàn

Vào Đơn sàn → tab Tài khoản nhận tiền. Cách nhập, quét thử và bật tự động xác nhận bằng SePay giống hệt cửa hàng; xem Thanh toán chuyển khoản bằng mã QR. Điểm khác: webhook của sàn là /v1/payments/sepay/_marzi.

Tab Tài khoản nhận tiền của sàn — Tài khoản nhận tiền của sàn.

Khi chưa có tài khoản (hoặc đã tắt), app sàn không hiện lựa chọn "Chuyển khoản bằng mã QR": khách chỉ thanh toán khi nhận hàng.

5. Xử lý Đơn sàn

Menu Đơn sàn (chỉ chủ hệ thống). Số chờ xử lý hiện trên menu.

Trang Đơn sàn, tab MARZI xử lý — Tab "MARZI xử lý": các phần đơn MARZI đang giữ.

Tab	Gồm
MARZI xử lý	Phần đơn của cửa hàng chưa ký (hoặc website không nhận đơn). Bạn xử lý: liên hệ cửa hàng hoặc tự đóng gói, rồi đổi trạng thái.
Đã gửi cho cửa hàng	Phần đơn đã sang website của cửa hàng. Trạng thái lấy từ website; MARZI không đổi ở đây.
Phí sàn	Bảng cộng dồn theo cửa hàng (mục 6).
Tài khoản nhận tiền	Mục 4.

Bấm Xem để mở chi tiết một phần đơn: người nhận, cách xử lý (và lý do nếu phần lẽ ra gửi cửa hàng mà ở lại MARZI), sản phẩm, phí sàn, tiến trình, và các nút chuyển trạng thái.

Chi tiết một phần đơn sàn — Chi tiết: người nhận, cách xử lý, sản phẩm, phí sàn, tiến trình và nút xử lý.

Các bước của phần MARZI giữ: Chờ xử lý → Đã xác nhận → Đang đóng gói → Đang giao → Đã giao; hủy được trước khi giao. Không nhảy cóc bước.
Chờ thanh toán: đơn trả bằng mã QR chưa có tiền. Chưa gửi cho ai. Nếu bạn đã thấy tiền trong ngân hàng mà SePay chưa báo, bấm Đã nhận tiền trong ngân hàng: các cửa hàng nhận phần của mình ngay. Bấm khi đơn không còn chờ tiền thì console báo "không có đơn nào chờ", không có gì thay đổi.
Hết hạn: đơn trả bằng QR quá 24 giờ không có tiền thì các phần tự hủy. Tiền chuyển muộn được ghi "Chưa khớp" ở bảng tiền vào của tài khoản sàn để bạn hoàn tiền hoặc tạo lại đơn.

Tab Đã gửi cho cửa hàng — Phần đã gửi cho cửa hàng: trạng thái do website của họ cập nhật.

6. Phí sàn và tiền phải trả cửa hàng

Bảng phí sàn theo cửa hàng — Bảng "Phí sàn" theo từng cửa hàng.

Cột	Là
Số đơn	Số phần đơn đã bán (không tính đơn hủy và đơn đang chờ thanh toán).
Gửi cửa hàng / MARZI giữ	Bao nhiêu phần đã sang website cửa hàng, bao nhiêu MARZI xử lý.
Tiền hàng	Tổng tiền hàng (không tính phí giao).
Phí sàn	Phí theo thỏa thuận trên tiền hàng. Với phần gửi website, tính trên tiền hàng website đã chốt (kể cả giảm giá riêng của website).
MARZI đã thu	Tiền khách đã chuyển khoản vào tài khoản của sàn cho các phần đó (tính cả phí giao).
Phải trả cửa hàng	Đã thu trừ phí sàn: số MARZI còn phải chuyển lại cho cửa hàng.

Đây là số cộng dồn, chưa phải đối soát

Chưa có chức năng ghi nhận "đã trả tiền cho cửa hàng", chưa chia theo kỳ và chưa xuất hóa đơn phí sàn. Hiện bạn dùng bảng này để đối chiếu với sao kê ngân hàng và ghi lại việc trả tiền ở nơi khác. Đơn thanh toán khi nhận hàng: tiền do bên giao thu, không nằm trong "MARZI đã thu".

7. Giữ tiền hộ cửa hàng

Với đơn chuyển khoản vào tài khoản của sàn, MARZI nhận tiền của khách rồi trả lại cho cửa hàng sau khi trừ phí sàn. Bạn đã cho biết sẽ dùng giấy phép của công ty của bạn cho việc này nên cách làm được giữ nguyên. Khi đã có hợp đồng với cửa hàng và trước khi bán rộng, nên nhờ luật sư hoặc kế toán xem lại: hóa đơn, thuế, hợp đồng với cửa hàng, và cách ghi nhận tiền giữ hộ. Cách thay thế nếu cần: khách trả thẳng vào tài khoản của cửa hàng và MARZI thu phí sau.

8. Trước khi chào hàng

Thử trọn một vòng với số tiền nhỏ: đặt một đơn trả bằng QR trên app sàn, chuyển đúng số tiền từ tài khoản của chính bạn, xem đơn chuyển sang "Chờ xác nhận" và phần của cửa hàng đã ký xuất hiện trên website của họ.
Quét thử mã QR bằng app của ít nhất hai ngân hàng khác nhau (mã dựng theo chuẩn VietQR của NAPAS; luôn kiểm tra bằng app ngân hàng thật).
SePay cần địa chỉ công khai: bật tự động xác nhận sau khi MARZI đã chạy trên máy chủ có tên miền HTTPS. Trước đó dùng nút "Đã nhận tiền trong ngân hàng".
Kiểm tra từng cửa hàng ký thỏa thuận: website nhận được đơn thử, đã có tài khoản nhận đơn, nhân viên cửa hàng thấy đơn trong app quản lý.
Dặn cửa hàng: đơn có ghi chú "ĐÃ THANH TOÁN qua MARZI, KHÔNG thu tiền khi giao" thì không thu tiền thêm của khách.

9. Giới hạn hiện tại

Chưa ghi nhận việc trả tiền cho cửa hàng và đối soát theo kỳ (mục 6).
Chưa thông báo cho bạn khi có đơn sàn mới (chỉ có số trên menu) hoặc giao dịch "Chưa khớp".
Khách chưa tự hủy hoặc đổi đơn trong app sàn; xử lý qua MARZI hoặc cửa hàng.
Cửa hàng không có website chưa nhận đơn sàn trong app quản lý.
Chưa có chỉ mục tìm kiếm chung: tìm kiếm hỏi trực tiếp tối đa 30 cửa hàng mới nhất, mỗi nơi 12 kết quả, kết quả nhớ 30 giây. Cần cải thiện khi có nhiều cửa hàng.

10. Liên hệ từ trang giới thiệu

Cuối trang giới thiệu có form "Sẵn sàng bán thêm app cho khách hàng của bạn?". Ai điền form, MARZI làm hai việc: lưu lại để bạn xem trong bảng điều khiển, và gửi một email báo về hộp thư bạn đã cài.

Xem và xử lý: menu Liên hệ (chỉ chủ hệ thống thấy; số trên menu là số liên hệ mới). Mỗi liên hệ có tên, điện thoại (bấm để gọi), email (bấm để trả lời), công ty, số website đang quản lý và lời nhắn. Bấm Đã liên hệ hoặc Đóng khi xong, và ghi chú lại nếu cần.
Dấu hiệu gửi email: mỗi liên hệ có thẻ Đã gửi mail báo, Gửi mail lỗi (rê chuột để xem lý do) hoặc Chưa cài mail. Email lỗi thì liên hệ vẫn được lưu, nên không mất khách; chỉ cần xem trong bảng điều khiển.
Cài hộp thư nhận: khai trong tệp services/api/.env của máy chủ (không đưa vào mã nguồn): SMTP_USER, SMTP_PASS (với Gmail là mật khẩu ứng dụng, không phải mật khẩu đăng nhập), tùy chọn SMTP_HOST (mặc định smtp.gmail.com), SMTP_PORT (mặc định 465), LEAD_NOTIFY_TO (mặc định gửi về chính SMTP_USER). Sửa xong khởi động lại máy chủ.
Chống spam: mỗi địa chỉ chỉ gửi được 5 lần mỗi phút (đổi bằng CONTACT_PER_MIN), form có ô ẩn để chặn chương trình tự điền, và nội dung được cắt gọn trước khi lưu.

Lưu ý

Hộp thư dùng để gửi chỉ cần là một tài khoản riêng cho việc này. Nếu mật khẩu ứng dụng bị lộ, vào tài khoản Google, thu hồi nó và tạo cái mới, rồi sửa lại SMTP_PASS.

11. Lượt truy cập trang

Menu Truy cập (chỉ chủ hệ thống thấy) cho biết có bao nhiêu người xem trang giới thiệu, tài liệu và các trang chính sách trong 7, 30, 90 hoặc 365 ngày: số lượt xem, số lượt người xem, biểu đồ theo ngày, trang được xem nhiều, họ đến từ trang web nào, ngôn ngữ và loại thiết bị.

Không dùng cookie và không lưu địa chỉ IP hay thông tin trình duyệt. Mỗi lượt xem chỉ ghi trang, ngôn ngữ, loại thiết bị và tên trang web đã dẫn tới. "Người xem" là một mã ẩn danh đổi mỗi ngày, nên cùng một người ở hai ngày được đếm hai lần (số lượt người xem là tổng theo từng ngày).
Không đếm chương trình tự động (công cụ tìm kiếm, theo dõi) và bỏ qua trình duyệt đã bật "Không theo dõi".
Số liệu giữ tối đa 400 ngày rồi tự xóa. Mỗi địa chỉ gửi tối đa 60 lượt mỗi phút (VISIT_PER_MIN).
Có số liệu này thì chính sách quyền riêng tư đã nói đúng như vậy; nếu thay đổi cách đếm, hãy sửa chính sách (mục 13).

12. Xóa tài khoản người mua theo yêu cầu

Người mua tự xóa tài khoản trong app (Tài khoản → Xóa tài khoản). Ai đã gỡ app thì gửi yêu cầu ở trang Xóa tài khoản của MARZI (địa chỉ ở mục 13); yêu cầu hiện trong menu Liên hệ với tiền tố [YÊU CẦU XÓA TÀI KHOẢN], kèm email của tài khoản và mã cửa hàng (hoặc "Chợ MARZI"), và cũng được báo qua email.

Xác nhận người gửi: trả lời vào đúng email đó (để không ai xóa nhầm tài khoản của người khác) và chờ người đó đồng ý.
Xóa: kéo xuống cuối trang Liên hệ, thẻ Xóa tài khoản người mua theo yêu cầu: chọn "Một cửa hàng" (nhập mã cửa hàng) hoặc "Chợ MARZI", nhập email, bấm Xóa tài khoản. Tài khoản và địa chỉ đã lưu bị xóa; đơn hàng cũ được giữ cho sổ sách của cửa hàng nhưng không còn gắn với tài khoản.
Báo lại cho người yêu cầu trong vòng 30 ngày (chính sách cam kết thời hạn này), rồi bấm Đã liên hệ ở yêu cầu.

Cửa hàng nối website: tài khoản người mua nằm ở website của cửa hàng nên MARZI không xóa được; công cụ báo rõ và bạn nhờ cửa hàng xóa trên website.
Mọi lần xóa ghi vào Nhật ký (địa chỉ email được che bớt).

13. Chính sách, điều khoản và ba ngôn ngữ

Trang giới thiệu có ba ngôn ngữ: tiếng Việt (/), English (/en/) và 한국어 (/ko/); mỗi ngôn ngữ có ba trang công khai dùng khi khai báo trên Google Play:

Trang	Địa chỉ (thay vi bằng en hoặc ko)
Chính sách quyền riêng tư	`/vi/privacy.html`
Điều khoản sử dụng	`/vi/terms.html`
Xóa tài khoản và dữ liệu (có form yêu cầu)	`/vi/delete-account.html`

Thông tin của đơn vị vận hành điền bằng biến môi trường khi dựng trang (cd apps/site, npm run build): SITE_LEGAL_NAME (tên pháp nhân hoặc cá nhân chịu trách nhiệm), SITE_LEGAL_ADDRESS, SITE_CONTACT_EMAIL, tùy chọn SITE_CONTACT_PHONE và SITE_BASE_URL (địa chỉ công khai, để công cụ tìm kiếm biết các bản ngôn ngữ). Chưa điền đủ thì các trang chính sách hiện khung "Bản nháp" và chỗ tên, địa chỉ ghi "chưa cập nhật": đừng đăng lên Play khi còn thấy khung này.
Nhờ luật sư xem ba trang này trước khi đăng (Nghị định 13/2023/NĐ-CP về bảo vệ dữ liệu cá nhân; thêm luật Hàn Quốc nếu có khách ở đó). Nội dung gốc ở apps/site/legal/vi.mjs, bản en và ko dịch từ đó; sau khi sửa, đổi ngày LEGAL_DATE trong apps/site/build.mjs.
Các cam kết trong chính sách mà người cài máy chủ phải làm đúng: nhật ký máy chủ (nginx, API) giữ tối đa 90 ngày; liên hệ từ trang giới thiệu giữ tối đa 24 tháng; thu phí hay dịch vụ nào mới dùng dữ liệu thì phải bổ sung vào chính sách.
Sửa trang giới thiệu tiếng Việt (apps/site/index.html) thì bản dựng báo lỗi và liệt kê đoạn chữ chưa có bản dịch: thêm vào apps/site/i18n/en.mjs và ko.mjs. Tên, mô tả của gói dịch vụ lấy từ trang Gói dịch vụ nên hiện nguyên như bạn đã gõ ở mọi ngôn ngữ; tên các chức năng trong gói thì được dịch.

14. Ảnh sản phẩm tải lên

Cửa hàng không có website tải ảnh lên bằng trang /shop/; ảnh lưu thành tệp trên máy chủ ở services/api/uploads (đổi bằng MEDIA_DIR) và được phát công khai ở /media/<cửa hàng>/<tên ảnh>. Sao lưu thư mục này cùng cơ sở dữ liệu, và để ngoài thư mục web.
Trang chỉ nhận JPG, PNG, WebP (kiểm bằng nội dung tệp, không tin tên tệp), tối đa 3 MB mỗi ảnh; mỗi cửa hàng tối đa 300 MB (MEDIA_QUOTA_MB). Một cửa hàng không dùng được ảnh của cửa hàng khác.
Khi triển khai nên đặt PUBLIC_BASE_URL (địa chỉ công khai của máy chủ) để địa chỉ ảnh trong app luôn cố định; không đặt thì máy chủ dùng địa chỉ mà người gọi đã dùng.
Ảnh không còn dùng (đã đổi ảnh khác) chưa tự xóa khỏi ổ đĩa; hạn mức 300 MB giữ cho thư mục không phình ra.

15. Trợ lý AI (chat)

MARZI nối với dịch vụ chat hani (ChatAPI v2) để có bốn trợ lý. Khóa của hani chỉ nằm ở máy chủ, app và trang web chỉ gọi MARZI.

Trợ lý	Ở đâu	Việc của nó
Người mua	Nút tròn trong app người mua	Bán hàng, tư vấn sản phẩm, giá, cách đặt hàng của cửa hàng đó (hiện cả thẻ sản phẩm)
App quản lý	Nút tròn trong app quản lý	Hỗ trợ chủ cửa hàng và nhân viên dùng app, thay mặt công ty/đại lý (biết tên và cách liên hệ của đại lý)
Bảng điều khiển	Nút tròn góc phải bảng điều khiển	Của MARZI: giải đáp và hướng dẫn dùng bảng điều khiển
Trang giới thiệu	Nút tròn ở trang giới thiệu (3 ngôn ngữ) và các trang hướng dẫn	Tư vấn trước khi mua, biết các gói đang bán

Tạo client trên hani (khuyên 4 client, mỗi loại một khóa), tắt tạo đơn hàng và thu thập lead trong cài đặt client (MARZI tự lo việc đó).
Dán vào services/api/.env: HANI_API_URL (ví dụ https://hani.io.vn/api) và khóa: HANI_API_KEY chung hoặc riêng HANI_KEY_SHOPPER, HANI_KEY_MERCHANT, HANI_KEY_CONSOLE, HANI_KEY_SITE. Khởi động lại máy chủ.
Menu "Trợ lý AI" (chủ hệ thống): bốn dòng phải hiện "Đã cài khóa". Công tắc bật/tắt từng loại cho cả hệ thống, và số câu đã trả lời 30 ngày.
Gói dịch vụ: bật ô Trợ lý AI ở gói muốn bán. Trợ lý trong app người mua và app quản lý chỉ chạy với cửa hàng của công ty có gói đó, và công ty/cửa hàng chưa tắt; trợ lý của bảng điều khiển và trang giới thiệu không cần cờ gói.

Tắt từng công ty: trang chi tiết công ty, thẻ Trợ lý AI của công ty. Tắt từng cửa hàng: thẻ Trợ lý AI trong trang sửa khách hàng (hiện lý do không chạy: đã tắt, gói chưa có AI, chưa cài dịch vụ chat).
Giới hạn: mỗi người tối đa 10 câu mỗi phút (AI_PER_MIN), mỗi cửa hàng tối đa 300 câu mỗi ngày (AI_TENANT_DAILY), trang giới thiệu 12 câu mỗi phút mỗi địa chỉ (AI_PUBLIC_PER_MIN). Hạn mức tin nhắn theo tháng nằm ở gói client trên hani: cho client người mua gói đủ lớn vì mọi cửa hàng dùng chung.
Cập nhật nội dung trợ lý biết: sửa services/api/src/modules/ai/knowledge.ts khi MARZI có tính năng mới. Chi tiết kỹ thuật: docs/TRO_LY_AI.md.
Câu hỏi của người dùng được gửi tới hani và giữ tối đa 12 tháng (chính sách quyền riêng tư đã ghi): đặt hani giữ đúng thời hạn đó.

Trợ lý có thể sai

App có dòng nhắc "Trợ lý AI có thể nhầm". Nếu một câu trả lời sai về giá hay chính sách, người dùng vẫn phải kiểm với cửa hàng; hãy xem lại hướng dẫn huấn luyện của client trên hani.