README

PHP沃尔玛API

一个用于连接到美国、加拿大和墨西哥沃尔玛市场、1P供应商和内容提供者API的PHP库。

功能

支持截至2023年8月17日的所有沃尔玛API操作，包括市场卖家、1P供应商和内容提供者（有关所有调用文档的链接，请参阅此处）
支持美国、加拿大和墨西哥市场
自动处理沃尔玛使用的所有认证形式（基本认证、访问令牌和请求签名），配置简单

安装

composer require highsidelabs/walmart-api

为什么创建这个库？

现有的PHP沃尔玛客户端库要么不完整，要么过时，或者两者兼而有之。这个库旨在提供完整、最新且易于使用的接口，用于所有沃尔玛的卖家和供应商API - 而不仅仅是市场API（其他包仅覆盖这一点）。我们创建它来满足我们自己的需求。

入门

先决条件

您需要一些东西才能开始

沃尔玛卖家和/或供应商账户
沃尔玛客户端ID/客户端密钥对，以及/或沃尔玛消费者ID和私钥

设置

Configuration构造函数接受三个参数，涵盖了您访问沃尔玛API所需的所有凭证

客户端ID
客户端密钥
可选的附加配置参数数组

use Walmart\Configuration;

$clientId = '<YOUR CLIENT ID>';
$clientSecret = '<YOUR CLIENT SECRET>';
$config = new Configuration([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
]);

如果您是在美国销售的Marketplace卖家（使用此API的大多数人很可能都是），那么这就是您开始调用Marketplace API所需进行的所有配置。如果您想调用1P供应商或内容提供者API，或者如果您在美国之外销售商品并需要调用Marketplace API，您将需要提供额外的配置参数，这些参数在下面的配置部分中详细说明。

基本用法

创建Configuration类的实例后，您就可以开始调用Walmart API了。Walmart类提供了一个简单的接口，用于从三个主要API类别（Marketplace、1P供应商、内容提供者）中检索任何API类的实例。例如，要检索Marketplace Authentication API的实例并检查您的身份验证令牌的状态，您可以执行以下操作

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Configuration([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
]);
$authApi = Walmart::marketplace($config)->auth();

// $authApi is an instance of Walmart\Apis\MP\US\AuthenticationApi
$tokenDetail = $authApi->getTokenDetail();
$tokenStatus = $tokenDetail->isValid;
var_dump($tokenStatus);

同样，其他API类别可以通过Walmart::supplier()和Walmart::contentProvider()方法访问。

文档

配置

Configuration类用于配置客户端库。它只接受一个选项数组作为其唯一参数，该数组可以包含以下键

clientId：您的Walmart客户端ID
clientSecret：您的Walmart客户端密钥
country：您正在销售的国家。必须是Walmart\Enums\Country中的值之一：Country::US、Country::CA或Country::MX。默认为Country::US。
consumerId：您的Walmart消费者ID。如果您正在向使用基于签名的身份验证的端点发送请求，则需要此选项（请参阅授权部分）
privateKey：您的Walmart私钥。与consumerId选项的要求相同。
channelType：您在入职期间收到的渠道类型值。在加拿大使用时为必需。
partnerId：您的Walmart合作伙伴ID。在使用供应商API时为必需。
accessToken：一个包含访问令牌及其过期时间的Walmart\AccessToken实例。如果提供，则将使用该令牌而不是客户端ID和密钥来验证API调用，直到令牌过期。如果您想重复使用从Walmart获取的访问令牌，这很有用。有关访问令牌身份验证的更多详细信息，请参阅下面。

如果您尝试实例化一个在指定国家不支持API类的实例，将抛出异常。

使用API类

API类分为三个类别：Marketplace、1P供应商和内容提供者。每个类别都有自己的命名空间，每个国家都有自己的子命名空间。例如，加拿大Marketplace API位于Walmart\Apis\MP\CA命名空间中，而美国1P供应商API位于Walmart\Apis\Supplier\US命名空间中。

要创建API类的实例，首先使用Walmart::marketplace()、Walmart::contentProvider()和Walmart::supplier()方法。这三个方法都接受一个参数：一个Walmart\Configuration实例。这些方法中的每一个都返回一个辅助类，该类提供对指定国家（默认为美国）中该类别所有API类的访问。有关此库支持的所有API的列表，请参阅下面的支持API段部分。

一旦拥有一个API类的实例，您就可以调用在文档中定义的任何端点方法。API类文档根据API类别和国家/地区进行划分，因为相同的API在不同的国家/地区可能有不同的端点以及/或参数。确保您查看的是您实际销售所在国家的正确文档！

一些端点有很多参数。如果您使用的是PHP 8或更高版本，可以使用命名参数使您的代码更具可读性。例如，美国市场的Marketplace Feeds API有一个getAllItems调用，它最多可以接受7个参数。如果您只想传递其中的一些参数，可以这样做

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Configuration([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
]);
$itemsApi = Walmart::marketplace($config)->items();

$response = $itemsApi->getAllItems(
    sku: '1234567890',
    lifecycleStatus: 'PUBLISHED',
    variantGroupId: '9876543210'
);

而不是这样

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Configuration([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
]);
$itemsApi = Walmart::marketplace($config)->items();

$response = $itemsApi->getAllItems(
    null,  // $nextCursor
    '1234567890',  // $sku,
    null,  // $offset
    null,  // $limit
    'PUBLISHED',  // $lifecycleStatus
    null,  // $publishedStatus
    '9876543210'  // $variantGroupId
);

