Giới thiệu chung

Hệ thống B2B API của Shop MMO Uy Tin cung cấp cơ chế bảo vệ giao dịch chống trừ tiền kép (double-spend), bảo vệ tính toàn vẹn tài chính cho đối tác qua khóa Idempotency và quy trình xử lý lỗi fail-closed.

• Kết nối trực tiếp: Lấy danh mục, kiểm tra tồn kho, đặt hàng và nhận tài khoản khi hoàn tất qua API.
• Bảo vệ dòng tiền: Tất cả giao dịch tài chính sử dụng đơn vị số nguyên VND (integer) không phát sinh lỗi số thực (float).
• Giao dịch bất biến (Idempotency): Gửi lại request khi gặp sự cố mạng (timeout) mà không sợ bị trừ tiền lần hai.

Chu kỳ đối tác & Cấp khóa an toàn

Tài khoản đối tác được quản lý nghiêm ngặt qua 4 trạng thái chu kỳ hoạt động:

• 1. Pending (Chờ duyệt): Đối tác mới đăng ký, chưa được cấp quyền gọi API (mọi lệnh gọi trả về 403 Forbidden).
• 2. Active (Hoạt động): Đã được Quản trị viên duyệt, có khóa API hoạt động và hạn mức giao dịch hợp lệ.
• 3. Suspended (Tạm dừng): Tài khoản bị tạm ngưng giao dịch theo lệnh quản trị hoặc phát hiện bất thường.
• 4. Revoked (Đã thu hồi): Khóa API bị hủy vĩnh viễn, không thể tiếp tục gọi hệ thống.

Quy chuẩn Header xác thực API

Chế độ hoạt động API & Giới hạn tần suất

Hệ thống B2B vận hành theo 3 chế độ được kiểm soát bởi Quản trị viên:

Bảng phân quyền trạng thái hệ thống

Giới hạn tần suất gửi yêu cầu (Rate Limits)

Hệ thống áp dụng giới hạn tần suất cơ bản theo địa chỉ IP để chống brute-force và bảo vệ hạ tầng. Ngoài ra, mỗi đối tác được cấu hình giới hạn max_requests_per_minute và hạn mức số tiền giao dịch trong ngày do Admin thiết lập.

1. Kiểm tra số dư ví đại lý

Truy vấn số dư ví hiện tại của đối tác. Hỗ trợ bí danh tương thích /api/wallet/balance.

curl -X GET "https://api.uytinnhat.com/api/balance" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "user_id": 990001,
  "username": "partner_demo",
  "balance_vnd": 500000,
  "balance": 500000,
  "wallet_balance": 500000
}

2. Danh sách sản phẩm khả dụng

Truy xuất danh sách tất cả các sản phẩm đang mở bán trên hệ thống. Hỗ trợ cả 2 bí danh id và product_id.

curl -X GET "https://api.uytinnhat.com/api/products" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "count": 2,
  "products": [
    {
      "id": "demo_product_01",
      "product_id": "demo_product_01",
      "name": "Demo Subscription Account (Synthetic)",
      "price_vnd": 65000,
      "price": 65000,
      "stock": 42,
      "description": "Synthetic demonstration account fixture."
    },
    {
      "id": "demo_product_02",
      "product_id": "demo_product_02",
      "name": "Demo Pro License (Synthetic)",
      "price_vnd": 120000,
      "price": 120000,
      "stock": 15,
      "description": "Synthetic software key license fixture."
    }
  ]
}

3. Chi tiết sản phẩm theo mã

Lấy thông tin chi tiết, mô tả và tồn kho của một sản phẩm cụ thể bằng mã sản phẩm. Đối tượng trả về chứa cả 2 bí danh id và product_id.

curl -X GET "https://api.uytinnhat.com/api/products/demo_product_01" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "product": {
    "id": "demo_product_01",
    "product_id": "demo_product_01",
    "name": "Demo Subscription Account (Synthetic)",
    "price_vnd": 65000,
    "stock": 42,
    "description": "Synthetic demonstration account fixture with full warranty."
  }
}

