ZenithStore • Telegram Bot Demo B2B Gateway v1.2
Base URL:
https://api.haidangstore.com/api/v1
High-Speed RESTful Architecture • 100% White-Label Sanitized

Cổng B2B Open API ZenithStore • Telegram Bot Demo

Cung cấp giải pháp kết nối API B2B tự động tốc độ cao dành riêng cho các Đối Tác, Chủ Shop và Lập trình viên Bot Telegram. Xuất kho tức thì, tra cứu tồn kho theo thời gian thực và đồng bộ số dư ví tự động.

Sản phẩm sẵn có 18+ Kho hàng thực tế
Tốc độ xuất hàng < 1.2s Cấp tài khoản tức thì
Hỗ trợ kỹ thuật 24/7 @duchai1818
Bảo vệ nguồn hàng 100% White-Label

Giao Hàng Thời Gian Thực (Instant)

Tự động trả về dữ liệu tài khoản, key bản quyền hoặc link kích hoạt ngay trong phản hồi HTTP POST /buy mà không cần polling chờ đợi.

Khóa Kép ACID & Bảo Vệ Ví 100%

Cơ chế khóa giao dịch nguyên tử SQLite (BEGIN IMMEDIATE) và Idempotency bảo đảm đối tác không bao giờ bị trừ tiền trùng lặp hoặc mất tiền oan.

Định Dạng Sẵn Cho Bot Telegram

Trường formatted.telegram_caption được máy chủ tính toán và định dạng sẵn HTML Telegram, đại lý chỉ việc lấy và hiển thị thẳng cho khách hàng.

Xác Thực (Authentication & API Keys)

Mỗi đối tác B2B được cấp một khóa API duy nhất (định dạng hds_live_... hoặc sk_live_...). Cổng API hỗ trợ 3 hình thức truyền API Key:

Cách 1: Custom Header (Khuyên Dùng)
X-API-Key: hds_live_YOUR_KEY
Cách 2: Bearer Authorization
Authorization: Bearer hds_live_...
Cách 3: Query Parameter
?api_key=hds_live_YOUR_KEY
Nguyên tắc an toàn: Không bao giờ chia sẻ API Key công khai trên GitHub hoặc trong mã nguồn phía Client (HTML/JS phía trình duyệt). Nếu phát hiện bị lộ key, hãy liên hệ ngay Admin @duchai1818 để thu hồi và cấp key mới tức thì.

Cơ Chế Chống Trùng Lặp (Idempotency Key)

Khi mạng phía Bot đối tác bị timeout hoặc ngắt kết nối trong lúc gọi POST /api/v1/buy, đối tác hoàn toàn có thể an tâm gửi lại yêu cầu đó mà không sợ bị trừ tiền lần hai nhờ khóa định danh duy nhất:

Hỗ trợ 2 phương thức Idempotency: Thời gian ghi nhớ: 24 Giờ
  • 1. Header HTTP: X-Idempotency-Key: d9821f52-4712-4f3b-a9bb-f24b819f07a2
  • 2. JSON Body: "partner_order_ref": "BOT_BILL_10928" hoặc "request_id": "UUID_HERE"

💡 Nếu gửi lại request có cùng khóa này, máy chủ sẽ nhận diện và trả về nguyên trạng đơn hàng đã tạo trước đó cùng cờ "is_idempotent_replay": true mà không trừ thêm bất kỳ đồng nào trong ví!

Live API Explorer

Trình Thử Nghiệm API Trực Tiếp (Sandbox Console)

Kiểm tra kết nối và dữ liệu trả về ngay trên trình duyệt
Phản hồi HTTP: Chưa gửi request
{
  "message": "Chọn một endpoint và bấm 'Gửi Yêu Cầu' để xem phản hồi thời gian thực từ máy chủ..."
}
Self-Service Recovery Tool

Tra Cứu Đơn Hàng & Cấp Lại Dữ Liệu Khẩn Cấp

Dành cho đối tác khi Bot Telegram bị sập nguồn, mất log hoặc mất kết nối mạng. Bạn có thể tra cứu lại đơn hàng và lấy lại nguyên vẹn thông tin tài khoản/key đã mua bất kỳ lúc nào.

💡 Hỗ trợ tra cứu bằng cả mã đơn hệ thống lẫn mã tham chiếu phía đại lý.
REST API Reference

Chi Tiết Endpoints API v1

Đầy đủ 6 giao diện lập trình cốt lõi phục vụ trọn vẹn vòng đời tích hợp của đại lý.

GET /api/v1/balance

