Chonj Open API & Widget nhúng

Bắt đầu trong 3 bước

1️⃣
Đăng ký đối tác
Dùng chính tài khoản Chonj.vn của bạn (tài khoản nhà tài trợ cũng được).
2️⃣
Tạo API key
Publishable cho widget trên trình duyệt, Secret cho máy chủ.
3️⃣
Dán mã nhúng / gọi API
Lấy mã nhúng có xem trước ngay trong bảng điều khiển.

🎡 Widget vòng quay nhúng

Dán đoạn mã sau vào nơi muốn hiện vòng quay. Widget tự lấy màu theo mùa của Chonj.vn, chạy trong Shadow DOM nên không ảnh hưởng CSS của trang bạn, nhẹ và không cần thư viện nào.

<div data-chonj-widget data-key="chj_pub_xxxxxxxx" data-tab="an-gi"></div>
<script src="https://api.chonj.vn/widget/v1.js" async></script>

Thuộc tính	Giá trị	Ý nghĩa
data-key	chj_pub_…	Publishable key (bắt buộc). Chỉ chạy trên tên miền bạn đã đăng ký.
data-tab	an-gi \| uong-gi \| nau-gi \| di-dau \| du-lich \| tang-gi	Danh mục của vòng quay.
data-size	compact \| full	Gọn (360px) hoặc rộng (640px).
data-theme	auto \| light \| dark	`auto`: màu & ruy băng theo mùa (Tết, Trung Thu, Giáng sinh…) của Chonj.vn.
data-color	#ff6b00	Màu thương hiệu riêng của bạn.
data-locale	vi \| en	Ngôn ngữ của widget.
data-city	Hà Nội	Tỉnh / thành của khách: hiện chi nhánh tài trợ gần đó (nếu có).

Không chèn được script? Dùng iframe

Cho Blogger và các CMS chặn thẻ <script>:

<iframe src="https://api.chonj.vn/embed/spin?key=chj_pub_xxxxxxxx&tab=an-gi" title="Chonj.vn" loading="lazy" style="width:100%;max-width:420px;height:560px;border:0;border-radius:20px"></iframe>

⚙️ REST API

Địa chỉ gốc:

https://api.chonj.vn/api/v1

Gửi key qua header Authorization: Bearer <key> (hoặc X-Chonj-Key). Dữ liệu trả về dạng JSON { "data": …, "meta": … }; thêm ?locale=en để nhận tiếng Anh. Secret key không bao giờ được đặt trên URL hay trong mã chạy trên trình duyệt.

Endpoint	Quyền	Mô tả
GET /categories	read	Danh mục (Ăn gì, Uống gì, Nấu gì…) kèm bộ lọc được hỗ trợ.
GET /items	read	Danh sách món, phân trang. Lọc: `category, q, dish_type, cuisine, drink_type, meal_type, recipient, occasion, gift_budget, group, price_min, price_max`; `per_page` (≤ 50), `page`, `sort=id\|title\|random`.
GET /items/{id}	read	Chi tiết một món (id công khai, ví dụ `k3x9ab`).
POST /spin	spin	Quay ngẫu nhiên có trọng số: `category` (bắt buộc) + các bộ lọc trên, `exclude` (id đã ra), `city`.
GET /theme	read	Giao diện theo mùa đang dùng (màu, ruy băng).
GET /ping	—	Kiểm tra kết nối, không cần key.

Ví dụ

curl -X POST https://api.chonj.vn/api/v1/spin \
  -H "Authorization: Bearer chj_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"category":"an-gi","price_max":60000}'

const res = await fetch('https://api.chonj.vn/api/v1/items?category=an-gi&per_page=10', {
  headers: { Authorization: 'Bearer ' + process.env.CHONJ_SECRET_KEY },
});
const { data, meta } = await res.json();

{
    "data": {
        "id": "k3x9ab",
        "title": "Phở bò",
        "image": "https://…",
        "price": {
            "min": 45000,
            "max": 65000,
            "label": "Từ 45.000đ - 65.000đ",
            "currency": "VND"
        },
        "category": {
            "slug": "an-gi",
            "name": "Ăn gì?",
            "icon": "🍜"
        },
        "maps_url": "https://www.google.com/maps/search/…",
        "url": "https://chonj.vn/?tab=an-gi&q=…",
        "sponsored": false,
        "sponsor": null
    },
    "meta": {
        "plan": "free",
        "branding": {
            "powered_by": true,
            "text": "Powered by Chonj.vn",
            "url": "https://chonj.vn/…"
        },
        "locale": "vi",
        "pool_size": 84
    }
}

Mã lỗi

401	missing_key, invalid_key, key_revoked, key_expired, secret_key_in_url
403	client_inactive (đối tác chưa kích hoạt / tạm khóa), insufficient_scope, domain_not_allowed
404	unknown_category, item_not_found, no_items, not_found
422	invalid_request (kèm "fields")
429	rate_limited (quá số lượt/phút), quota_exceeded (hết lượt trong ngày); xem header Retry-After
503	api_disabled (Open API đang tạm tắt)

Mỗi phản hồi có header X-RateLimit-Limit, X-RateLimit-Remaining và (gói có hạn mức ngày) X-Quota-Limit, X-Quota-Remaining.

📦 Các gói API

Free

Miễn phí

⚡ 60 lượt gọi / phút
📊 5.000 lượt/ngày
🔑 2 key · 🌐 3 tên miền
🏷️ Hiện "Powered by Chonj.vn"
📣 Có chen món tài trợ

Partner

Miễn phí

⚡ 300 lượt gọi / phút
📊 50.000 lượt/ngày
🔑 5 key · 🌐 10 tên miền
🏷️ Hiện "Powered by Chonj.vn"
🚫 Không quảng cáo

Premium

Miễn phí

⚡ 1.000 lượt gọi / phút
📊 Không giới hạn
🔑 20 key · 🌐 50 tên miền
✨ Ẩn "Powered by"
🚫 Không quảng cáo

Gói tài trợ của nhà tài trợ có thể đã kèm sẵn gói API cao hơn. Muốn nâng gói? Liên hệ Chonj.vn qua trang Hỗ trợ.

📜 Điều khoản ngắn gọn

Gói có "Powered by Chonj.vn" phải giữ dòng này cùng liên kết về Chonj.vn.
Món "Tài trợ" luôn được gắn nhãn rõ ràng, không được che hoặc đổi nhãn.
Không lưu trữ lại toàn bộ dữ liệu Chonj.vn để dựng dịch vụ cạnh tranh; dữ liệu được làm mới liên tục qua API.
Key bị lộ: thu hồi ngay trong bảng điều khiển và tạo key mới.

⚖️ Đọc đầy đủ Điều khoản sử dụng API