4. Đặt mua tài khoản B2B (Có Idempotency)

Thực hiện mua tài khoản bằng số dư ví. Hỗ trợ bí danh tương thích POST /api/orders. Khóa công khai chỉ chấp nhận trường product_id trong body.

Kết quả xử lý đơn hàng: Phản hồi 200 OK khi hoàn tất giao hàng và thông tin tài khoản được cấp trong mảng items. Trong trường hợp cần đối soát hoặc nhà cung cấp xử lý dở, hệ thống trả về 202 Accepted với items rỗng (đơn hàng ở trạng thái xử lý). Khi lỗi (hết hàng, thiếu số dư...), hệ thống trả về mã lỗi thích hợp.

Cơ chế Replay cùng Key: Gửi lại request với cùng X-Idempotency-Key và cùng payload sẽ trả về kết quả giao dịch ban đầu kèm tài khoản đã cấp (nếu có) và trường "idempotent_replay": true, bảo đảm số dư ví không bị trừ thêm lần 2.

curl -X POST "https://api.uytinnhat.com/api/buy" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: unique-order-key-sample-001" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "demo_product_01", "quantity": 1}'

{
  "success": true,
  "order_code": 1717382912345,
  "order_id": 1717382912345,
  "product_id": "demo_product_01",
  "product_name": "Demo Subscription Account (Synthetic)",
  "quantity": 1,
  "total": 65000,
  "status": "completed",
  "items": [
    "user_demo@example.invalid|DEMO_CREDENTIAL_NOT_REAL"
  ],
  "new_balance": 435000
}

5. Tra cứu đơn hàng & Lấy lại tài khoản

Tra cứu lại thông tin đơn hàng đã mua và lấy lại danh sách tài khoản được cấp. Hỗ trợ lấy toàn bộ danh sách đơn qua GET /api/orders.

curl -X GET "https://api.uytinnhat.com/api/orders/1717382912345" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "order": {
    "order_code": 1717382912345,
    "product_id": "demo_product_01",
    "product_name": "Demo Subscription Account (Synthetic)",
    "quantity": 1,
    "total": 65000,
    "status": "completed",
    "items": [
      "user_demo@example.invalid|DEMO_CREDENTIAL_NOT_REAL"
    ],
    "created_at": "2026-09-11 12:00:00"
  }
}

6. Tạo link nạp tiền ví tự động (VietQR)

Khởi tạo giao dịch nạp tiền vào ví đại lý. Hệ thống sinh mã thanh toán VietQR và nội dung chuyển khoản tự động. Hỗ trợ bí danh tương thích POST /api/wallet/topup.

curl -X POST "https://api.uytinnhat.com/api/deposit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: unique-deposit-key-sample-001" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000}'

{
  "success": true,
  "order_code": 1717382999999,
  "amount": 500000,
  "payment_code": "DH1717382999999",
  "payment_url": "https://example.invalid/payment/demo_gateway_session",
  "qr_url": "https://example.invalid/qr/synthetic_qr_demo.png",
  "bank_info": {
    "bank_name": "DEMO_BANK",
    "account_number": "0000000000",
    "account_name": "SYNTHETIC_ACCOUNT_NAME"
  }
}

Mã lỗi & HTTP Status Codes

Các phản hồi lỗi từ hệ thống sử dụng trường error để mô tả nguyên nhân; một số phản hồi bổ sung trường code khi lỗi thuộc các danh mục có cấu trúc định sẵn (như API_LOCKED, API_READ_ONLY, PARTNER_INACTIVE, PARTNER_LIMIT_EXCEEDED, IDEMPOTENCY_KEY_REQUIRED). Khi xảy ra lỗi hệ thống 500, phản hồi sẽ trả về correlation_id để hỗ trợ tra soát kỹ thuật an toàn.

