README

一个用于连接 Amazon Selling Partner API 的 PHP 库。

赞助商

为以下公司提供动力...

如果您觉得这个库很有用，请考虑成为赞助商，或者通过下面的按钮进行一次性捐赠。我非常感激您提供的任何和支持！

特性

支持所有 Selling Partner API 操作（针对卖家和供应商）截至 2021 年 7 月 2 日（在此处查看所有调用的文档链接）
支持使用 IAM 用户和 IAM 角色ARN制作的应用程序（文档）
自动生成所有需要它们的所有调用的受限制数据令牌--不需要额外的 Tokens API 调用
包括一个用于上传和下载 feed/report 文档的 Document 辅助类

安装

composer require forum-brands/selling-partner-api

入门

先决条件

您需要一些东西才能开始

Selling Partner API 开发者账户
配置了用于与 Selling Partner API 一起使用的 AWS IAM 用户或角色
Selling Partner API 应用程序

如果您想了解更多关于如何设置这些内容的信息，请查看这篇文章。它提供了整个设置过程的详细说明。

设置

Configuration 构造函数接受一个参数：一个关联数组，包含连接到 Selling Partner API 所需的所有配置信息

$config = new SellingPartnerApi\Configuration([
    "lwaClientId" => "<LWA client ID>",
    "lwaClientSecret" => "<LWA client secret>",
    "lwaRefreshToken" => "<LWA refresh token>",
    "awsAccessKeyId" => "<AWS access key ID>",
    "awsSecretAccessKey" => "<AWS secret access key>",
    // If you're not working in the North American marketplace, change
    // this to another endpoint from lib/Endpoint.php
    "endpoint" => SellingPartnerApi\Endpoint::NA,
]);

如果您使用 IAM 角色ARN而不是用户ARN创建了 Selling Partner API 应用程序，请在配置数组中传递该角色 ARN

$config = new SellingPartnerApi\Configuration([
    "lwaClientId" => "<LWA client ID>",
    "lwaClientSecret" => "<LWA client secret>",
    "lwaRefreshToken" => "<LWA refresh token>",
    "awsAccessKeyId" => "<AWS access key ID>",
    "awsSecretAccessKey" => "<AWS secret access key>",
    // If you're not working in the North American marketplace, change
    // this to another endpoint from lib/Endpoint.php
    "endpoint" => SellingPartnerApi\Endpoint::NA,
    "roleArn" => "<Role ARN>",
]);

存在用于 Configuration 类的 lwaClientId、lwaClientSecret、lwaRefreshToken、awsAccessKeyId、awsSecretAccessKey 和 endpoint 属性的获取器和设置器方法。方法名称与它们交互的属性名称相匹配：getLwaClientId、setLwaClientId、getLwaClientSecret 等。

然后可以将 $config 传递给任何 SellingPartnerApi\Api\*Api 类的构造函数。请参阅 示例 部分，以获取完整示例。

配置选项

传递给 Configuration 构造函数的数组接受以下键

lwaClientId (字符串)：必需。用于执行 API 请求的 SP API 应用程序的 LWA 客户端 ID。
lwaClientSecret (字符串)：必需。用于执行 API 请求的 SP API 应用程序的 LWA 客户端密钥。
lwaRefreshToken (字符串)：用于执行 API 请求的 SP API 应用程序的 LWA 刷新令牌。必需，除非您只使用 Configuration 实例调用无需授权的操作。
awsAccessKeyId (字符串)：必需。具有 SP API ExecuteAPI 权限的 AWS IAM 用户访问密钥 ID。
awsSecretAccessKey (字符串)：必需。具有 SP API ExecuteAPI 权限的 AWS IAM 用户密钥。
endpoint (数组)：必需。包含一个 url 键（端点 URL）和一个 region 键（AWS 区域）的数组。在 lib/Endpoint.php 中有这些数组的预定义常量：（NA、EU、FE 和 NA_SANDBOX、EU_SANDBOX、FE_SANDBOX。更多详情请见此处。
accessToken (字符串)：由刷新令牌生成的访问令牌。
accessTokenExpiration (整数)：与 accessToken 过期时间对应的 Unix 时间戳。如果提供了 accessToken，则需要 accessTokenExpiration（反之亦然）。
onUpdateCredentials (可调用函数|闭包)：当生成新的访问令牌时调用的回调函数。函数应接受一个类型为 SellingPartnerApi\Credentials 的单个参数。
roleArn (字符串)：如果您使用 AWS IAM 角色ARN（而非用户ARN）设置了您的 SP API 应用程序，请在此处传递该 ARN。

