Offer API 文档

通过 Offer API，您可以动态管理卖家的商品报价、定价及库存。本文档将指导您如何使用 API Key 与 HMAC-SHA256 签名机制完成接口鉴权。

API 概述

Offer API 基于 REST 架构设计. 接口采用语义化的资源导向型 URL，支持 form-encoded格式的请求体，统一返回 JSON 格式的响应数据，并严格遵循标准的 HTTP 状态码、鉴权规范及请求方法（Verbs）。

该 Offer API 提供了一套完善的接口集，支持卖家动态管理商品报价。您可以使用这些接口创建新报价或更新现有报价，并支持对价格、过期时间及库存状态进行实时同步。

鉴权机制

Offer API 采用 API Key 进行身份验证。您可以在 API Key Management 页面申请、查看及管理您的密钥。如何申请并配置 API Key？
 

签名验证

接口鉴权通过以下 HTTP Headers 实现：

示例

var CryptoJS = require("crypto-js");

const secretKey = "Your_API_Secret_Key_Here";  
const apiKey = "Your_API_Key_Here"; 
const timestamp = "1780293232"; // timestamp
const requestBody = "{ 'offerId': 15000 }"; // Request body

let canonicalString = apiKey + String(timestamp) + requestBody;

const signature = CryptoJS.HmacSHA256(canonicalString, secretKey);

string apiKey = "Your_API_Key_Here";
string timestamp = "1780293232";
string requestBody = "{ \"offerId\": 15000 }";
string secretKey = "Your_API_Secret_Key_Here";

string canonicalString = $"{apiKey}{timestamp}{requestBody}";

byte[] keyBytes = Encoding.UTF8.GetBytes(secretKey);
byte[] messageBytes = Encoding.UTF8.GetBytes(canonicalString);

using (var hmac = new HMACSHA256(keyBytes))
{
    byte[] hashBytes = hmac.ComputeHash(messageBytes);
    var signature = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
    Console.WriteLine(signature);
}

<?php

function generateSignature($apiKey, $timestamp, $requestBody, $secretKey) {
    $canonicalString = $apiKey . $timestamp . $requestBody;
    return hash_hmac('sha256', $canonicalString, $secretKey);
}

$secretKey = "Your_API_Secret_Key_Here";
$apiKey = "Your_API_Key_Here";
$timestamp = "1780293232";
$requestBody = "{ 'offerId': 15000 }";

$signature = generateSignature($apiKey, $timestamp, $requestBody, $secretKey);

echo "Signature: " . $signature . "\n";

?>

请求限制

为保障系统稳定性，Offer API 对每分钟的 HTTP 请求总次数不设限制，但会根据您的卖家等级 (Seller Level) 限制每小时的配额与瞬时频率：

其他频率控制：

• 单个创建冷却时间： 针对同一种产品类型 (Product Type），每 5 秒内最多只能成功创建 1 个商品。超过该频率的创建将被系统限流。

⚠️ 重要提示： 一旦触发每小时配额上限或瞬时频率限制，后续请求将会失败。请在编写自动化脚本时合理设计限流应对机制（例如引入退避延迟重试）。

详细文档

以下是 Offer API 接口的完整参考指南。点击下方的资源名称即可查看详细的请求/响应参数及代码示例。

1. 商品（Offer）管理

用于查看和管理单个卖家商品生命周期的核心接口。

商品列表 – 获取您处于生效中或已下架的历史商品分页列表。

取消资格校验 – 检查特定商品是否满足安全取消的条件。

设置商品展示状态 – 切换商品的可见性（例如：显示、隐藏）。

取消商品 – 永久取消并移除一个处于生效状态的商品。

🔄 取消商品流程 – 下架前的资格校验与取消提交步骤指南。

2. 批量上传商品

通过批处理流程和模板，高效管理海量商品。

📤批量上传商品 – 上传文件，以同时创建或更新多个商品。

🔍查询上传结果 – 查看批量上传任务的执行状态和处理结果。

📥下载批量模板 – 获取官方数据模板（.csv / .xlsx），用于规范批量上传的数据格式。

3. 商品创建与修改

专为特定游戏类目定制的接口，用于创建、修改和查询商品信息。

💡最佳实践: 在调用任何创建接口前，请务必先运行商品创建预校验，以验证数据有效性防止提交报错。 

📈 生命周期与创建流程

货币商品创建流程 ❖ 道具商品创建流程 ❖ 账号商品创建流程 * 代练商品创建流程 ❖ 充值商品创建流程

🛠️ 类目端点

货币类商品: 创建货币商品 ❖ 编辑货币商品  ❖ 查询货币商品

道具类商品: 创建道具商品  ❖ 编辑道具商品  ❖ 查询道具商品

账号类商品: 创建账号商品 ❖ 编辑账号商品  ❖ 查询账号商品

代练类商品: 创建代练商品  ❖ 编辑代练商品  ❖ 查询代练商品

充值类商品: 创建充值商品  ❖ 编辑充值商品  ❖ 查询充值商品

4. 图片库管理

管理用于展示商品列表的多媒体资源和截图。

🖼️查询图片库 – 获取已上传图片及其 URL 的列表。

📤上传图片 – 向图片库上传新的图片资源。

🗑️删除图片 – 从图片库中移除不需要的图片释放存储空间。

5. 基础数据（元数据）

辅助查询接口，用于获取构建有效商品请求体所需的系统 ID、类目结构和字典数据。

游戏与服务器

• 游戏列表 (获取所有支持的游戏及其 ID)
• 查询游戏服务器 (获取指定游戏的服务器/阵营列表)

类目与属性

• 查询游戏货币类型
• 查询充值类目
• 查询道具类目
• 查询代练类目

物流

• 查询游戏发货时效

6. 错误处理

⚠️ 错误码字典 – 全面汇总了全局错误码、HTTP 状态码映射关系，以及针对请求失败的排查步骤。