jason6688/walmart-api-client

Walmart 的 Marketplace、1P 供应商和内容提供者 API 的 PHP 客户端。

维护者

详情

github.com/jason6688/walmart-api-client

源代码

问题

安装: 3

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 0

开放问题: 0

0.0.1 2024-08-29 09:40 UTC

Requires

Requires (Dev)

BSD-3-Clause 507fb83b843c944f22f0a0c9f2aff08591658790

  • Jason <284469828.woop@qq.com>

restecommerceapisdkwalmartwalmart-apiwalmart-marketplace-apiwalmart-content-providers-apiwalmart-1p-suppliers-api

This package is auto-updated.

Last update: 2024-09-29 09:48:05 UTC

README

一个连接到 Walmart 的 Marketplace、1P 供应商 和 内容提供者 API 的 PHP 库，支持美国、加拿大和墨西哥。

功能

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

安装

composer require jason6688/walmart-api-client

为什么制作这个库？

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

目录

入门

先决条件

要开始，您需要一些东西

  • 一个 Walmart 卖家和一个/或供应商账户
  • 一个 Walmart 客户端 ID/客户端密钥对，以及/或一个 Walmart 消费者 ID 和私钥

设置

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

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

使用 API 类

API 类分为三个类别：市场、1P 供应商和内容提供商。每个类别都有自己的命名空间，每个国家都有自己的子命名空间。例如，加拿大的市场 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 类别和随后是国家划分，因为相同的 API 在不同的国家可能有不同的端点和/或参数。确保您查看的是您实际销售所在国家的正确文档！

一些端点有非常多的参数。如果您正在使用 PHP 8 或更高版本，您可以使用命名参数来使您的代码更易读。例如，美国的市场 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文件夹中。例如，美国Marketplace Authorization API的getTokenDetail方法的响应模型为Walmart\Models\MP\US\Authorization\TokenDetailResponse，文档位于docs/Models/MP/US/Authorization/TokenDetailResponse.md。

授权

沃尔玛为其API使用三种不同的认证方式：基本认证、访问令牌和请求签名。这个库自动处理这三种认证，所以你不必过多考虑它们……但如果你想知道它是如何工作的，请继续阅读。

基本身份验证

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

访问令牌身份验证

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

请求签名身份验证

对于Marketplace 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的更多信息，请参阅沃尔玛开发者门户。

Marketplace

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

1P 供应商

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

内容提供者

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

  • Feeds API： Walmart::contentProvider($config)->feeds()

贡献

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

拉取请求

在提交任何重大功能工作的拉取请求之前，请先通过问题（issue）进行咨询。投入了大量精力，结果却因为非代码质量原因被拒绝，这种感觉真的很糟糕。（作者注：我不太清楚我是怎么知道的。）尽管如此，我们欢迎任何人的贡献，并将尽力将您的代码合并。请耐心等待——我们并没有忽视您，但处理您的PR可能需要一些时间。

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