Tài liệu API Reseller

🇻🇳 Tiếng Việt🇬🇧 English

API dành cho reseller sử dụng các dịch vụ công khai, số dư và lịch sử đơn của bot.

Base URL: /api/v1

Xác thực

Gửi X-API-Key trong mọi request. Quyền API phải được admin kích hoạt thủ công trước khi sử dụng. Chỉ dùng HTTPS; không đặt key trong URL, frontend công khai hoặc log.

curl -H "X-API-Key: YOUR_BOT_API_KEY" https://YOUR_DOMAIN/api/v1/me

Quy ước chung

{
  "ok": true,
  "code": "SUCCESS"
}
{
  "ok": false,
  "code": "INSUFFICIENT_BALANCE",
  "error": "Insufficient balance."
}

Dùng một clientOrderId/shopOrderId duy nhất cho mỗi đơn và dùng lại mã đó khi gửi lại request tạo đơn. Cùng mã nhưng payload khác trả 409 IDEMPOTENCY_CONFLICT.

Tài khoản, ví và lịch sử

MethodEndpointDescription
GET/meHồ sơ, tier, số dư Point và referral
GET/balanceSố dư Point chuẩn và quy đổi hiển thị
GET/purchases?limit=50Lịch sử mua trong bot
GET/deposits?limit=50Lịch sử nạp tiền
GET/referralsThống kê referral
{
  "ok": true,
  "success": true,
  "code": "SUCCESS",
  "shopId": "TG123",
  "wallet": {
    "point": 1.5,
    "usd": 1.5,
    "vnd": 39000,
    "credit": 2
  }
}

Point là đơn vị ví duy nhất: 1 Point = 1 USD = 26.000 VND. Telegram Stars chỉ dùng để nạp Point trong bot; wallet.usd và wallet.vnd chỉ là giá trị quy đổi hiển thị.

Sản phẩm Shop

MethodEndpointDescription
GET/products?page=1&limit=50Sản phẩm, giá và tồn kho
POST/ordersMua bằng productId hoặc code
POST/products/{id}/buyMua theo ID
GET/orders?limit=50Danh sách đơn Shop API
GET/orders/{orderCode}Chi tiết đơn
POST /orders

{
  "productId": 123,
  "qty": 1,
  "currency": "point",
  "shopOrderId": "shop-001"
}
{
  "ok": true,
  "order": {
    "orderCode": "ORDER123",
    "shopOrderId": "shop-001",
    "qty": 1,
    "total": 1.5,
    "currency": "point",
    "status": "completed",
    "accounts": [
      "delivered-content"
    ]
  }
}

Gemini Student Pro

MethodEndpointDescription
GET/sheerid/service_infoGiá và trạng thái
POST/sheerid/verifyTạo xác minh bằng URL SheerID
GET/sheerid/jobsDanh sách job
GET/sheerid/jobs/{job_id}Tiến độ và kết quả
POST /sheerid/verify

{
  "sheerid_url": "https://services.sheerid.com/verify/...",
  "client_order_id": "student-001",
  "discount_code": "API5"
}
{
  "job": {
    "job_id": "SJ123",
    "client_order_id": "student-001",
    "status": "pending",
    "progress": 0,
    "result_link": null
  }
}

Gemini Pro Xiaomi 3 tháng

MethodEndpointDescription
GET/xiaomi3/servicesGiá và trạng thái Xiaomi Full
POST/xiaomi3/ordersTạo batch 1–200 tài khoản
GET/xiaomi3/ordersDanh sách đơn
GET/xiaomi3/orders/{id}Chi tiết/kết quả

Xiaomi Full là chế độ duy nhất. Mỗi tài khoản được tạo thành một đơn riêng để theo dõi và hoàn tiền độc lập. Mặc định, bậc giá reseller được tính theo tổng số dư ví quy đổi: từ 30 USD giảm 5%, từ 60 USD giảm 10%. Nếu reseller được admin đặt giá riêng thì giá cứng đó được ưu tiên và không áp dụng bậc giảm. Giá được khóa tại thời điểm tạo đơn.

GET /xiaomi3/services

Đọc trạng thái mở bán, giá gốc, giá thực trả và bậc giảm hiện tại trước khi tạo đơn. customPrice=true nghĩa là tài khoản API đang dùng giá cứng riêng.

{
  "ok": true,
  "pricingTiers": [
    {
      "minimumUsd": 0,
      "discountPercent": 0
    },
    {
      "minimumUsd": 30,
      "discountPercent": 5
    },
    {
      "minimumUsd": 60,
      "discountPercent": 10
    }
  ],
  "services": [
    {
      "taskType": "default",
      "name": "Xiaomi Full",
      "basePriceUsd": 2,
      "basePriceVnd": 50000,
      "priceUsd": 1.7,
      "priceVnd": 43000,
      "discountPercent": 0,
      "customPrice": true,
      "walletEquivalentUsd": 35,
      "enabled": true
    }
  ]
}

POST /xiaomi3/orders

TrườngKiểuYêu cầu / Ý nghĩa
taskTypestringBắt buộc: chỉ nhận default.
currencystringKhuyến nghị: point. Legacy usd/vnd vẫn được nhận và đổi sang Point.
clientOrderIdstringBắt buộc, 8–80 ký tự: chữ, số, dấu gạch dưới hoặc gạch ngang. Dùng lại chính mã này khi request bị timeout.
accountsstring[]Bắt buộc 1–200 dòng. Mỗi dòng dùng 2FA Base32 đúng 32 ký tự hoặc một mã dự phòng 8 số.
POST /xiaomi3/orders
Content-Type: application/json
X-API-Key: YOUR_BOT_API_KEY

