代理 API · v1 及 SHOPCLONE7 兼容

对接你的代理网站, 自动购买账号

获取商品列表,用钱包余额下单,并直接在 JSON 响应中收到账号。新对接请使用 API v1,或使用兼容 SHOPCLONE7 的 API,让 SHOPCLONE6/7 网站只需更换域名和 API key。

Base URL
/api/v1
格式
JSON · UTF-8
认证
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}'

认证

请在 Authorization: Bearer <API key> 请求头(或 X-API-Key)中携带你的 API key。切勿把密钥放在 URL 中;一旦泄露,请立即生成新的密钥。

GET/api/v1/me

账号信息

账号信息、钱包余额和购买频率限制。

请求

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

参数

Authorization必填
headerBearer <API key>

代码示例

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

响应示例

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

分类列表

启用中的分类及商品数量(含子分类)。

请求

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

参数

Authorization必填
headerBearer <API key>
lang选填
query商品名称和消息的语言(vi、en)

代码示例

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

响应示例

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

商品列表

支持筛选和分页的商品列表;价格为你的专属价格。

请求

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

参数

Authorization必填
headerBearer <API key>
category_id选填
query按分类筛选(含子分类)
search选填
query按商品名称搜索
in_stock选填
query1 = 仅显示有货商品
page选填
query页码,默认 1
limit选填
query每页行数,默认 50,最大 100
lang选填
query商品名称和消息的语言(vi、en)

代码示例

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

响应示例

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}

获取商品

按 ID 获取单个商品。

请求

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

参数

Authorization必填
headerBearer <API key>
id必填
path商品 ID
lang选填
query商品名称和消息的语言(vi、en)

代码示例

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

响应示例

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

创建订单(购买)

使用钱包余额购买,并在响应中收到账号。支持 Idempotency-Key,可安全重试而不会重复购买。

请求

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

参数

Authorization必填
headerBearer <API key>
Idempotency-Key选填
header每次购买使用唯一字符串(最多 128 个字符)。24 小时内重复发送相同的密钥将返回原订单,而不会再次购买
product_id必填
integer商品 ID(来自 /v1/products)
quantity必填
integer购买数量,介于 min_quantity 和 max_quantity 之间
coupon选填
string优惠券代码(如有)
wait选填
booleantrue(默认):最多等待数十秒等待发货;false:立即返回,稍后用 GET /v1/orders/{code} 获取

代码示例

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}'

响应示例

201 Created · application/json
{
  "success": true,
  "message": "Tạo đơn hàng thành công!",
  "data": {
    "code": "TSM261105TAKE49XD",
    "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

订单列表

订单历史(最新在前),不含账号。

请求

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

参数

Authorization必填
headerBearer <API key>
status选填
query按状态筛选:pending、processing、completed、cancelled、refunded
source选填
query按来源筛选:api 或 web
page选填
query页码,默认 1
limit选填
query每页行数,默认 50,最大 100

代码示例

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

响应示例

200 OK · application/json
{
  "success": true,
  "data": [
    {
      "code": "TSM261105TAKE49XD",
      "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}

获取订单

订单详情及已发放的账号。

请求

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

参数

Authorization必填
headerBearer <API key>
code必填
path订单号

代码示例

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

响应示例

200 OK · application/json
{
  "success": true,
  "data": {
    "code": "TSM261105TAKE49XD",
    "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"
    ]
  }
}

错误码

出错时 success = false;error.code 是供你的程序使用的稳定错误码,error.message 为可读信息,另附 request_id 供客服排查。

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
缺少参数或参数无效
400invalid_quantity
数量超出允许范围
400out_of_stock
库存不足
401missing_api_key
缺少 Authorization 请求头
401invalid_api_key
API key 错误或账号已锁定
402insufficient_balance
钱包余额不足
403ip_not_allowed
IP 不在密钥白名单内
404product_not_found
未找到商品,或该商品已不再通过 API 销售
404order_not_found
未找到订单
409idempotency_conflict
Idempotency-Key 已用于另一个不同的请求,或上一个请求仍在处理中
429rate_limited
购买过于频繁或错误密钥次数过多
503api_disabled
API 暂时停用
503order_refunded
供应商失败,订单已退款

对接说明

  • 每次购买都请携带 Idempotency-Key,这样在网络错误或超时时可以安全重试。
  • 订单未完全发货时 status = processing——请调用 GET /v1/orders/{code} 获取剩余部分。
  • 同一密钥两次购买之间至少需间隔 3 秒。
  • 返回的价格为你的专属价格(已应用等级价和 Flash Sale),单位为 VND。
  • 每个响应都带有 X-Request-Id 请求头;联系客服时请一并提供。
  • 仅自动发货的商品可通过 API 购买。