示例

此示例假设您有权访问 Seller Insights 卖家合作伙伴 API 角色，但通用格式适用于任何卖家合作伙伴 API 请求。

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use SellingPartnerApi\Api;
use SellingPartnerApi\Configuration;
use SellingPartnerApi\Endpoint;

$config = new Configuration([
    "lwaClientId" => "amzn1.application-oa2-client.....",
    "lwaClientSecret" => "abcd....",
    "lwaRefreshToken" => "Aztr|IwEBI....",
    "awsAccessKeyId" => "AKIA....",
    "awsSecretAccessKey" => "ABCD....",
    // If you're not working in the North American marketplace, change
    // this to another endpoint from lib/Endpoint.php
    "endpoint" => Endpoint::NA
]);

$api = new Api\SellersApi($config);
try {
    $result = $api->getMarketplaceParticipations();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SellersApi->getMarketplaceParticipations: ', $e->getMessage(), PHP_EOL;
}

?>

支持的 API 段

卖家 API

供应商 API

受限操作

当调用受限操作时，会自动生成受限数据令牌（RDT）。如果您调用接受 dataElements 参数的受限操作，可以将 dataElements 值作为参数传递给 API 调用。请参阅 getOrders、getOrder 和 getOrderItems 文档，了解如何将这些调用传递 dataElements 值。撰写本文时，这些是唯一接受 dataElements 值的受限操作。）

上传和下载文档

Feeds和Reports API包括涉及上传和下载文件到和从亚马逊的操作。亚马逊加密他们生成的所有文件，并要求所有上传的文件都进行加密。《SellingPartnerApi\Document》类处理所有加密/解密操作，前提是有一个《Model\Reports\ReportDocument》、《Model\Feeds\FeedDocument》或《Model\Feeds\CreateFeedDocumentResponse》类实例。这些类的实例包含在亚马逊返回的响应中，当你调用《getReportDocument》、《getFeedDocument》和《createFeedDocument》端点时，分别。

下载报告文件

use SellingPartnerApi\Api\ReportsApi;
use SellingPartnerApi\ReportType;

// Assume we've already fetched a report document ID, and that a $config object was defined above
$documentId = 'foo.1234';
$reportType = ReportType::GET_FLAT_FILE_OPEN_LISTINGS_DATA;

$reportsApi = new ReportsApi($config);
$reportDocumentInfo = $reportsApi->getReportDocument($documentId, $reportType['name']);

$docToDownload = new SellingPartnerApi\Document($reportDocumentInfo, $reportType);
$contents = $docToDownload->download();  // The raw report text
/*
 * - Array of associative arrays, (each sub array corresponds to a row of the report) if content type is ContentType::TAB or ContentType::CSV
 * - A nested associative array (from json_decode) if content type is ContentType::JSON
 * - The raw report data if content type is ContentType::PLAIN or ContentType::PDF
 * - PHPOffice Spreadsheet object if content type is ContentType::XLSX
 * - SimpleXML object if the content type is ContentType::XML
 */
$data = $docToDownload->getData();
// ... do something with report data

上传饲料文件

use SellingPartnerApi\Api\FeedsApi;
use SellingPartnerApi\FeedType;
use SellingPartnerApi\Model\Feeds;

$feedType = FeedType::POST_PRODUCT_PRICING_DATA;
$feedsApi = new FeedsApi($config);

// Create feed document
$createFeedDocSpec = new Feeds\CreateFeedDocumentSpecification(['content_type' => $feedType['contentType']]);
$feedDocumentInfo = $feedsApi->createFeedDocument($createFeedDocSpec);
$feedDocumentId = $feedDocumentInfo->getFeedDocumentId();