Tra cứu số dư ví B2B khả dụng, tiền tệ, trạng thái hoạt động và thông tin hạng thành viên (Tier) của đối tác.

Headers Bắt Buộc
X-API-Key: hds_live_YOUR_KEY
Query Parameters

Không có tham số bắt buộc.

Response 200 OK
{
  "status": "success",
  "data": {
    "partner_id": 1,
    "partner_name": "Reseller Bot A",
    "balance": 2500000,
    "formatted_balance": "2,500,000 đ",
    "currency": "VND",
    "status": "active"
  }
}
GET /api/v1/products

Lấy toàn bộ danh mục sản phẩm đang kinh doanh cùng tồn kho khả dụng, giá niêm yết bán lẻ, giá sỉ độc quyền riêng cho bạn, full mô tả chi tiết sản phẩm (description, description_en) để đấu vào bot/web có sẵn nội dung ngay, và chuỗi format Telegram dựng sẵn.

Query Parameters (Tùy chọn)
category_id int - Lọc theo ID danh mục sản phẩm
in_stock_only bool - `true` để chỉ lấy sản phẩm còn hàng
Tips dành cho Dev Bot Telegram & Web Reseller:

• Mô tả sản phẩm (product.description): Chứa toàn bộ thông số kỹ thuật, hạn dùng, đặc quyền gói và chính sách bảo hành chi tiết y hệt như trên bot chính. Bạn chỉ việc gắn trường này vào bot mà không cần tự nhập tay. Khi shop cập nhật mô tả, API sẽ tự động trả về mô tả mới nhất!

• Giá bán & Format (formatted.telegram_caption): Đã được hệ thống tạo sẵn mã HTML Telegram (<b>, <s>). Bạn chỉ cần truyền thẳng vào lệnh bot.send_message(parse_mode='HTML') mà không cần lập trình format lại giá!

Response 200 OK
{
  "code": 200,
  "status": "success",
  "ok": true,
  "total": 1,
  "products": [
    {
      "product_id": 15,
      "name": "Tài khoản Canva Pro 1 Năm",
      "category_name": "Thiết Kế & Đồ Họa",
      "retail_price": 200000,
      "wholesale_price": 140000,
      "discount_amount": 60000,
      "discount_percent": 30.0,
      "is_discounted": true,
      "pricing_rule": "custom_fixed",
      "formatted": {
        "retail_price": "200.000đ",
        "wholesale_price": "140.000đ",
        "discount_badge": "-30%",
        "promo_display": "200.000đ ➔ 140.000đ (Tiết kiệm 60.000đ)",
        "telegram_caption": "├ 💎 Giá niêm yết: 200.000đ\n├ 🏷️ Giá sỉ đại lý: 140.000đ (-30%)"
      },
      "stock_available": 42,
      "in_stock": true,
      "delivery_type": "instant",
      "description": "Gói tài khoản Canva Pro chính chủ thời hạn 1 năm full tính năng thiết kế cao cấp...",
      "description_en": "Canva Pro account 1 year full premium features..."
    }
  ]
}
GET /api/v1/products/:product_id

Tra cứu thông tin chi tiết của 1 sản phẩm cụ thể: bao gồm full mô tả sản phẩm (thông số gói, quyền lợi, bảo hành), hình thức phân phối, tồn kho khả dụng và giá sỉ riêng của đối tác.

Response 200 OK
{
  "code": 200,
  "status": "success",
  "ok": true,
  "product": {
    "product_id": 266,
    "product_slug": "apikey-claude-50m",
    "brand": "Anthropic Claude",
    "name": "API Claude | 50M Token | 2 Ngày",
    "category_name": "API & AI Models",
    "retail_price": 55000,
    "wholesale_price": 45000,
    "description": "Gói API Claude Sonnet & Opus hạn mức 50M Token thời hạn 2 ngày...",
    "stock_available": 10,
    "in_stock": true,
    "delivery_type": "instant"
  }
}
GET /api/v1/products/:product_id/stock

Endpoint kiểm tra tồn kho siêu nhẹ (Lightweight Stock Ping) phản hồi cực nhanh dưới 15ms. Bot đối tác nên gọi endpoint này ngay trước khi cho khách chuyển tiền để đảm bảo sản phẩm còn hàng.

Response 200 OK
{
  "code": 200,
  "status": "success",
  "ok": true,
  "product_id": 266,
  "stock_available": 10,
  "in_stock": true,
  "delivery_type": "instant"
}
POST /api/v1/buy

Tạo đơn đặt mua sản phẩm tự động. Hệ thống sẽ khóa giao dịch, trừ tiền ví B2B và trả về dữ liệu tài khoản/key bàn giao ngay lập tức.

