Tài liệu API đại lý

Mua hàng tự động từ bot hoặc website của bạn.

Bắt đầu

Lấy API key trong menu API đại lý trên bot. Gửi key trong header X-Api-Key ở mọi request. Dữ liệu gửi và nhận đều là JSON, tiền tính bằng VND.

Địa chỉ API	`http://api.clonzen.tech/api/v1`
Header	`X-Api-Key: ck_...`

Kết quả thành công có dạng {"success": true, "data": ...}. Khi lỗi: {"success": false, "error": {"code": "...", "message": "..."}}.

Xem số dư

GET /balance

{"success": true, "data": {"balance": 1500000, "currency": "VND"}}

Danh sách sản phẩm

GET /products

{"success": true, "data": [
  {"id": "sp_a", "name": "Sản phẩm A", "category": "Danh mục 1",
   "price": 45000, "pricing_tiers": [{"quantity": 10, "price": 40000}],
   "min_quantity": 1, "stock": 37}
]}

Giá đã trừ chiết khấu của bạn. Mua từ quantity trong pricing_tiers trở lên thì được giá tương ứng.

Mua hàng

POST /orders
{"product_id": "sp_a", "quantity": 2, "request_id": "don-0001"}

{"success": true, "data": {
  "order_id": "482913", "request_id": "don-0001",
  "product_id": "sp_a", "quantity": 2, "amount": 90000,
  "status": "COMPLETED", "items": ["user1|pass1", "user2|pass2"]
}}

request_id là mã đơn do bạn tự đặt, mỗi đơn một mã (tối đa 100 ký tự gồm chữ, số và _ . : -). Gửi lại cùng mã sẽ nhận lại đúng đơn cũ, không bị trừ tiền lần hai. Vì vậy khi bị timeout hay mất mạng, cứ gửi lại với mã cũ.

`COMPLETED`	Đã có hàng trong `items`.
`PROCESSING`	Đã trừ tiền, đang lấy hàng (HTTP 202). Gọi tra cứu đơn sau vài giây.
`FAILED`	Không giao được, tiền đã hoàn lại. Lý do trong `failure_reason`.

Tra cứu đơn

GET /orders/{request_id}

Trả về cùng dạng với khi mua hàng.

Mã lỗi

HTTP	code	Ý nghĩa
400	`INVALID_PARAMS`, `BELOW_MIN_QUANTITY`	Thiếu hoặc sai tham số, ít hơn số lượng tối thiểu
401	`UNAUTHORIZED`	Thiếu hoặc sai API key
402	`INSUFFICIENT_BALANCE`	Không đủ số dư
403	`CLIENT_PENDING`, `CLIENT_DISABLED`, `IP_NOT_ALLOWED`	Chưa được duyệt, bị khoá, hoặc IP không được phép
404	`PRODUCT_NOT_FOUND`, `ORDER_NOT_FOUND`	Không tìm thấy
409	`OUT_OF_STOCK`, `REQUEST_ID_CONFLICT`	Hết hàng; mã đơn đã dùng cho đơn khác
429	`RATE_LIMITED`	Gọi quá nhiều trong một phút
500	`INTERNAL_ERROR`	Lỗi hệ thống, gửi lại với cùng request_id

Ví dụ

curl -X POST http://api.clonzen.tech/api/v1/orders \
  -H "X-Api-Key: ck_xxx" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"sp_a","quantity":1,"request_id":"don-0001"}'