Gian hàng trên mã của riêng bạn (headless)

Cách thông thường là gian hàng của chúng tôi hoặc các widget trên trang web của bạn. Nhưng nếu trang web do nhà phát triển hoặc agency của bạn viết và phần giao diện phải hoàn toàn của riêng bạn, thì có phương án thứ ba: bạn nhận từ chúng tôi dữ liệu và việc tiếp nhận đơn hàng, còn toàn bộ frontend bạn tự làm, trên bất kỳ stack nào.

Việc đọc dữ liệu không cần khóa và không cần xác thực: mọi thứ công khai trên gian hàng đều công khai trong JSON.

Nơi cấu hình: Marketing → «Trang web của tôi» → thẻ «Gian hàng trên mã của riêng bạn». Tại đó cũng có địa chỉ manifest của chi nhánh bạn, liên kết đến tài liệu kỹ thuật và các JSON schema, cùng cấu hình webhook. Không cần bật gì cả: dữ liệu luôn được công bố.

Manifest storefront.json#

Địa chỉ duy nhất mà nhà phát triển cần biết:

https://cdn.cenaly.com/{ДОМЕН}/storefront.json

Trong manifest có mọi thứ còn lại:

Hợp đồng được đánh phiên bản (contractVersion), và bên cạnh là các JSON schema — dùng chúng để xác thực dữ liệu và sinh kiểu. Các trường không xác định cần bỏ qua: hợp đồng mở rộng mà không phá vỡ tương thích.

Dữ liệu và hình ảnh#

Mọi thứ gian hàng hiển thị đều có sẵn dưới dạng tệp: menu và danh mục theo ngôn ngữ, hồ sơ chi nhánh (tên, địa chỉ, giờ làm việc, liên hệ, cài đặt), trang và bài viết, bộ sưu tập, đánh giá.

Với danh mục lớn, manifest chuyển sang chế độ api: trong tệp menu có bản trích lược nhẹ, còn thẻ đầy đủ được lấy theo từng tệp hoặc qua API danh mục với bộ lọc và danh mục con.

Hình ảnh — từ CDN của chúng tôi, ở nhiều kích thước theo mẫu trong manifest; khi ảnh được cập nhật, đường dẫn được đánh phiên bản, nên có thể giữ cache «mãi mãi».

Không nhất thiết phải viết tay tất cả các yêu cầu này: có gói npm @cenaly/storefront — client có kiểu của hợp đồng (manifest, hồ sơ, menu của cả hai chế độ danh mục, tạo đơn hàng), trình tạo URL hình ảnh và các React hook. Gói có một điểm vào riêng cho bản dựng tĩnh (@cenaly/storefront/static: bản đồ địa chỉ trang web, sitemap.xml, robots.txt, liên kết hình ảnh) và lệnh console cenaly-storefront — chụp toàn bộ dữ liệu chi nhánh vào một thư mục, liệt kê địa chỉ và chế độ watch, theo dõi manifest và chạy bản dựng của bạn ngay khi publishId thay đổi. Nó cũng là nền tảng của dự án khởi đầu trên Next.js, có thể clone về và chỉ việc đổi màu.

Đơn hàng và API khách#

Tiếp nhận đơn hàng, trạng thái đơn hàng, tìm kiếm và đặt bàn — qua API khách: không cần xác thực, địa chỉ lấy từ manifest, đặc tả là OpenAPI 3.1. Riêng có luồng thương mại: mã giảm giá, tính phí giao hàng, biểu mẫu, đăng ký. Chi tiết — Guest API cho AI agent, cùng một giao diện.

Đơn hàng do trang web của bạn tạo ra sẽ vào mục chung «Đơn hàng» và vận hành theo các quy tắc thông thường: trạng thái, bếp, shipper, biên lai, thông báo.

Webhook về các thay đổi#

Để không phải liên tục hỏi CDN, hãy đăng ký nhận sự kiện:

• menu.updated — menu hoặc danh mục được tạo lại;
• profile.updated — hồ sơ chi nhánh thay đổi;
• pages.updated — trang và bài viết thay đổi.

