Chuyển đến nội dung
Sàn Tài Khoản

Tài liệu API người bán

REST API cho phép người bán tự động đẩy sản phẩm lên Sàn Tài Khoản. Mỗi tài khoản người bán được cấp 1 API key (yêu cầu trong Tài khoản › API bán hàng, quản trị viên duyệt cấp phép).

Base URL

https://santaikhoan.com

Xác thực

Gửi API key trong header Authorization dạng Bearer. Khóa chỉ hiển thị một lần khi tạo — hãy lưu lại; mất thì tạo lại khóa.

Authorization: Bearer YOUR_API_KEY

Giới hạn tần suất

Tối đa 50 request/phút cho mỗi API key. Vượt giới hạn trả mã 429.

Vòng đời & chế độ đăng

  1. Người bán yêu cầu cấp key trong trang tài khoản → nhận khóa (hiện 1 lần).
  2. Quản trị viên duyệt cấp phép key và chọn chế độ đăng cho key đó:
  3. • Đăng ngay: sản phẩm hiển thị công khai ngay (khi có kho).
  4. • Chờ duyệt: sản phẩm vào hàng chờ, admin duyệt từng SP mới hiển thị.
  5. Kiểm tra chế độ hiện tại của key qua GET /api/seller/me.

Endpoints

MethodPathMô tả
POST/api/seller/productsĐẩy 1 sản phẩm.
GET/api/seller/productsDanh sách SP đã đăng + trạng thái duyệt.
GET/api/seller/categoriesDanh mục hợp lệ để đăng.
GET/api/seller/meKiểm tra key + chế độ đăng.

POST /api/seller/products

Các trường trong body JSON:

TrườngKiểuBắt buộcMô tả
namestringBắt buộcTên sản phẩm (≤ 200 ký tự).
categorySlugstringBắt buộcSlug danh mục có sẵn (lấy qua GET /categories). KHÔNG tạo danh mục mới.
pricenumberBắt buộcGiá bán (VND, > 0).
descriptionstringTùy chọnMô tả (≤ 5000 ký tự).
oldPricenumberTùy chọnGiá gạch (hiển thị giảm giá).
warrantyDaysnumberTùy chọnSố ngày bảo hành (mặc định 1).
imageUrlstringTùy chọnLink ảnh http/https CÓ SẴN. Hệ thống tự tải & lưu; không upload file. Nếu có mà tải lỗi sẽ báo lỗi.
stockstring[]Tùy chọnMảng dòng credential để giao (mỗi phần tử = 1 đơn vị, tối đa 2000). Được mã hóa khi lưu; không xuất hiện trong log.

Ví dụ (curl):

curl -X POST https://santaikhoan.com/api/seller/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tài khoản Netflix Premium 1 tháng",
    "categorySlug": "netflix",
    "price": 59000,
    "oldPrice": 89000,
    "warrantyDays": 30,
    "description": "Xem 4K UHD, bảo hành đăng nhập.",
    "imageUrl": "https://cdn.example.com/netflix.png",
    "stock": ["user1@mail.com|pass1", "user2@mail.com|pass2"]
  }'

Phản hồi thành công (201):

{
  "ok": true,
  "data": {
    "id": "b1a2...",
    "slug": "tai-khoan-netflix-premium-1-thang",
    "status": "approved",
    "stockAdded": 2
  }
}

GET /api/seller/products

Liệt kê sản phẩm bạn đã đăng (mới nhất trước) kèm trạng thái duyệt và tồn kho. Tham số: limit (mặc định 50, tối đa 100), offset.

curl "https://santaikhoan.com/api/seller/products?limit=20&offset=0" -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "products": [
      {
        "listingId": "…", "slug": "netflix-...", "productId": "…",
        "name": "Tài khoản Netflix Premium 1 tháng", "categorySlug": "netflix",
        "price": 59000, "oldPrice": 89000, "warrantyDays": 30,
        "approvalStatus": "approved",
        "listingStatus": "active",
        "stock": 12,
        "imageUrl": "/api/img/logos/….webp",
        "createdAt": "2026-08-21T…"
      }
    ],
    "total": 137, "limit": 20, "offset": 0
  }
}

GET /api/seller/categories

curl https://santaikhoan.com/api/seller/categories -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "data": [ { "slug": "netflix", "name": "Netflix" }, ... ] }

GET /api/seller/me

{ "ok": true, "data": { "sellerId": "...", "status": "approved", "autoPublish": true, "publishMode": "auto", "rateLimit": "50/min" } }

Mã lỗi

HTTPKhi nào
400Body JSON sai / thiếu trường bắt buộc / danh mục không hợp lệ / ảnh tải lỗi.
401Thiếu hoặc sai API key (header Authorization).
403API key chưa được duyệt / đang bị tắt / gian hàng bị khóa bán.
429Vượt 50 request/phút.
500Lỗi máy chủ.

Mọi phản hồi lỗi có dạng { "ok": false, "error": "..." }.

Lưu ý