GenzShop Buyer API

GenzShop 官方发布的 API，供合作伙伴在其网站、应用或机器人上自动销售产品。

快速上手

  1. 使用 GenzShop 签发的 API 密钥（联系管理员获取密钥）。
  2. 使用 GET /products.php 获取商品。
  3. 使用 GET /balance.php 查看钱包余额。
  4. 使用 POST /purchase.php 下单购买。
  5. 成功后，从 deliveredAccounts 获取数据交付给客户。

注意事项

  • 接口地址必须带 .php 后缀（例如 /products.php）。缺少 .php 会返回 HTML 404 页面而非 JSON。
  • 生产环境必须通过 HTTPS 调用——密钥放在请求头中，必须走加密通道。使用普通 HTTP 调用会被拒绝（HTTPS_REQUIRED）。
  • 每位客户的每笔订单都必须有各自独立的 idempotency_key。
  • 重复提交同一笔订单时，请保持原来的 idempotency_key 不变——系统返回已创建的订单并附带 replay: true，不会重复扣费。
  • 购买时，系统从与该密钥绑定的账户的钱包余额 (VND)中扣款。
  • 若产品暂时缺货，购买接口将返回 OUT_OF_STOCK 错误。
  • 出错时，请读取 errorCode 以了解处理方式。

Base URL 与认证

Base URL：

https://genzshop.vn/api/partner/v1

所有请求都必须附带认证请求头（推荐使用 X-API-Key）：

X-API-Key: YOUR_API_KEY

或使用 Bearer 标准（等效）：

Authorization: Bearer YOUR_API_KEY
在生产环境中，API 仅接受 HTTPS 连接。
GET /products.php

获取正在售卖的商品列表，含代理价与库存。

curl "https://genzshop.vn/api/partner/v1/products.php" \
  -H "X-API-Key: YOUR_API_KEY"

响应（简略）：

{
  "success": true,
  "walletCurrency": "VND",
  "products": [
    {
      "product_id": "CUR-0001",
      "name": "Cursor Pro 1 tháng",
      "description": "Tài khoản Cursor Pro dùng 1 tháng",
      "type": "cursor",
      "walletCurrency": "VND",
      "walletPricing": 120000,
      "walletPricingText": "120.000 VND",
      "available": 38
    }
  ]
}

使用 product_id（即 SKU）下单。若产品暂时缺货，购买接口将返回 OUT_OF_STOCK 错误。

GET /balance.php

查看与该 API 密钥关联账户的当前钱包余额。

curl "https://genzshop.vn/api/partner/v1/balance.php" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "success": true,
  "walletCurrency": "VND",
  "balance": 5000000,
  "balanceText": "5.000.000 VND"
}
POST /purchase.php

下单并即时获取账号。从钱包余额扣款，在 deliveredAccounts 中返回账号。

curl -X POST "https://genzshop.vn/api/partner/v1/purchase.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "CUR-0001",
    "quantity": 1,
    "idempotency_key": "don-khach-0001"
  }'

请求体参数：

参数类型描述
product_idstring产品 SKU，例如 CUR-0001（必填）
quantityinteger数量 1..1000（必填）
idempotency_keystring8..128 个字符 [A-Za-z0-9._:-]（必填）
customer_emailstring您的客户邮箱，用于对账（可选）

成功响应：

{
  "success": true,
  "walletCurrency": "VND",
  "orderCode": "GZ260724CUR3F9A2B",
  "productType": "cursor",
  "quantity": 1,
  "amount": 120000,
  "amountText": "120.000 VND",
  "balance": 4880000,
  "balanceText": "4.880.000 VND",
  "deliveredAccounts": [
    {
      "productItemId": "1024",
      "user": "[email protected]",
      "password": "example-password",
      "verifyEmail": "[email protected]"
    }
  ]
}

若使用已用过的 idempotency_key 重新提交，响应将保持原订单不变，并附带 "replay": true——不会再次扣费。

错误与错误码 (errorCode)

所有错误均返回固定格式的 JSON（HTTP 状态 ≥ 400）：

{
  "success": false,
  "errorCode": "INSUFFICIENT_BALANCE",
  "detail": "Số dư ví không đủ. Cần 120.000 VND, số dư hiện tại 50.000 VND."
}
HTTPerrorCode含义
400INVALID_BODY请求体不是有效的 JSON
401MISSING_API_KEY缺少 X-API-Key 请求头（或 Authorization: Bearer）
401INVALID_API_KEY密钥错误或已被吊销
402INSUFFICIENT_BALANCE钱包余额不足
403HTTPS_REQUIRED在生产环境中使用 HTTP 调用——必须使用 HTTPS
403IP_NOT_ALLOWEDIP 不在该密钥的白名单中
404PRODUCT_NOT_FOUND找不到该产品
405METHOD_NOT_ALLOWED该接口的 HTTP 方法不正确
409PRODUCT_INACTIVE该产品目前未上架
409OUT_OF_STOCK库存不足
422INVALID_PRODUCT_ID缺少 product_id 或格式不正确
422INVALID_QUANTITY数量超出 1..1000 范围
422INVALID_IDEMPOTENCY_KEYidempotency_key 格式不正确
422INVALID_CUSTOMER_EMAILcustomer_email 无效
429RATE_LIMITED调用过于频繁（按 IP 或按密钥限流），请稍后重试
500INTERNAL_ERROR系统错误，未扣费

当触发按密钥限流的 RATE_LIMITED 时，响应会附带 Retry-After、X-RateLimit-Limit 和 X-RateLimit-Remaining 请求头——请等待 Retry-After 中的秒数后再重试。

Zalo Telegram