Trong nội dung sự kiện có publishId — dùng nó để dựng lại các trang tĩnh hoặc xóa cache ISR. Nếu bạn đặt secret, yêu cầu được ký bằng HMAC-SHA256 và đến với header X-Meni-Signature — hãy kiểm tra chữ ký trước khi dựng lại bất cứ thứ gì; với deploy hook của Vercel/Netlify có thể không cần đặt secret. Tối đa năm địa chỉ cho mỗi chi nhánh, và sau mười lần thất bại liên tiếp, đăng ký tự động bị tắt (trong tài khoản có thể thấy lần gửi gần nhất và bộ đếm lỗi; lưu lại cài đặt sẽ bật lại).

Địa chỉ nào máy chủ sẽ chấp nhận. Chỉ https://, không có login và mật khẩu trong chính URL, và host bắt buộc phải công khai: các địa chỉ cục bộ, nội bộ và nội bộ hệ thống (localhost, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, 100.64.0.0/10, 169.254.169.254) bị từ chối khi lưu. Để gỡ lỗi trên máy của bạn, hãy dựng một tunnel với địa chỉ https công khai.

Khi nào có gửi lại. Các lần timeout và phản hồi 5xx, 408, 429 được gửi lại — tức là những gì giống như sự cố tạm thời. Mọi phản hồi 4xx khác được coi là lỗi vĩnh viễn: sẽ không gửi lại, lần thử đó ngay lập tức được tính vào bộ đếm thất bại.

Webhook được cấu hình trong thẻ «Gian hàng trên mã của riêng bạn» và khả dụng trên các gói trả phí; việc đọc dữ liệu luôn khả dụng.

Bắt đầu từ đâu#

1. Mở Marketing → «Trang web của tôi» → «Gian hàng trên mã của riêng bạn» và sao chép địa chỉ manifest.
2. Tải manifest và từ đó — dữ liệu menu và hồ sơ (hoặc cài gói @cenaly/storefront và truyền cho nó slug chi nhánh). Bước này không cần khóa nào cả.
3. Dựng các trang bằng framework của bạn; với đơn hàng, dùng API khách.
4. Thêm webhook để dựng lại trang web khi có thay đổi — hoặc, nếu không có địa chỉ công khai để nhận sự kiện, hãy chạy cenaly-storefront watch: nó tự theo dõi publishId trong manifest và chạy bản dựng của bạn.

Mô tả kỹ thuật đầy đủ — theo liên kết «Tài liệu nhà phát triển» trong cùng thẻ đó; bên cạnh là liên kết đến hướng dẫn riêng về trang tĩnh và đến các JSON schema. Có sẵn dự án khởi đầu trên Next.js, và toàn bộ tài liệu được nhân bản dưới dạng llms.txt cho các trợ lý AI của nhà phát triển — bao gồm cả llms.txt riêng của chi nhánh bạn trên CDN.

Các mục liên quan#

• Trang web của tôi — các widget, nếu không cần viết lại toàn bộ trang web
• Guest API cho AI agent — cùng một guest API
• API và MCP của tổng đài riêng — quyền truy cập của AI agent và CRM vào hệ thống điện thoại
• Cửa hàng trực tuyến — dữ liệu danh mục mang đến chính xác những gì

Câu hỏi thường gặp#

Có phải trả tiền để đọc dữ liệu không? Không. JSON công khai khả dụng ở mọi Gói — đó chính là những tệp mà cửa hàng của chúng tôi sử dụng. Dịch vụ tính phí là webhook.

Còn SEO thì sao? Hoàn toàn do bạn quyết định: bạn tự tạo trang và tự quản lý phần đánh dấu. Dữ liệu cho microdata (JSON-LD) có trong hợp đồng.

Có thể kết hợp với cửa hàng riêng của mình không? Có. Cửa hàng của chúng tôi, các widget và trang web riêng của bạn hoạt động với cùng một dữ liệu và cùng một giỏ Đơn hàng.