{"taskType":"default","currency":"point","clientOrderId":"xiaomi-001","accounts":["email@gmail.com|password|12345678","second@gmail.com|password|JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"]}

Request mới trả HTTP 202. Gửi lại cùng clientOrderId và cùng payload trả HTTP 200 với duplicated=true, không trừ tiền lần hai. Cùng clientOrderId nhưng đổi tài khoản hoặc currency trả HTTP 409 IDEMPOTENCY_CONFLICT.

{
  "ok": true,
  "duplicated": false,
  "orders": [
    {
      "id": 812,
      "clientOrderId": "xiaomi-001",
      "email": "email@gmail.com",
      "taskType": "default",
      "status": "pending",
      "amount": 47500,
      "currency": "vnd",
      "resultLink": null,
      "errorCode": null,
      "errorEn": null,
      "createdAt": "2026-11-16 10:20:00",
      "updatedAt": "2026-11-16 10:20:01"
    }
  ]
}

GET /xiaomi3/orders

Trả tối đa 50 đơn gần nhất của API key hiện tại, mới nhất trước. Một batch nhiều tài khoản xuất hiện thành nhiều đơn có cùng clientOrderId.

{
  "ok": true,
  "orders": [
    {
      "id": 812,
      "clientOrderId": "xiaomi-001",
      "email": "email@gmail.com",
      "taskType": "default",
      "status": "running",
      "amount": 47500,
      "currency": "vnd",
      "resultLink": null,
      "errorCode": null,
      "errorEn": null,
      "createdAt": "2026-11-16 10:20:00",
      "updatedAt": "2026-11-16 10:21:10"
    }
  ]
}

GET /xiaomi3/orders/{id}

Tra cứu một đơn thuộc API key hiện tại. Thành công trả resultLink khi có; thất bại trả errorCode và errorEn đã chuẩn hóa, đồng thời số tiền của riêng đơn đó được hoàn tự động.

{
  "ok": true,
  "order": {
    "id": 812,
    "clientOrderId": "xiaomi-001",
    "email": "email@gmail.com",
    "taskType": "default",
    "status": "success",
    "amount": 47500,
    "currency": "vnd",
    "resultLink": "https://one.google.com/...",
    "errorCode": null,
    "errorEn": null,
    "createdAt": "2026-11-16 10:20:00",
    "updatedAt": "2026-11-16 10:23:00"
  }
}
{
  "ok": true,
  "order": {
    "id": 813,
    "clientOrderId": "xiaomi-001",
    "email": "second@gmail.com",
    "taskType": "default",
    "status": "failed",
    "amount": 47500,
    "currency": "vnd",
    "resultLink": null,
    "errorCode": "wrong_password",
    "errorEn": "Incorrect password.",
    "createdAt": "2026-11-16 10:20:00",
    "updatedAt": "2026-11-16 10:22:00"
  }
}

Trường đơn:

TrườngKiểuYêu cầu / Ý nghĩa
idintegerID đơn dùng cho endpoint chi tiết.
clientOrderIdstringID idempotency do reseller cung cấp.
emailstringTài khoản của đơn; mật khẩu/2FA không được trả lại.
statusstringsubmitting | pending | running | success | failed | cancelled
amountnumberSố Point đã khóa cho riêng đơn.
currencystringpoint
resultLinkstring|nullLink kết quả khi hoàn tất và có link.
errorCodestring|nullMã lỗi ổn định để xử lý bằng code.
errorEnstring|nullThông báo lỗi tiếng Anh an toàn cho khách.
createdAt / updatedAtstringThời gian tạo và cập nhật gần nhất.

Theo dõi trạng thái

Kiểm tra trạng thái mỗi 5–10 giây. Dừng khi success, failed hoặc cancelled. Nếu hệ thống không trả về mã tác vụ hợp lệ, đơn thất bại và được hoàn ví tự động.

submitting → pending → running → success
failed, cancelled

HTTP status và mã lỗi

MethodEndpointDescription
400INVALID_TASK_TYPE / INVALID_CURRENCY / INVALID_CLIENT_ORDER_ID / INVALID_ACCOUNTS / INVALID_ORDER_IDRequest không hợp lệ
401MISSING_API_KEY / INVALID_API_KEYLỗi xác thực
402INSUFFICIENT_BALANCE / INSUFFICIENT_CREDITKhông đủ số dư
403API_NOT_UNLOCKED / SERVICE_DISABLEDAdmin chưa mở quyền hoặc dịch vụ đang tắt
404ORDER_NOT_FOUND / INVALID_PRODUCTKhông tìm thấy
409IDEMPOTENCY_CONFLICTCùng ID nhưng payload khác
410XIAOMI_LINK_DISABLEDChế độ Link không tồn tại
500INTERNAL_ERRORLỗi nội bộ tạm thời; gửi lại cùng clientOrderId
503SERVICE_UNAVAILABLE / PRICE_UNAVAILABLETạm thời không khả dụng

Bảo mật

API không trả lại mật khẩu, khóa 2FA hay mã tác vụ nội bộ. Không ghi credentials vào log và không chia sẻ X-API-Key.

OpenAPI cho Postman/Swagger

GET /api/v1/openapi.json