JSON Body Parameters
product_id Tùy Chọn 1 ID sản phẩm dạng số nguyên (lấy từ GET /products, ví dụ: 265).
product_slug Tùy Chọn 2 (Khuyên Dùng) Mã định danh gói bằng chữ (ví dụ: "apikey-claude-10m"). Giúp bạn không bao giờ bị nhầm lẫn giữa các gói cùng giá như Claude và Codex. (Có thể gửi product_slug thay thế hoàn toàn cho product_id).
quantity Mặc định: 1 Số lượng cần mua
partner_order_ref Khuyên Dùng Mã đơn phía bot của bạn (dùng tra cứu lại)
customer_info Tùy chọn Email hoặc Telegram ID người nhận (cho đơn nâng cấp)
request_id Tùy chọn UUID chống gửi lệnh trùng lặp
is_test Tùy Chọn (Test Miễn Phí) Set true (hoặc truyền product_id: 0) để thử nghiệm API mua hàng 0 đồng. Hệ thống tạm giữ 1,000đ để kiểm tra số dư và tự động hoàn trả 100% về ví ngay lập tức sau khi test thành công.
Chế độ Thử Nghiệm API 0 Đồng (Zero-Cost Testing): Gọi POST /api/v1/buy kèm {"is_test": true} hoặc gọi POST /api/v1/test-order để test toàn diện quy trình thanh toán & nhận key mẫu mà không mất tiền.
Response 200 OK (Universal Delivery Format)
{
  "code": 200,
  "status": "COMPLETED",
  "ok": true,
  "order_code": "B2B-20261107133716-0670C8",
  "partner_order_ref": "BOT_BILL_98124",
  "product_id": 345,
  "product_name": "Tài khoản Gemini Pro Pixel 24 Tháng ( bh 24h )",
  "quantity": 1,
  "data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "account": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "accounts": [
    "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
  ],
  "items": [
    "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
  ],
  "delivered_data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "delivered_items": [
    {
      "account": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
      "account_data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
    }
  ],
  "instructions": "",
  "created_at": "2026-11-07 13:37:17"
}
Bảo mật White-label 100%: Toàn bộ body đơn hàng tuyệt đối không chứa giá sỉ hay số dư ví để tránh lộ bí mật kinh doanh khi bot đại lý gửi kết quả cho khách. Số dư ví còn lại được chuyển an toàn qua HTTP Header X-Partner-Remaining-Balance hoặc tra cứu qua GET /api/v1/balance.
GET /api/v1/orders/:order_code

Tra cứu trạng thái, dữ liệu tài khoản đã cấp phát của đơn hàng. Bạn có thể truyền mã đơn B2B-... hoặc mã đơn đối tác partner_order_ref.

Response 200 OK
{
  "code": 200,
  "status": "success",
  "ok": true,
  "order_code": "B2B-20261107133716-0670C8",
  "product_id": 345,
  "product_name": "Tài khoản Gemini Pro Pixel 24 Tháng ( bh 24h )",
  "quantity": 1,
  "data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "account": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "accounts": [
    "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
  ],
  "items": [
    "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
  ],
  "delivered_data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
  "delivered_items": [
    {
      "account": "user@gmail.com | Password123# | 2faa eksm nb2a buq2...",
      "account_data": "user@gmail.com | Password123# | 2faa eksm nb2a buq2..."
    }
  ],
  "partner_order_ref": "BOT_BILL_98124",
  "created_at": "2026-11-07 13:37:17"
}
GET /api/v1/restock-feed HOT FOR RESELLER BOT

Giải pháp tự động hóa dành riêng cho Bot & Kênh Telegram của Đại Lý: Bạn không cần tự viết hệ thống theo dõi kho phức tạp hay chạy vòng lặp so sánh tồn kho cũ - mới. Chỉ cần gọi endpoint này, máy chủ sẽ trả về danh sách các mặt hàng vừa mới nhập kho, kèm theo chuỗi formatted.telegram_message đã định dạng sẵn HTML Telegram cực đẹp.

💡 Bot của đại lý chỉ việc lấy nguyên văn trường formatted.telegram_message và bắn thẳng vào Kênh/Group Telegram của mình!

Query Parameters (Tùy chọn)
since_id int - Chỉ lấy các sự kiện có event_id > since_id (Giúp bot không đăng trùng tin cũ)
since_timestamp int - Chỉ lấy tin sau Unix timestamp này
limit int - Số tin tối đa (Mặc định: 20, Max: 100)
category_id int - Lọc riêng theo danh mục
Tùy chọn Webhook Push (Tức thì 0 giây):

