发卡网对接教程

一、准备账号与商户凭证

1. 在 本站注册账号，然后登录。
2. 进入个人中心，找到 API / 商户对接信息，复制你自己的商户 ID（app_id）与商户密钥（app_key）。
3. 确认你的发卡系统支持异次元共享协议、店铺共享或对应的 SharedStock 兼容方式。菜单名称会随程序版本变化；只有“远程商品”功能，并不代表协议一定兼容。
4. 确认商品已开放对接，并准备足够的本站账户余额。连接与拉取商品成功，不代表已经具备下单所需的余额和库存。

如果后台有单独的“会员 ID”和“商户 ID”，请填写个人中心对接区域显示的商户 ID。不要把你自己的网站用户 ID、本站商品 ID 或店铺共享记录 ID 填入认证字段。

二、在你的网站后台添加远程店铺

进入你的网站后台 → 店铺共享 / 商品对接 → 新增店铺，选择与你程序版本匹配的异次元共享或 SharedStock 协议。

保存后执行“连接测试”。正常应收到业务成功响应（code=200），并能显示远程店铺信息。HTTP 200 只说明收到了响应；还要检查响应中的 code 和 msg。

本站同时提供 /shared/… 标准接口和 /plugin/SharedStock/api/… 兼容接口。普通商户按上表配置即可；自己编写客户端时，请查看本文末尾的完整路径和签名示例。

三、导入商品并核对拿货价

1. 在已连接店铺中选择“拉取商品 / 商品同步”，把开放对接的商品导入本地分类。
2. 按需要设置固定金额加价或百分比加价，并开启程序支持的价格、库存同步。
3. 核对商品种类、SKU、购买数量、发货方式与必填信息；不要只核对商品名称。
4. 核对你当前商户身份对应的拿货价，再设置本地售价。更换会员等级、规格或数量后，重新取价。

例如：确认某规格当前拿货价为 100 元，设置固定加价 20 元，本地售价为 120 元。加价在你的网站设置，不会改变本站对该账号的采购计价。

库存列表可能是同步快照。对需要实时确认的商品，应使用库存接口；人工发货商品的库存显示也不能当作“立即返回卡密”的承诺。

可以调整你自己站点的商品展示、分类和排序。保留远程商品 CODE 以及种类 / SKU 对应关系；商品 CODE 不等于本站商品页面中的数字 ID。

四、充值与对接验收

共享采购使用你的本站账户余额。可用充值方式以充值页面为准；USDT 操作请查看USDT 支付教程，按当前付款页面的网络、收款地址和准确到账金额操作。

1. 先做不扣款的检查：连接测试成功，能拉取开放商品，规格、即时价格和库存符合预期。
2. 再做真实采购验收：确认金额和商品后，用你准备好的验收商品下一笔订单。这一步会消耗本站余额，并可能交付真实卡密。
3. 对照两边订单：记录你的网站订单号和本站返回的订单号，核对余额扣款、采购状态及交付内容。
4. 核对发货方式：自动发货商品检查内容是否完整返回；人工发货商品检查状态是否按实际交付进度更新。

五、常见问题

连接提示“商户鉴权失败”或“密钥错误”

检查商户 ID、当前密钥、选择的协议和程序签名实现。只发送 app_id 与 app_key 不够，还需要正确的 sign；业务参数也必须参与签名。重置密钥后更新所有客户端，并重新计算签名。

当前接口对无效凭证可能统一返回“商户鉴权失败”。不要依靠错误文案判断某个商户 ID 是否存在。

接口返回 404，或浏览器打开 /shared/ 没有页面

/shared/ 是接口前缀，不是可浏览的页面。后台店铺地址填写根地址；自己调试时，使用下表的完整接口路径与 POST 方法。不要在 URL 后拼中文逗号、字段说明或密钥。

连接成功，但没有商品或缺少部分商品

核对商品是否已上架、分类是否启用、是否开放对接，以及当前会员的商品可见范围。重新拉取商品，并确认本地没有被分类或筛选条件隐藏。前台能看到的商品不一定全部开放 API 对接。

商品能拉取，但下单失败或没有自动发货

依次核对余额、实时库存、商品是否停售、远程 CODE、种类 / SKU、数量及商品要求的联系 / 充值信息。人工发货商品需要等待实际处理；若为接口异常，请提供脱敏的错误响应和两边订单号。

同步价格与最终下单金额不一致

用同一商户账号、商品 CODE、规格和数量重新取价；检查会员等级、批发数量优惠、预选附加费以及本地加价设置。不要把商品展示价或列表快照当作所有规格的固定采购价。

请求超时、频率受限或返回 HTML 页面

检查服务器网络、TLS 证书验证、请求超时和响应 Content-Type。查询类请求可按错误信息退避重试；下单先查状态再决定是否重试。若返回网页或访问限制提示，记录请求时间、完整接口路径、HTTP 状态与脱敏响应，联系客服核查。

充值已付款，余额仍未增加

先查充值订单状态；USDT 核对网络、收款地址、到账金额和链上确认。联系客服时提供充值订单号与交易哈希，不要提供钱包助记词、私钥或商户密钥。

六、开发者接口参考

以下路径相对于 https://web3chirou.com。均使用 POST，请求体为 application/x-www-form-urlencoded。公共认证字段：app_id、app_key、sign。

参数名区分大小写：inventory 使用 sharedCode，inventoryState 和 trade 使用 shared_code，查单使用 tradeNo。CODE 从接口商品数据获取，不要自行拼接。空规格、未预选的字段按客户端契约提交；sku 如为数组，使用 PHP 表单数组编码。

旧版兼容路径为 /plugin/SharedStock/api/ 加对应功能名。例如连接测试是 /plugin/SharedStock/api/connect，商品列表是 /plugin/SharedStock/api/items，查单是 /plugin/SharedStock/api/query。其认证和签名要求与标准接口一致。

<?php
$appId = getenv('WEB3CHIROU_APP_ID');
$appKey = getenv('WEB3CHIROU_APP_KEY');
if (!$appId || !$appKey) {
    throw new RuntimeException('请配置自己的商户 ID 和当前密钥');
}

$data = ['app_id' => $appId, 'app_key' => $appKey];
$toSign = $data;
unset($toSign['sign']);
ksort($toSign);
foreach ($toSign as $name => $value) {
    if ($value === '') {
        unset($toSign[$name]);
    }
}
$data['sign'] = md5(urldecode(http_build_query($toSign) . '&key=' . $appKey));

$curl = curl_init('https://web3chirou.com/shared/authentication/connect');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($data),
    CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_CONNECTTIMEOUT => 8,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);
$response = curl_exec($curl);
if ($response === false) {
    throw new RuntimeException(curl_error($curl));
}
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode !== 200) {
    throw new RuntimeException('接口 HTTP 状态：' . $httpCode);
}
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if (($result['code'] ?? null) !== 200) {
    throw new RuntimeException($result['msg'] ?? '连接失败');
}
echo "连接成功\n";