PHPackages                             fcwh/shop\_sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. fcwh/shop\_sdk

ActiveLibrary[API Development](/categories/api)

fcwh/shop\_sdk
==============

电商联盟统一 SDK：淘宝联盟、多多进宝、京东联盟 - 物料搜索、链接转换、店铺搜索、商品详情

00PHP

Since Feb 28Pushed 4mo agoCompare

[ Source](https://github.com/yangxiaozhan/shopunion_sdk)[ Packagist](https://packagist.org/packages/fcwh/shop_sdk)[ RSS](/packages/fcwh-shop-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

ShopUnion SDK
=============

[](#shopunion-sdk)

电商联盟统一 PHP SDK，用于对接 **淘宝联盟**、**多多进宝**、**京东联盟** 的开放 API。合作方通过 Composer 引入后，使用**自身或平台方提供的配置**即可调用物料搜索、链接转换、店铺搜索、商品详情、商品列表、生成淘口令、物料分类及物料精选等能力。

---

合作方如何调用本 SDK
------------

[](#合作方如何调用本-sdk)

### 一、环境要求

[](#一环境要求)

- PHP >= 7.4
- Composer
- 已开通对应联盟平台并取得 **app\_key / app\_secret（或 client\_id / client\_secret）** 及推广位等信息

### 二、安装

[](#二安装)

在合作方项目中执行：

```
composer require fcwh/shop_sdk
```

或在 `composer.json` 中增加依赖后执行 `composer update`：

```
{
    "require": {
        "fcwh/shop_sdk": "^1.0"
    }
}
```

若使用公司私有 Packagist，需在 `composer.json` 中配置 `repositories` 指向本包仓库或私有源。

### 三、配置与创建客户端

[](#三配置与创建客户端)

**所有密钥、推广位等均由合作方自行传入**，SDK 不内置任何账号信息。合作方从各自业务配置（环境变量、配置中心、数据库等）中读取后，组装成 `Config` 再创建 `ShopUnionClient`。

```
use ShopUnion\SDK\Config;
use ShopUnion\SDK\ShopUnionClient;

// 从合作方自己的配置源读取（示例为数组，实际可来自 .env、数据库等）
$options = [
    'taobao' => [
        'app_key'    => getenv('TAOBAO_APP_KEY') ?: '你的淘宝app_key',
        'app_secret' => getenv('TAOBAO_APP_SECRET') ?: '你的淘宝app_secret',
        'pid'        => getenv('TAOBAO_PID') ?: 'mm_xxx_xxx_xxx',  // 或 adzone_id
    ],
    'pinduoduo' => [
        'client_id'     => getenv('PDD_CLIENT_ID') ?: '你的拼多多client_id',
        'client_secret' => getenv('PDD_CLIENT_SECRET') ?: '你的拼多多client_secret',
        'pid'           => getenv('PDD_PID') ?: '你的推广位pid',
    ],
    'jd' => [
        'app_key'     => getenv('JD_APP_KEY') ?: '你的京东app_key',
        'app_secret'  => getenv('JD_APP_SECRET') ?: '你的京东app_secret',
        'union_id'    => getenv('JD_UNION_ID') ?: '联盟ID',
        'position_id' => getenv('JD_POSITION_ID') ?: '推广位ID',
    ],
];

$config = new Config($options);
$client = new ShopUnionClient($config);
```

**说明：**

- 只需配置将要使用的平台，未使用的平台可省略。
- 淘宝：必填 `app_key`、`app_secret`；转链/物料等需 `pid`（或 `adzone_id`）。
- 拼多多：必填 `client_id`、`client_secret`；转链需 `pid`。
- 京东：必填 `app_key`、`app_secret`；转链需 `union_id`、`position_id`。

### 四、调用方式约定

[](#四调用方式约定)

- **入口**：统一使用 `ShopUnionClient` 实例。
- **选平台**：通过 `$client->taobao()`、`$client->pinduoduo()`、`$client->jd()` 选择淘宝联盟、多多进宝、京东联盟。
- **选能力**：在对应平台对象上调用具体方法，传入 `array` 参数，返回值为接口原始结构的 `array`（由各联盟 API 文档定义）。

**通用调用形式：**

```
$result = $client->平台()->方法名([
    '参数名' => '参数值',
    // ...
]);
```

合作方只需按「平台 → 方法名 → 参数」即可完成调用，无需关心签名、网关等底层细节。

### 五、各平台能力与调用示例

[](#五各平台能力与调用示例)

#### 1. 淘宝联盟 `$client->taobao()`

[](#1-淘宝联盟-client-taobao)

方法说明主要参数`materialSearch`物料搜索（关键词商品）keyword, page\_no, page\_size`linkConvert`长链转短链url 或 urls（数组）`shopSearch`店铺搜索keyword, page\_no, page\_size`itemDetail`商品详情（升级版，最多20个）num\_iids 或 item\_id`promotionGoodsList`权益物料商品列表page\_num, page\_size, promotion\_id(默认62191)`createTpwd`生成淘口令url（推广链接）`materialCategoryList`物料分类列表（获取物料 id）subject(默认1), material\_type(默认1)`materialRecommendList`按物料 id 获取商品列表material\_id（来自分类列表）, page\_no, page\_size```
// 示例：关键词搜索
$result = $client->taobao()->materialSearch([
    'keyword'   => '手机',
    'page_no'   => 1,
    'page_size' => 20,
]);

// 示例：长链转短链
$result = $client->taobao()->linkConvert([
    'url' => 'https://s.click.taobao.com/xxx',
]);

// 示例：先取物料分类，再按物料 id 取商品列表
$categories = $client->taobao()->materialCategoryList(['subject' => 1, 'material_type' => 1]);
$goods      = $client->taobao()->materialRecommendList([
    'material_id' => 27939,
    'page_no'     => 1,
    'page_size'   => 20,
]);
```

#### 2. 多多进宝 `$client->pinduoduo()`

[](#2-多多进宝-client-pinduoduo)

方法说明主要参数`materialSearch`物料搜索keyword, page, page\_size`linkConvert`链接转换goods\_sign\_list 或 goods\_id\_list, pid(可选)`shopSearch`店铺搜索keyword, page, page\_size`itemDetail`商品详情goods\_sign\_list 或 goods\_id\_list```
$result = $client->pinduoduo()->materialSearch([
    'keyword'   => '手机',
    'page'      => 1,
    'page_size' => 20,
]);
$result = $client->pinduoduo()->linkConvert([
    'goods_sign_list' => ['xxx'],
]);
```

#### 3. 京东联盟 `$client->jd()`

[](#3-京东联盟-client-jd)

方法说明主要参数`materialSearch`物料搜索keyword, page\_index, page\_size`linkConvert`链接转换material\_id（商品链接等）`shopSearch`店铺/商品搜索同 materialSearch`itemDetail`商品详情sku\_ids```
$result = $client->jd()->materialSearch([
    'keyword'    => '手机',
    'page_index' => 1,
    'page_size'  => 20,
]);
$result = $client->jd()->linkConvert([
    'material_id' => 'https://item.jd.com/100012345678.html',
]);
```

### 六、返回值与异常

[](#六返回值与异常)

- **成功**：各方法返回 `array`，结构以对应联盟 API 文档为准（如 `result_list`、`data`、`results` 等），合作方按文档解析即可。
- **失败**：SDK 会抛出 `ShopUnion\SDK\Exception\SdkException`。合作方应捕获该异常，并根据需要记录日志、返回错误码或提示信息。

```
use ShopUnion\SDK\Exception\SdkException;

try {
    $result = $client->taobao()->materialSearch(['keyword' => '手机']);
    // 使用 $result 做业务逻辑
} catch (SdkException $e) {
    // 错误信息
    $message = $e->getMessage();
    // 平台错误码（若有）
    $codeFromApi = $e->getCodeFromApi();
    // 原始响应（便于排查）
    $raw = $e->getRawResponse();
    // 合作方在此处理：打日志、返回统一错误格式等
}
```

### 七、推荐业务流程示例（淘宝）

[](#七推荐业务流程示例淘宝)

合作方常见流程：获取物料/商品 → 取详情 → 转链 → 生成淘口令用于传播。

```
// 1）获取物料分类下的商品列表
$list = $client->taobao()->materialRecommendList([
    'material_id' => 27939,
    'page_no'     => 1,
    'page_size'   => 20,
]);

// 2）根据商品 id 查详情（示例：取列表中第一个商品 id）
// $itemId = $list['result_list'][0]['item_id'] ?? null;

// 3）长链转短链（合作方自己的推广长链）
$short = $client->taobao()->linkConvert([
    'url' => 'https://s.click.taobao.com/xxx',
]);

// 4）生成淘口令用于分享
$tpwd = $client->taobao()->createTpwd([
    'url' => $short['results'][0]['content'] ?? 'https://s.click.taobao.com/xxx',
]);
// 淘口令文案：$tpwd['data']['model'] 或 $tpwd['data']['password_simple']
```

合作方按自身业务选择其中步骤或调整顺序即可。

---

配置项说明（可选阅读）
-----------

[](#配置项说明可选阅读)

平台配置键必填说明淘宝app\_key, app\_secret是开放平台应用凭证淘宝pid 或 adzone\_id转链/物料必填推广位，pid 格式 mm\_账户\_媒体\_推广位淘宝session部分接口会员授权 session拼多多client\_id, client\_secret是开放平台应用凭证拼多多pid转链必填推广位京东app\_key, app\_secret是开放平台应用凭证京东union\_id, position\_id转链必填联盟 ID、推广位 ID---

高级用法
----

[](#高级用法)

**自定义 HTTP 客户端**（如超时、代理）：实现 `ShopUnion\SDK\Http\HttpClientInterface` 后注入：

```
$client = new ShopUnionClient($config, $yourHttpClient);
```

**直接调平台原始 API**（淘宝）：`$client->taobao()->call('taobao.xxx.xxx', ['param' => 'value']);`

---

发布与版本
-----

[](#发布与版本)

- 本包可发布至 [packagist.org](https://packagist.org) 或公司私有 Packagist。
- 版本发布：打 tag（如 `v1.0.0`）并推送到仓库后，合作方通过 `composer update fcwh/shop_sdk` 获取新版本。

许可证
---

[](#许可证)

MIT

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance52

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/e2d3296701ca14aa109dd9a9c242f73af9015143c9a288d31dcf3d519ef15b5b?d=identicon)[yangxiaozhan](/maintainers/yangxiaozhan)

---

Top Contributors

[![yangxiaozhan](https://avatars.githubusercontent.com/u/24222458?v=4)](https://github.com/yangxiaozhan "yangxiaozhan (1 commits)")

### Embed Badge

![Health badge](/badges/fcwh-shop-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/fcwh-shop-sdk/health.svg)](https://phpackages.com/packages/fcwh-shop-sdk)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k15](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)