Nếu bạn có máy chủ riêng muốn nhận tin tức thì mà không cần polling, hãy gọi POST /api/v1/partner/webhook với payload {"webhook_url": "https://your-bot.com/webhook"}. Kho tổng vừa nhập hàng là máy chủ sẽ bắn event ngay lập tức!

Response 200 OK
{
  "code": 200,
  "status": "success",
  "ok": true,
  "total": 1,
  "last_event_id": 42,
  "items": [
    {
      "event_id": 42,
      "product_id": 266,
      "product_name": "Nâng cấp chính chủ Gemini Pro Pixel 12 Tháng",
      "category_name": "Google Services",
      "retail_price": 40000,
      "wholesale_price": 32000,
      "added_qty": 50,
      "current_stock": 50,
      "delivery_type": "instant",
      "restocked_at": "2026-11-07 15:40:00",
      "restocked_timestamp": 1794040800,
      "formatted": {
        "retail_price": "40.000đ",
        "wholesale_price": "32.000đ",
        "telegram_message": "HÀNG MỚI VỀ!\n\n1️⃣ Nâng cấp chính chủ Gemini Pro Pixel 12 Tháng\n💎 Giá: 40.000đ\n⚙️ Hình thức: Dịch vụ tự động\n📦 Vừa nhập: +50 (Hiện có: 50)\n⚡ Liên hệ ngay hoặc đặt mua qua Bot để được phục vụ cấp tốc!"
      }
    }
  ]
}
Code Mẫu Bot Telegram Tự Động Bắn Tin Vào Kênh (Chỉ 15 Dòng Python!):
import time, requests

API_KEY = "hds_live_YOUR_KEY_HERE"
CHANNEL_ID = "@kenh_shop_cua_ban"       # Kênh Telegram của đại lý
BOT_TOKEN = "123456789:AAEF..."          # Token Bot tạo từ @BotFather
last_event_id = 0

print("🚀 Bot tự động quét hàng mới đang chạy...")
while True:
    try:
        # 1. Gọi API lấy danh sách hàng mới vừa nhập
        resp = requests.get(
            "https://api.haidangstore.com/api/v1/restock-feed",
            headers={"X-API-Key": API_KEY},
            params={"since_id": last_event_id, "limit": 10},
            timeout=10
        ).json()

        for item in reversed(resp.get("items", [])):
            # 2. Lấy nguyên văn chuỗi tin nhắn đã format sẵn chuẩn HTML
            tg_text = item["formatted"]["telegram_message"]
            
            # 3. Bắn thẳng lên Kênh Telegram của bạn!
            requests.post(
                f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
                json={"chat_id": CHANNEL_ID, "text": tg_text, "parse_mode": "HTML"},
                timeout=10
            )
            print(f"✅ Đã đăng bài: {item['product_name']}")
            last_event_id = max(last_event_id, item["event_id"])
            
    except Exception as e:
        print(f"Lỗi kết nối: {e}")
        
    time.sleep(60) # Tự động quét 1 phút/lần
Dedicated Support

Trung Tâm Hỗ Trợ 24/7 & Nạp Ví Đại Lý

Đội ngũ kỹ thuật túc trực 24/7 cam kết hỗ trợ tối đa cho các đối tác tích hợp hệ thống.

Kênh Kỹ Thuật Trực Tuyến 24/7

Đang Online • Phản hồi 5-15 phút

Hỗ trợ cấp mới API Key, kiểm tra đơn hàng, hỗ trợ debug mã nguồn bot, nâng hạn mức gọi API và thiết lập mức giá sỉ riêng cho từng danh mục.

Nạp Số Dư Ví B2B Tự Động

Tự động cộng tiền ví sau 10-30 giây

Ngân Hàng (24/7): VPBank - 9999918181010
Binance Pay ID: 981865782
USDT (BEP20 BSC): 0xc0b08E5416BB0B14bED20284FEd40928cEea8a06

ℹ️ Sau khi chuyển khoản, quý khách nhắn tin tới Admin kèm biên lai để cộng số dư ví ngay lập tức hoặc nạp tự động qua Bot Telegram của shop.

Bảng Phân Hạng Đối Tác & Mức Chiết Khấu Sỉ

Standard Reseller Giá Sỉ Chuẩn

Áp dụng cho mọi đối tác mới tích hợp bot hoặc web.

Silver Partner -3% đến -5% Thêm

Doanh số đạt từ 5.000.000đ/tháng.

Gold Partner -5% đến -10% Thêm

Doanh số đạt từ 15.000.000đ/tháng.

