API 接口规范
您的第三方应用需要实现以下 API 接口，以便市场系统进行库存查询和更新操作。
1. 用户交易可用性检查接口
请求方式：GET
{host}/checkUser?userId={userId}&apiKey={apiKey}
参数说明：
userId - 用户ID（FishPi用户ID）apiKey - 您提供的 API Key
响应格式（可用）：
{
"code": 0,
"msg": "OK"
}
响应格式（不可用）：
{
"code": 1003,
"msg": "用户未注册"
}
📌 此接口用于检查用户是否在您的系统中注册并可参与交易。
⚠️ code=0 表示用户可用，code!=0 表示不可用（msg 字段说明原因，请返回友好 msg，对用户可见）。
💡 平台会在技术审核和交易前调用此接口，确保用户存在且可用。
⚠️ 请确保您提交的测试用户名已在您的系统中注册。
2. 查询库存接口
请求方式：GET
{host}/inventory?userId={userId}&apiKey={apiKey}&productKey={productKey}
参数说明：
userId - 用户ID（FishPi用户ID）apiKey - 您提供的 API KeyproductKey - 产品标识（可选，不传则返回所有产品）
响应格式（成功）：
{
"code": 0,
"data": [
{
"itemKey": "product_001",
"itemName": "高级道具",
"count": 10
}
],
"msg": "OK"
}
响应格式（失败）：
{
"code": 1,
"msg": "错误信息"
}
3. 更新库存接口
请求方式：POST
{host}/updateInventory
请求体（JSON）：
{
"userId": "fishpi_user_id",
"productKey": "product_001",
"count": 5,
"memo": "市场交易：订单ID xxx",
"apiKey": "your_api_key"
}
参数说明：
userId - 用户ID（FishPi用户ID）productKey - 产品标识count - 库存变化量（正数增加，负数减少）memo - 操作备注apiKey - 您提供的 API Key
响应格式（成功）：
{
"code": 0,
"data": [
{
"itemKey": "product_001",
"itemName": "高级道具",
"count": 15
},
{
"itemKey": "product_002",
"itemName": "普通道具",
"count": 8
}
],
"msg": "OK"
}
⚠️ data 字段必须返回该用户的完整最新库存列表，包括未被本次操作影响的其他物品。
响应格式（失败）：
{
"code": 1,
"msg": "库存不足"
}
⚠️ 重要说明
- 所有请求必须在 5秒 内响应
- code 为 0 表示成功，非 0 表示失败
- 产品审核时系统会进行技术测试：检查用户可用性 → 查询库存 → 加1 → 减1 → 验证
- 确保测试用户已在您的系统中注册，并有足够的库存供测试使用
- 交易前会调用
/checkUser 接口验证用户存在，避免交易失败
📡 开放 API（供您调用）
以下 API 供您的应用主动调用，用于查询在本平台注册的产品信息。
1. 获取已过审产品列表
请求方式：GET
{本站域名}/api/open/third-party/products?appId={appId}&apiKey={apiKey}
参数说明：
appId - 您的应用ID（在"我的应用"中查看）apiKey - 您在申请应用时提交的 API Key
响应格式（成功）：
{
"code": 0,
"data": [
{
"id": 1,
"itemKey": "product_001",
"itemName": "高级道具",
"productKey": "tp_1_product_001",
"description": "道具描述",
"createdAt": "2025-01-01T00:00:00.000Z"
}
],
"msg": "OK"
}
2. 获取应用详情
请求方式：GET
{本站域名}/api/open/third-party/app?appId={appId}&apiKey={apiKey}
参数说明：
appId - 您的应用IDapiKey - 您在申请应用时提交的 API Key
响应格式（成功）：
{
"code": 0,
"data": {
"id": 1,
"appName": "我的应用",
"description": "应用描述",
"status": "approved",
"createdAt": "2025-01-01T00:00:00.000Z",
"approvedAt": "2025-01-02T00:00:00.000Z",
"products": [
{
"id": 1,
"itemKey": "product_001",
"itemName": "高级道具",
"productKey": "tp_1_product_001",
"status": "approved",
"rejectReason": null,
"techError": null,
"createdAt": "2025-01-01T00:00:00.000Z"
}
]
},
"msg": "OK"
}
📌 此接口返回所有产品，包括待审核、已拒绝的产品，方便您查看完整状态。