Reseller API · v1 & tương thích SHOPCLONE7

Kết nối website đại lý, mua tài khoản tự động

Lấy danh sách sản phẩm, mua hàng bằng số dư ví và nhận tài khoản ngay trong phản hồi JSON. Dùng API v1 cho tích hợp mới, hoặc API tương thích SHOPCLONE7 để website SHOPCLONE6/7 chỉ cần đổi domain và API Key.

Base URL
/api/v1
Định dạng
JSON · UTF-8
Xác thực
Bearer API Key
curl -X POST "https://your-domain/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a2e-order-1001" \
  -d '{"product_id": 3, "quantity": 2}'

Xác thực

Gửi API Key trong header Authorization: Bearer <API Key> (hoặc X-API-Key). Không đặt khoá trong URL; nếu khoá bị lộ, hãy đổi khoá mới ngay.

GET/api/v1/me

Thông tin tài khoản

Thông tin tài khoản, số dư ví và giới hạn tần suất mua.

Request

GEThttps://your-domain/api/v1/me

Tham số

AuthorizationBắt buộc
headerBearer <API Key>

Mã mẫu

curl "https://your-domain/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": {
    "username": "daily01",
    "email": "daily01@example.com",
    "balance": 1250000,
    "currency": "VND",
    "limits": { "buy_interval_seconds": 3, "max_wait_seconds": 25 }
  }
}
GET/api/v1/categories

Danh sách danh mục

Danh mục đang bán kèm số sản phẩm (tính cả danh mục con).

Request

GEThttps://your-domain/api/v1/categories

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
langTuỳ chọn
queryNgôn ngữ tên sản phẩm và thông báo (vi, en)

Mã mẫu

curl "https://your-domain/api/v1/categories" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": [
    { "id": 1, "parent_id": null, "name": "Facebook", "icon": "https://…/facebook.svg", "product_count": 11 },
    { "id": 8, "parent_id": 1, "name": "Via Việt Nam", "icon": null, "product_count": 4 }
  ]
}
GET/api/v1/products

Danh sách sản phẩm

Danh sách sản phẩm có lọc và phân trang; giá là giá riêng của bạn.

Request

GEThttps://your-domain/api/v1/products?category_id=1&in_stock=1&page=1&limit=50

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
category_idTuỳ chọn
queryLọc theo danh mục (gồm cả danh mục con)
searchTuỳ chọn
queryTìm theo tên sản phẩm
in_stockTuỳ chọn
query1 = chỉ lấy sản phẩm còn hàng
pageTuỳ chọn
queryTrang, mặc định 1
limitTuỳ chọn
querySố dòng mỗi trang, mặc định 50, tối đa 100
langTuỳ chọn
queryNgôn ngữ tên sản phẩm và thông báo (vi, en)

Mã mẫu

curl "https://your-domain/api/v1/products?category_id=1&in_stock=1&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "Via VN cổ 2FA",
      "category_id": 8,
      "price": 45000,
      "currency": "VND",
      "stock": 120,
      "in_stock": true,
      "min_quantity": 1,
      "max_quantity": 100,
      "country": "vn",
      "description": "…",
      "image": "https://…/via.png"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 19, "total_pages": 1 }
}
GET/api/v1/products/{id}

Chi tiết sản phẩm

Chi tiết một sản phẩm theo ID.

Request

GEThttps://your-domain/api/v1/products/3

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
idBắt buộc
pathID sản phẩm
langTuỳ chọn
queryNgôn ngữ tên sản phẩm và thông báo (vi, en)

Mã mẫu

curl "https://your-domain/api/v1/products/3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": {
    "id": 3,
    "name": "Via VN cổ 2FA",
    "category_id": 8,
    "price": 45000,
    "currency": "VND",
    "stock": 120,
    "in_stock": true,
    "min_quantity": 1,
    "max_quantity": 100,
    "country": "vn",
    "description": "…",
    "image": "https://…/via.png"
  }
}
POST/api/v1/orders

Tạo đơn hàng (mua)

Mua bằng số dư ví và nhận tài khoản ngay trong phản hồi. Hỗ trợ Idempotency-Key để thử lại an toàn, không bị mua trùng.

Request

POSThttps://your-domain/api/v1/orders

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
Idempotency-KeyTuỳ chọn
headerChuỗi duy nhất cho mỗi lần mua (tối đa 128 ký tự). Gửi lại cùng khoá trong 24 giờ sẽ nhận lại đơn cũ thay vì mua lần nữa
product_idBắt buộc
integerID sản phẩm (lấy từ /v1/products)
quantityBắt buộc
integerSố lượng cần mua, trong khoảng min_quantity – max_quantity
couponTuỳ chọn
stringMã giảm giá nếu có
waitTuỳ chọn
booleantrue (mặc định): chờ giao hàng tối đa vài chục giây; false: trả về ngay, tra lại bằng GET /v1/orders/{code}

Mã mẫu

curl -X POST "https://your-domain/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a2e-order-1001" \
  -d '{"product_id": 3, "quantity": 2}'

Phản hồi mẫu