// Upload feed contents to document
$feedContents = file_get_contents('<your/feed/file.xml>');
// The Document constructor accepts a custom \GuzzleHttp\Client object as an optional 3rd parameter. If that
// parameter is passed, your custom Guzzle client will be used when uploading the feed document contents to Amazon.
$docToUpload = new SellingPartnerApi\Document($feedDocumentInfo, $feedType);
$docToUpload->upload($feedContents);

// ... call FeedsApi::createFeed() with $feedDocumentId

下载饲料结果文件

这和下载报告文件非常相似

use SellingPartnerApi\Api\FeedsApi;
use SellingPartnerApi\FeedType;

$feedType = FeedType::GET_FLAT_FILE_OPEN_LISTINGS_DATA;
$feedsApi = new FeedsApi($config);

// ...
// Create and upload a feed document, and wait for it to finish processing
// ...

$feedId = '1234567890';  // From the createFeed call
$feed = $api->getFeed($feedId);

$feedResultDocumentId = $feed->getResultFeedDocumentId();
$feedResultDocument = $api->getFeedDocument($feedResultDocumentId);

$doc = new Document($documentInfo, $feedType);

$docToDownload = new SellingPartnerApi\Document($feedResultDocument, $feedType);
$contents = $docToDownload->download();  // The raw report data
$data = $docToDownload->getData();  // Parsed/formatted report data

模型

大多数操作都与其一个或多个模型相关联。这些模型是包含进行某种类型API请求所需数据的类，或者包含特定请求类型返回的数据的类。所有模型都共享相同的一般接口：你可以在初始化期间指定所有模型属性，或者使用setter方法在实际设置每个属性。以下是一个使用Service API的《Buyer》模型的示例（《docs》链接，（《source》链接））。

《Buyer》模型有四个属性：《buyer_id》、《name》、《phone》和《is_prime_member》。（如果你想知道如何自己确定模型具有哪些属性，请参阅上面的《docs》链接。）要创建一个所有这些属性都设置的《Buyer》模型实例

$buyer = new SellingPartnerApi\Model\Service\Buyer([
    "buyer_id" => "ABCDEFGHIJKLMNOPQRSTU0123456",
    "name" => "Jane Doe",
    "phone" => "+12345678901",
    "is_prime_member" => true
]);

或者，你可以创建一个《Buyer》模型实例，然后填充其字段

$buyer = new SellingPartnerApi\Model\Service\Buyer();
$buyer->setBuyerId("ABCDEFGHIJKLMNOPQRSTU0123456");
$buyer->setName("Jane Doe");
$buyer->setPhone("+12345678901");
$buyer->setIsPrimeMember(true);

每个模型也都有你可能期望的getter方法

$buyer->getBuyerId();        // -> "ABCDEFGHIJKLMNOPQRSTU0123456"
$buyer->getName();           // -> "Jane Doe"
$buyer->getPhone();          // -> "+12345678901"
$buyer->getIsPrimeMember();  // -> true

模型可以（并且通常确实）将其他模型作为属性

$serviceJob = new SellingPartnerApi\Model\Service\Buyer([
    // ...
    "buyer" => $buyer,
    // ...
]);

$serviceJob->getBuyer();             // -> [Buyer instance]
$serviceJob->getBuyer()->getName();  // -> "Jane Doe"

响应头

亚马逊在每个SP API响应中包含了一些有用的头信息。如果你出于任何原因需要这些，你可以通过在响应对象上调用《getHeaders()`》来获取响应头的关联数组。例如

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use SellingPartnerApi\Api;
use SellingPartnerApi\Configuration;
use SellingPartnerApi\Endpoint;

$config = new Configuration([...]);
$api = new Api\SellersApi($config);
try {
    $result = $api->getMarketplaceParticipations();
    $headers = $result->getHeaders();
    print_r($headers);
} catch (Exception $e) {
    echo 'Exception when calling SellersApi->getMarketplaceParticipations: ', $e->getMessage(), PHP_EOL;
}

forum-brands / selling-partner-api

维护者

详细信息