Diamond VIP Giá Sỉ Thỏa Thuận

Hỗ trợ giá sỉ riêng cho từng danh mục, ưu tiên cấp hàng độc quyền.

Bảng Mã Lỗi Chuẩn (HTTP Status & Error Codes)

Tất cả phản hồi lỗi đều tuân thủ định dạng JSON đồng nhất kèm mã lỗi máy tính dễ parse:

Status Code Error Code Ý nghĩa & Hành động đề xuất cho Bot
400 Bad Request INVALID_REQUEST Thiếu tham số bắt buộc hoặc định dạng JSON không hợp lệ. Kiểm tra lại payload gửi lên.
401 Unauthorized UNAUTHORIZED Khóa API không đúng hoặc đối tác đang bị tạm khóa. Liên hệ Admin để mở lại.
402 Payment Required INSUFFICIENT_BALANCE Số dư ví B2B không đủ để hoàn tất đơn hàng. Bot cần thông báo nạp thêm tiền.
404 Not Found PRODUCT_NOT_FOUND Không tìm thấy sản phẩm hoặc đơn hàng tương ứng với ID/mã cung cấp.
409 Conflict OUT_OF_STOCK Sản phẩm hiện đang tạm hết hàng trong kho. Chờ restock hoặc liên hệ Admin.
429 Too Many Requests RATE_LIMIT_EXCEEDED Vượt quá 60 requests/phút. Bot nên giãn cách delay và cache danh sách sản phẩm.
503 Service Unavailable PRODUCT_TEMPORARILY_UNAVAILABLE Sản phẩm tạm thời gián đoạn xuất hàng. Số dư ví của bạn được bảo lưu 100% nguyên vẹn.
Developer Guide & FAQ

Cẩm Nang Lập Trình & Câu Hỏi Thường Gặp

Những kinh nghiệm thực tế giúp bot Telegram của bạn chạy ổn định 24/7 mà không gặp lỗi.

Tôi nên cache danh sách sản phẩm như thế nào?

Bạn nên gọi GET /products định kỳ 5-10 phút một lần và lưu vào RAM của bot thay vì gọi liên tục mỗi khi khách bấm menu. Khi khách chuẩn bị thanh toán, chỉ cần gọi nhanh GET /products/:id/stock để xác nhận còn hàng.

Xử lý thế nào khi bot gọi mua hàng bị timeout mạng?

Luôn luôn truyền tham số partner_order_ref (mã đơn bot tự sinh). Nếu gặp timeout mạng, bot có thể an tâm gọi lại lệnh POST /buy với cùng mã đó hoặc gọi GET /orders/:code để kiểm tra. Hệ thống bảo đảm không trừ tiền 2 lần.

Nếu gặp lỗi 503 thì số dư ví có bị trừ không?

Tuyệt đối không! Mọi giao dịch đặt mua đều chạy trong transaction khóa kép ACID. Nếu không thể bàn giao dữ liệu thành công, toàn bộ giao dịch bị hủy bỏ (Rollback) và số dư ví của quý khách được bảo lưu 100% nguyên vẹn.

Làm thế nào để đăng ký cấp API Key đối tác?

Quý khách chỉ cần nhắn tin trực tiếp cho Admin Telegram @duchai1818, thông báo tên Bot/Shop và số Telegram ID, chúng tôi sẽ cấp ngay API Key bí mật và cấu hình bảng giá sỉ trong 5 phút.

Mã Nguồn Mẫu Đa Ngôn Ngữ (SDK Integration Kit)

Chọn ngôn ngữ bạn đang lập trình để xem mã nguồn mẫu sẵn sàng copy-paste:

# 1. Tra cứu số dư ví B2B
curl -X GET "https://api.haidangstore.com/api/v1/balance" \
     -H "X-API-Key: hds_live_YOUR_KEY_HERE"

# 2. Lấy danh sách sản phẩm & giá sỉ
curl -X GET "https://api.haidangstore.com/api/v1/products" \
     -H "X-API-Key: hds_live_YOUR_KEY_HERE"

# 3. Kiểm tra tồn kho thời gian thực
curl -X GET "https://api.haidangstore.com/api/v1/products/266/stock" \
     -H "X-API-Key: hds_live_YOUR_KEY_HERE"

# 4. Đặt mua hàng tự động
curl -X POST "https://api.haidangstore.com/api/v1/buy" \
     -H "X-API-Key: hds_live_YOUR_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{
       "product_id": 266,
       "quantity": 1,
       "partner_order_ref": "ORDER_TELEGRAM_1002"
     }'
Đã sao chép vào bộ nhớ tạm!