SHARED API

API 接入文档

连接店铺商品与您的业务系统。从商品查询、库存检查到余额下单，按下面的流程开始对接。

requestPOSTauthapp_id + signsuccesscode 200formatform-urlencoded

接口基址 https://tghy.top

基础说明

提交方法POST

请求体类型application/x-www-form-urlencoded

身份校验商户 ID 与请求签名

判断结果读取 JSON 中的 code、msg、data

先注册本站账号，在会员中心取得自己的商户凭据。仅开放对接的商品可供查询。账号价格与权限请联系本站客服确认。

签名算法

移除 sign，将参数名排序，去掉值为空字符串的参数。用 PHP 表单编码拼接密钥，URL 解码后计算 MD5；数组规格也要参与签名。

PHP · 服务端示例

<?php
function makeSign(array $params, string $appKey): string
{
    unset($params['sign']);
    ksort($params);
    foreach ($params as $name => $value) {
        if ($value === '') {
            unset($params[$name]);
        }
    }
    return md5(urldecode(http_build_query($params) . '&key=' . $appKey));
}

// 在你的服务端使用账号自己的凭据；不要把真实密钥写进网页。
$params = ['app_id' => 'YOUR_APP_ID'];
$params['sign'] = makeSign($params, 'YOUR_APP_KEY');
// 将 $params 以表单格式 POST 到 /shared/authentication/connect。

app_key 只保存在您自己的服务端。发送请求时携带 app_id、sign 及业务参数，签名参数与实际提交内容应一致。

公共参数与响应

参数	要求	说明
`app_id`	必填	当前账号的商户 ID
`sign`	必填	本次请求的 MD5 签名

响应示意

JSON · code 为业务状态码

{
  "code": 200,
  "data": {}
}

失败时通常返回 code: 0，并在 msg 中说明原因。不同接口的 data 结构不同。

规格字段

race 表示商品种类；sku 是规格数组，例如 sku[颜色]=蓝色。商品返回 widget 时，按其 name 提交额外字段。

ENDPOINT

验证连接

POST/shared/authentication/connect

先验证商户凭据，成功后再读取商品。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

此接口不需要额外业务参数。

返回说明

data 中包含 shopName（店铺名称）和 balance（账号余额）。

ENDPOINT

获取商品列表

POST/shared/commodity/items

读取已开放 API 对接的商品。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

此接口不需要额外业务参数。

返回说明

data 是分类数组；分类的 children 包含商品。保留商品 code，后续请求将使用它。

ENDPOINT

获取商品详情

POST/shared/commodity/item

查看商品规格、下单要求和当前信息。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`code`	必填	商品编码

返回说明

data 是商品对象；重点读取 config、widget、draft_status、minimum 和 maximum。

ENDPOINT

获取实时库存

POST/shared/commodity/stock

提交具体规格，查询可售库存。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`code`	必填	商品编码
`race`	可选	商品种类
`sku`	可选	规格数组

返回说明

读取 data.stock；实际成交仍以订单接口校验为准。

ENDPOINT

计算购买价格

POST/shared/commodity/valuation

按当前账号、数量及规格询价。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`code`	必填	商品编码
`num`	必填	购买数量
`race`	可选	商品种类
`sku`	可选	规格数组
`card_id`	可选	预选卡 ID

返回说明

data.price 为本次询价结果。

ENDPOINT

检查购买库存

POST/shared/commodity/inventoryState

下单前检查指定数量和预选卡是否可用。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`shared_code`	必填	商品编码
`num`	必填	购买数量
`race`	可选	商品种类
`card_id`	可选	预选卡 ID

返回说明

code 为 200 表示本次检查通过；失败时查看 msg。

ENDPOINT

读取库存与配置

POST/shared/commodity/inventory

读取库存数量、价格与配置文本。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`sharedCode`	必填	商品编码，注意字段大小写
`race`	可选	商品种类

返回说明

常用字段：count、price、user_price、factory_price、config。这里的 config 为 INI 文本。

ENDPOINT

获取预选卡列表

POST/shared/commodity/draftCard

商品开启预选功能时使用。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`code`	必填	商品编码
`page`	可选	页码，建议从 1 开始
`limit`	可选	分页数量，默认 10
`race`	可选	商品种类
`sku`	可选	规格数组

返回说明

data.list 为预选项；data.total 为总数。使用前确认 draft_status 为 1。

ENDPOINT

获取预选卡详情

POST/shared/commodity/draft

确认指定预选卡的附加价格。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`code`	必填	商品编码
`card_id`	必填	预选卡 ID

返回说明

data.draft_premium 为预选附加价格。

ENDPOINT

提交订单

POST/shared/commodity/trade

通过当前对接账号余额购买。请求成功会产生真实订单并扣费。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`shared_code`	必填	商品编码
`num`	必填	购买数量
`request_no`	建议填写	每笔业务订单使用唯一编号；重试同一笔订单时保持一致
`race`	可选	商品种类
`sku`	可选	规格数组
`card_id`	可选	预选卡 ID
`contact`	可选	联系方式
`password`	可选	查单密码
`coupon`	可选	优惠券
`device`	可选	设备标识，通常填 0

返回说明

保存 data.tradeNo；data.amount 是扣费金额，data.secret 为发货内容。商品有 widget 时，也要提交对应 name 的值。

ENDPOINT

查询订单

POST/shared/commodity/query

凭订单号读取支付与发货情况。

请求参数

每个请求均需附带公共参数 app_id 和 sign。

参数	要求	说明
`tradeNo`	必填	订单号，注意大小写

返回说明

data.status 表示订单支付状态，0 为未支付、1 为已支付；data.secret 为发货内容，data.widget 为下单控件数据。

接入流程

取得凭据：用 connect 验证自己的商户 ID 与签名。
同步商品：读取列表与详情，保存商品编码和规格要求。
确认购买条件：先查库存、询价，再按需检查预选卡。
提交订单：确认账号余额和对接权限后下单，并保存订单号。
跟踪结果：用订单号查询发货；网络超时后先查单，避免盲目重复购买。

接口行为随站点版本及配置变化。正式接入前，请与本站确认当前版本、开放商品、账号权限及实际接口返回。