201 Created · application/json
{
  "success": true,
  "message": "Tạo đơn hàng thành công!",
  "data": {
    "code": "STC261028TAKE49XD",
    "status": "completed",
    "source": "api",
    "total": 90000,
    "discount": 0,
    "currency": "VND",
    "coupon": null,
    "quantity": 2,
    "items": [
      { "product_id": 3, "name": "Via VN cổ 2FA", "unit_price": 45000, "quantity": 2, "total": 90000 }
    ],
    "created_at": "2026-10-28T09:15:02.000Z",
    "delivered": 2,
    "accounts": [
      "1000040304952|GUTJXYIFPWLHCNDOMBRKVAQESZ",
      "1000087676467|IVMRLABECWTQYUXHPOFNJDSZGK"
    ]
  }
}
GET/api/v1/orders

Lịch sử đơn hàng

Lịch sử đơn hàng (mới nhất trước), không kèm tài khoản.

Request

GEThttps://your-domain/api/v1/orders?status=completed&page=1

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
statusTuỳ chọn
queryLọc trạng thái: pending, processing, completed, cancelled, refunded
sourceTuỳ chọn
queryLọc nguồn đơn: api hoặc web
pageTuỳ chọn
queryTrang, mặc định 1
limitTuỳ chọn
querySố dòng mỗi trang, mặc định 50, tối đa 100

Mã mẫu

curl "https://your-domain/api/v1/orders?status=completed&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": [
    {
      "code": "STC261028TAKE49XD",
      "status": "completed",
      "source": "api",
      "total": 90000,
      "discount": 0,
      "currency": "VND",
      "coupon": null,
      "quantity": 2,
      "items": [
        { "product_id": 3, "name": "Via VN cổ 2FA", "unit_price": 45000, "quantity": 2, "total": 90000 }
      ],
      "created_at": "2026-10-28T09:15:02.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 }
}
GET/api/v1/orders/{code}

Chi tiết đơn hàng

Chi tiết đơn kèm danh sách tài khoản đã giao.

Request

GEThttps://your-domain/api/v1/orders/STC261028TAKE49XD

Tham số

AuthorizationBắt buộc
headerBearer <API Key>
codeBắt buộc
pathMã đơn hàng

Mã mẫu

curl "https://your-domain/api/v1/orders/STC261028TAKE49XD" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phản hồi mẫu

200 OK · application/json
{
  "success": true,
  "data": {
    "code": "STC261028TAKE49XD",
    "status": "completed",
    "source": "api",
    "total": 90000,
    "discount": 0,
    "currency": "VND",
    "coupon": null,
    "quantity": 2,
    "items": [
      { "product_id": 3, "name": "Via VN cổ 2FA", "unit_price": 45000, "quantity": 2, "total": 90000 }
    ],
    "created_at": "2026-10-28T09:15:02.000Z",
    "delivered": 2,
    "accounts": [
      "1000040304952|GUTJXYIFPWLHCNDOMBRKVAQESZ",
      "1000087676467|IVMRLABECWTQYUXHPOFNJDSZGK"
    ]
  }
}

Mã lỗi

Khi lỗi, success = false; error.code là mã cố định để code của bạn xử lý, error.message là thông báo cho người đọc, kèm request_id để gửi hỗ trợ.

402 Payment Required · application/json
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Số dư không đủ, vui lòng nạp thêm",
    "status": 402
  },
  "request_id": "4c043782-5dac-4e19-8ef8-60b7ff3c7c20"
}
400invalid_request
Tham số sai hoặc thiếu
400invalid_quantity
Số lượng ngoài khoảng cho phép
400out_of_stock
Không đủ hàng
401missing_api_key
Thiếu header Authorization
401invalid_api_key
API Key sai hoặc tài khoản bị khoá
402insufficient_balance
Số dư ví không đủ
403ip_not_allowed
IP không nằm trong whitelist của khoá
404product_not_found
Sản phẩm không tồn tại hoặc đã ngừng bán qua API
404order_not_found
Đơn hàng không tồn tại
409idempotency_conflict
Idempotency-Key đã dùng cho yêu cầu khác, hoặc yêu cầu trước đó vẫn đang xử lý
429rate_limited
Mua quá nhanh hoặc nhập sai khoá quá nhiều lần
503api_disabled
API đang tạm tắt
503order_refunded
Nguồn hàng lỗi, đơn đã được hoàn tiền

Lưu ý khi tích hợp

  • Gửi Idempotency-Key cho mỗi lần mua để có thể thử lại an toàn khi mạng lỗi hoặc hết thời gian chờ.
  • Đơn có status = processing khi chưa giao đủ — gọi GET /v1/orders/{code} để lấy phần còn lại.
  • Mỗi khoá cần cách nhau tối thiểu 3 giây giữa 2 lần mua.
  • Giá trả về là giá riêng của bạn (đã tính cấp bậc, Flash Sale), đơn vị VND.
  • Mọi phản hồi có header X-Request-Id; gửi kèm mã này khi cần hỗ trợ.
  • Chỉ sản phẩm giao tự động mới bán được qua API.