API方法通常将模型类作为参数，并以API响应的形式返回它们——让我们看看模型类是如何工作的。

使用模型类

为了表示API处理和返回的各种数据结构，这个库使用模型类。每个模型类代表一个单一的数据结构，它有一个构造函数，该构造函数接收一个包含数据的关联数组。模型类文档根据API类别、国家/地区和API类进行划分。每个模型类的文档都嵌套在对应于模型类在src/Models文件夹中位置的docs/Models文件夹中。例如，美国市场授权API的getTokenDetail方法的响应模型是Walmart\Models\MP\US\Authorization\TokenDetailResponse，文档位于docs/Models/MP/US/Authorization/TokenDetailResponse.md。

授权

沃尔玛为其API使用三种不同的认证形式：基本认证、访问令牌和请求签名。这个库自动处理所有这三种认证，所以您不必过多考虑……但如果您对此感兴趣，请继续阅读。

基本认证

这是标准、最简单的认证形式。它使用传递给Configuration构造函数的沃尔玛客户端ID和客户端密钥来生成授权头值。它还用于在必要时生成访问令牌，这就是为什么这两个参数是Configuration构造函数的两个必需参数。

访问令牌认证

对于大多数市场API，沃尔玛使用访问令牌认证。访问令牌是一个短期令牌（15分钟），由沃尔玛使用客户端ID和客户端密钥生成，然后用于认证API调用。这个库自动处理访问令牌的生成和续订，所以您不必担心。如果您想重用已从沃尔玛获取的访问令牌，您可以通过accessToken选项将其传递给Configuration构造函数。

请求签名认证

除了市场API之外，沃尔玛还使用请求签名认证来处理大多数其他API。这只是一个作为头传递的值，它是使用请求方法、路径、时间戳以及您的消费者ID和私钥生成的。如果您正在制作涉及签名认证的请求，您需要将privateKey和consumerId选项传递给Configuration构造函数的选项数组。

调试模式

要获取API请求时的调试输出，您可以调用$config->setDebug()。默认情况下，调试输出通过php://output发送到stdout，但您可以使用$config->setDebugFile('log/file/path.log')将其重定向到文件。

require_once __DIR__ . '/vendor/autoload.php';

use Walmart\Configuration;

$config = new Configuration([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
]);
$config->setDebug(true);
// To redirect debug info to a file:
$config->setDebugFile('debug.log');

支持的API段

这是本库支持的所有API的详尽列表，按API类别组织。并非所有API在所有国家/地区都受支持。有关每个API的更多信息，请参阅沃尔玛开发者门户。

市场

品类推荐API: Walmart::marketplace($config)->assortmentRecommendations() (仅限美国)
认证API: Walmart::marketplace($config)->auth() (墨西哥，美国)
事件API: Walmart::marketplace($config)->events() (仅限加拿大)
数据流API: Walmart::marketplace($config)->feeds() (加拿大，墨西哥，美国)
履约API: Walmart::marketplace($config)->fulfillment() (美国)
洞察API: Walmart::marketplace($config)->insights() (仅限美国)
国际运输API: Walmart::marketplace($config)->internationalShipping() (加拿大，墨西哥)
库存API: Walmart::marketplace($config)->inventory() (加拿大，墨西哥，美国)
商品API: Walmart::marketplace($config)->items() (加拿大，墨西哥，美国)
延迟时间API: Walmart::marketplace($config)->lagTime() (仅限美国)
商品列表质量API: Walmart::marketplace($config)->listingQuality() (仅限美国)
通知API: Walmart::marketplace($config)->notifications() (仅限美国)
请求报告API: Walmart::marketplace($config)->onRequestReports() (仅限美国)
订单API: Walmart::marketplace($config)->orders() (加拿大，墨西哥，美国)
价格API: Walmart::marketplace($config)->prices() (加拿大，墨西哥，美国)
促销API: Walmart::marketplace($config)->promotions() (加拿大，美国)
报告API: Walmart::marketplace($config)->reports() (加拿大，墨西哥，美国)
退货API: Walmart::marketplace($config)->returns() (墨西哥，美国)
评论API: Walmart::marketplace($config)->reviews() (仅限美国)
规则API: Walmart::marketplace($config)->rules() (仅限美国)
设置API: Walmart::marketplace($config)->settings() (仅限美国)
工具API: Walmart::marketplace($config)->utilities() (仅限美国)

1P供应商

注意：一票供应商API目前仅在美国可用。

成本API: Walmart::supplier($config)->cost()
数据流API: Walmart::supplier($config)->feeds()
库存API: Walmart::supplier($config)->inventory()
商品API: Walmart::supplier($config)->items()
延迟时间API: Walmart::supplier($config)->lagTime()
订单API: Walmart::supplier($config)->orders()
报告API: Walmart::supplier($config)->reports()

内容提供者

注意：内容提供者API目前仅在美国提供。

数据流API: Walmart::contentProvider($config)->feeds()

贡献

感谢您一直阅读到这里！我们欢迎您的贡献……开源世界因像您这样的人而运转。

拉取请求

在提交任何重大功能工作的拉取请求之前，请通过（问题）进行询问。花了大量精力却因为非代码质量原因被拒绝是很令人沮丧的。（作者注：不知道为什么我知道。）话虽如此，我们欢迎任何人的贡献，并将尽力合并您的代码。请耐心等待——我们并没有忽略您，但这可能需要一些时间才能处理您的PR。

在提交PR之前，请使用composer lint格式化您的代码。

highsidelabs / walmart-api

维护者

详情