Bắt đầu

Seller API

Base URL: https://api.shopaikey.com/seller

Giới thiệu

Seller API dành riêng cho các Seller (Đại lý) của ShopAIKey. Thông qua API này, seller có thể tự động hoá việc quản lý credit, tạo và phân phối API key cho khách hàng cuối của mình.

Với Seller API, bạn có thể:

  • Kiểm tra số dư credit của tài khoản seller.
  • Tạo API key mới (đơn lẻ hoặc hàng loạt) cho khách hàng và trừ credit tương ứng.
  • Nạp thêm, rút bớt hoặc xoá key để hoàn credit về tài khoản seller.
  • Quản lý trạng thái, tên key.
  • Nạp credit vào tài khoản seller qua chuyển khoản ngân hàng.
  • Xem thống kê sử dụng và lịch sử giao dịch.
  • Tích hợp vào hệ thống bán hàng, bot Telegram, website riêng để vận hành tự động 24/7.

Lưu ý: API này không dành cho người dùng cuối. Chỉ tài khoản đã được cấp quyền Seller mới có thể sử dụng các endpoint dưới đây.

Authentication

Mọi request đều yêu cầu secret key của seller ở header:

code
Authorization: Bearer sk-xxx

hoặc:

code
x-secret-key: sk-xxx

Cảnh báo bảo mật: Secret key của seller có quyền thao tác trực tiếp lên số dư credit. Tuyệt đối không chia sẻ, không commit vào git, không nhúng trực tiếp vào code client.

Hướng dẫn sử dụng nhanh

1. Kiểm tra thông tin tài khoản seller

code
curl -X GET https://api.shopaikey.com/seller \
  -H "Authorization: Bearer sk-your-seller-secret-key"

2. Tạo API key mới cho khách hàng

code
curl -X POST https://api.shopaikey.com/seller/keys \
  -H "Authorization: Bearer sk-your-seller-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "type": "cheap", "name": "Key cho khách A"}'

3. Kiểm tra danh sách key đã phát hành

code
curl -X GET https://api.shopaikey.com/seller/keys \
  -H "Authorization: Bearer sk-your-seller-secret-key"

Endpoints

1. Lấy thông tin seller

Endpoint: GET /seller

Mô tả: Trả về thông tin tài khoản seller, bao gồm email và số dư credit hiện có.

Response:

code
{
  "id": 1,
  "email": "[email protected]",
  "credit": 100.5
}

2. Danh sách key do seller phát hành

Endpoint: GET /seller/keys

Query params:

ParamTypeDescription
searchstringTìm theo tên hoặc giá trị key
statusstringLọc theo trạng thái: active, inactive, expired
typestringLọc theo loại: cheap, claude_code

Response:

code
{
  "keys": [
    {
      "id": 1,
      "key": "sk-abc123...",
      "name": "Key cho khách A",
      "type": "cheap",
      "balance": 50,
      "status": "active",
      "created_at": "2024-01-01T00:00:00.000Z",
      "refundable": true,
      "used": 10,
      "remain": 40
    }
  ]
}

3. Tạo key mới

Endpoint: POST /seller/keys

Body:

FieldTypeRequiredDescription
amountnumberYesSố credit cấp cho key (trừ vào credit seller)
typestringYescheap hoặc claude_code
namestringNoTên gợi nhớ của key

Response:

code
{
  "key": "sk-generated-key...",
  "balance": 10,
  "id": 1
}

4. Tạo nhiều key cùng lúc

Endpoint: POST /seller/keys/bulk-create

Body:

FieldTypeRequiredDescription
amountnumberYesSố credit mỗi key
typestringYescheap hoặc claude_code
quantityintegerYesSố lượng key cần tạo

Response: Mảng các key đã tạo.

5. Nạp thêm credit cho key

Endpoint: POST /seller/keys/:key_id/topup

Body:

FieldTypeRequiredDescription
amountnumberYesSố credit nạp thêm (trừ vào credit seller)

Response:

code
{
  "balance": 30
}

6. Trừ credit từ key (thu hồi)

Endpoint: POST /seller/keys/:key_id/deduct

Body:

FieldTypeRequiredDescription
amountnumberYesSố credit cần thu hồi

Response:

code
{
  "keyBalance": 40,
  "userCredit": 110
}

7. Cập nhật trạng thái key

Endpoint: PUT /seller/keys/:key_id/status

Body:

FieldTypeRequiredDescription
statusstringYesactive hoặc inactive

Response:

code
{
  "success": true,
  "status": "inactive"
}

8. Đổi tên key

Endpoint: PUT /seller/keys/:key_id/name

Body:

FieldTypeRequiredDescription
tokenNamestringYesTên mới cho key

Response:

code
{
  "success": true
}

9. Xoá key và hoàn credit

Endpoint: DELETE /seller/keys/:key_id

Response:

code
{
  "refunded": 25.5
}