Hướng dẫn phục hồi sự cố mạng (Recovery Guidance)

Quy trình xử lý chuẩn khi rớt mạng / HTTP Timeout:

1. Bước 1: Lưu trữ mã định danh giao dịch nội bộ của bạn và chuỗi X-Idempotency-Key đã gửi.
2. Bước 2: Gửi lại request POST /api/buy với chính xác cùng một X-Idempotency-Key và cùng body JSON. Hệ thống sẽ trả về ngay kết quả đơn hàng đã tạo (kèm "idempotent_replay": true) mà không trừ thêm tiền vào ví.
3. Bước 3: Sau khi nhận được phản hồi chứa order_code (hoặc tra cứu từ danh sách GET /api/orders), bạn có thể gọi GET /api/orders/{order_code} để tra cứu lại thông tin đơn hàng bất kỳ lúc nào (lưu ý: endpoint này nhận mã đơn hoặc payment reference, không nhận idempotency key).

Quy chuẩn an toàn bảo mật đối tác

• Bảo mật khóa trên máy chủ (Backend-only): API Key chỉ được lưu trữ và gọi từ backend máy chủ của đối tác. Tuyệt đối không nhúng key vào mã nguồn Javascript phía client (Frontend/Mobile app) hoặc kho lưu trữ Git công khai.
• Định dạng tiền tệ chuẩn: Toàn bộ giá và số dư đều tính bằng đồng Việt Nam dạng số nguyên (integer). Không truyền chuỗi float có dấu chấm thập phân.
• Thu hồi & Đổi khóa: Nếu nghi ngờ lộ key, hãy truy cập Telegram Bot ngay lập tức để thực hiện yêu cầu đổi key mới.

Mã nguồn mẫu kết nối B2B

Ví dụ minh họa cách thực hiện kiểm tra số dư và đặt hàng có tích hợp Idempotency:

curl -X GET "https://api.uytinnhat.com/api/balance" \
  -H "X-API-Key: YOUR_API_KEY"

# Idempotent Order Placement
ORDER_KEY="partner-order-$(date +%s)"
curl -X POST "https://api.uytinnhat.com/api/buy" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: $ORDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "demo_product_01", "quantity": 1}'

import uuid
import httpx

API_BASE = "https://api.uytinnhat.com"
API_KEY = "YOUR_API_KEY"
headers = {"X-API-Key": API_KEY}

with httpx.Client(base_url=API_BASE, headers=headers, timeout=30.0) as client:
    bal_resp = client.get("/api/balance")
    print("Balance:", bal_resp.json().get("balance_vnd"))

    idempotency_key = f"order-{uuid.uuid4()}"
    buy_resp = client.post(
        "/api/buy",
        headers={"X-Idempotency-Key": idempotency_key},
        json={"product_id": "demo_product_01", "quantity": 1},
    )
    data = buy_resp.json()
    if buy_resp.status_code == 200:
        print("Success! Items delivered:", data.get("items"))
        print("Order code:", data.get("order_code"))
    else:
        print("Purchase failed:", data.get("error"))

import crypto from "crypto";

const API_BASE = "https://api.uytinnhat.com";
const API_KEY = "YOUR_API_KEY";

async function main() {
  const balRes = await fetch(`${API_BASE}/api/balance`, {
    headers: { "X-API-Key": API_KEY }
  });
  const balData = await balRes.json();
  console.log("Balance:", balData.balance_vnd);

  const idempKey = `order-${crypto.randomUUID()}`;
  const buyRes = await fetch(`${API_BASE}/api/buy`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "X-Idempotency-Key": idempKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ product_id: "demo_product_01", quantity: 1 })
  });

  const buyData = await buyRes.json();
  if (buyRes.ok) {
    console.log("Success! Items:", buyData.items);
    console.log("Order code:", buyData.order_code);
  } else {
    console.error("Failed:", buyData.error);
  }
}

main();