Lưu ý: Key bị xoá sẽ không thể khôi phục. Khách hàng đang dùng key sẽ mất quyền truy cập ngay lập tức.

10. Xoá nhiều key cùng lúc

Endpoint: DELETE /seller/keys/bulk

Body:

FieldTypeRequiredDescription
idsarray of integerYesDanh sách ID key cần xoá

Response:

code
{
  "deleted": 3,
  "refunded": 75.0,
  "failures": []
}

11. Tạo đơn nạp credit seller

Endpoint: POST /seller/topup

Mô tả: Tạo đơn nạp credit vào tài khoản seller qua chuyển khoản ngân hàng. Số tiền tối thiểu 500.000đ, bội số 1.000đ.

Body:

FieldTypeRequiredDescription
amount_vndintegerYesSố tiền VND (tối thiểu 500.000, bội số 1.000)

Response:

code
{
  "order_id": 123,
  "transfer_content": "NP123",
  "amount": 208,
  "price_vnd": 1000000,
  "qrUrl": "https://...",
  "bank_info": { ... }
}

12. Lấy thông tin đơn nạp credit

Endpoint: GET /seller/topup/:order_id

Response: Tương tự response của POST /seller/topup, có thêm trường status.

13. Lịch sử nạp credit

Endpoint: GET /seller/topup-history

Query params:

ParamTypeDescription
pageintegerTrang (mặc định: 1)
limitintegerSố bản ghi mỗi trang (tối đa 50)
searchstringTìm theo nội dung chuyển khoản
statusstringLọc theo trạng thái đơn

14. Huỷ đơn hàng

Endpoint: PUT /seller/orders/:id

Body:

FieldTypeRequiredDescription
statusstringYesChỉ hỗ trợ cancelled

15. Huỷ nhiều đơn hàng

Endpoint: PUT /seller/orders/bulk

Body:

FieldTypeRequiredDescription
idsarray of integerYesDanh sách ID đơn cần huỷ
statusstringYesChỉ hỗ trợ cancelled

16. Thống kê sử dụng

Endpoint: GET /seller/stats

Query params:

ParamTypeDescription
modestringdaily hoặc monthly (mặc định: daily)
fromstringNgày bắt đầu (YYYY-MM-DD)
tostringNgày kết thúc (YYYY-MM-DD)

Response:

code
{
  "totalSpent": 5000000,
  "totalOrders": 10,
  "totalRequests": 12500,
  "totalTokenUsed": 3200000,
  "spending": [
    { "date": "2026-04-28", "total": 500000, "count": 1 }
  ],
  "topModels": [
    { "modelName": "claude-3-5-sonnet", "requests": 5000, "tokenUsed": 1200000 }
  ]
}

17. Lịch sử giao dịch

Endpoint: GET /seller/transactions

Query params:

ParamTypeDescription
pageintegerTrang (mặc định: 1)
limitintegerSố bản ghi mỗi trang (tối đa 50)
typestringLọc theo loại giao dịch

Error Responses

HTTP CodeMô tả
400Sai tham số hoặc không đủ credit
401Thiếu hoặc sai secret key
404Không tìm thấy key / đơn hàng
500Lỗi server
code
{
  "error": "Không đủ credit"
}

Ví dụ workflow cho Seller

Kịch bản: seller bán 1 key 50 credit cho khách, sau đó khách mua thêm 30 credit.

code
# 1. Kiểm tra credit seller
curl -X GET https://api.shopaikey.com/seller \
  -H "Authorization: Bearer sk-your-seller-secret-key"

# 2. Tạo key 50 credit cho khách
curl -X POST https://api.shopaikey.com/seller/keys \
  -H "Authorization: Bearer sk-your-seller-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "type": "cheap", "name": "Khach_NguyenVanA"}'

# 3. Khách mua thêm 30 credit
curl -X POST https://api.shopaikey.com/seller/keys/1/topup \
  -H "Authorization: Bearer sk-your-seller-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 30}'

# 4. Khách ngừng dùng, xoá key lấy lại credit thừa
curl -X DELETE https://api.shopaikey.com/seller/keys/1 \
  -H "Authorization: Bearer sk-your-seller-secret-key"

Lưu ý bảo mật cho Seller

  • Không chia sẻ secret key với khách hàng hoặc bên thứ ba.
  • Không commit secret key vào git repository.
  • Luôn dùng HTTPS khi gọi API ở môi trường production.
  • Xoay vòng secret key định kỳ hoặc ngay khi nghi ngờ bị lộ.
  • Đặt tên key có ý nghĩa (ví dụ: khach_abc_2025_01) để dễ đối soát với khách hàng.
  • Log lại mọi giao dịch ở phía hệ thống seller để đối chiếu với ShopAIKey khi cần.

Bài cùng nhóm · Bắt đầu

Giới thiệu ShopAIKey
Mua key và nạp tiền
Bài trướcMua key và nạp tiềnBài sau OpenAI Format